@instruments/materialgraph 0.33.0 → 0.36.0

package/webmcp.generated.js

@@ -1,12 +1,7 @@
 const json = [
-    "[{\"annotations\":{\"readOnlyHint\":true,\"untrustedContentHint\":true},\"description\":\"The stable, authenticated search endpoint, POST JSON-body form: `text`, a raw `image` (`url` or `base64`, embedded server-side) or a `similarTo` seed (`variantId`, `materialBankId` or a pre-computed image-space `vector`), a `category`, `filters` and a `corpusScope`, and `limit`, `cursor`, `view` and `explain`. Every request runs the one search over the index (ADR 0031): the query's plan is read from the cache or the dictionaries (brands, categories, colours and attributes are read from the words), one query runs on the search index, and the page is hydrated in the order the index gave. No model runs while the caller waits. A word no material carries may be corrected first; the response then carries `correctedQuery: { from, to }` and its `note` says which results it shows. Results are one per product. A caller may also send a `category` (a hard gate that replaces the category the words were read as), attribute `filters` (hard token sets: a term, a term set, an exclusion or a presence check; OR within one attribute, AND across attributes) and a `corpusScope`. Each becomes a field of the query's plan and runs in the same index query; none of them changes the order. A category or filters can define a page without words. `explain.plan.plan` shows the plan with them on it, and `explain.plan.signature` covers them, so one request gives one signature. A look-alike search reads the seed's nearest materials from the image namespace; the index keeps those inside whatever the words filter to and orders them by image similarity. A field the contract does not declare is a 400 naming it, with near misses; weights, mood, colours, text modes and sorts are no longer part of the request, and brands and colours are read from `text`. `?explain=1` on the query string is honoured as a shorthand for body `explain: true`; an explicit body `explain` (true or false) always wins. The `query` echo never carries raw image bytes or a vector, only `{ type }`. Send `Accept: application/x-ndjson` for one `{ type: \\\"response\\\", status, body }` line carrying exactly what the buffered form answers. Search is dynamic, so success responses carry `Cache-Control: no-store`. Requires the `mg:read` bearer scope.\",\"inputSchema\":{\"$ref\":\"#/$defs/schema0\",\"$defs\":{\"schema0\":{\"type\":\"object\",\"properties\":{\"brands\":{\"description\":\"Brands the page must come from: canonical brand ids, exact slugs (\\\"sherwin-williams\\\") or exact display names (\\\"Sherwin-Williams\\\"). They replace the brands `text` was read as. An empty list is the same request as omitting it — every brand. An unrecognised value is a 400 naming it; a display name shared by more than one brand is a 400 naming the exact slugs to choose between; a brand MaterialGraph holds no materials under is a 400 naming a populated sibling when one exists.\",\"maxItems\":50,\"type\":\"array\",\"items\":{\"type\":\"string\",\"minLength\":1}},\"category\":{\"type\":\"object\",\"properties\":{\"filter\":{\"minItems\":1,\"maxItems\":50,\"type\":\"array\",\"items\":{\"type\":\"string\",\"minLength\":1},\"description\":\"Only these public categories are returned: category-group or product-type display names (case-insensitive) or taxonomy keys. A group stands for every product type under it. An unknown value is a 400 listing every valid name.\"}},\"required\":[\"filter\"],\"additionalProperties\":false,\"description\":\"A hard category gate. It replaces the category the words were read as.\"},\"colour\":{\"anyOf\":[{\"type\":\"object\",\"properties\":{\"hex\":{\"type\":\"string\",\"pattern\":\"^#?[0-9a-f]{6}$\",\"description\":\"The colour to order by, e.g. \\\"#9CAF88\\\".\"},\"oklab\":{\"type\":\"array\",\"prefixItems\":[{\"type\":\"number\"},{\"type\":\"number\"},{\"type\":\"number\"}],\"items\":false,\"minItems\":3,\"maxItems\":3},\"range\":{\"type\":\"object\",\"properties\":{\"chroma\":{\"type\":\"array\",\"prefixItems\":[{\"type\":\"number\"},{\"type\":\"number\"}],\"items\":false,\"minItems\":2,\"maxItems\":2},\"hue\":{\"anyOf\":[{\"type\":\"array\",\"prefixItems\":[{\"type\":\"number\"},{\"type\":\"number\"}],\"items\":false,\"minItems\":2,\"maxItems\":2},{\"type\":\"null\"}]},\"lightness\":{\"type\":\"array\"",
-    ",\"prefixItems\":[{\"type\":\"number\"},{\"type\":\"number\"}],\"items\":false,\"minItems\":2,\"maxItems\":2}},\"required\":[\"chroma\",\"hue\",\"lightness\"],\"additionalProperties\":false}},\"required\":[\"hex\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"variantId\":{\"type\":\"string\",\"minLength\":1,\"description\":\"A Variant whose own colour to order by: materials the same colour as this one. A Variant with no colour on the index is a 400.\"}},\"required\":[\"variantId\"],\"additionalProperties\":false}],\"description\":\"Order the page by a colour: `hex`, or `variantId` for the colour of an existing Variant. The page is the colour's family, nearest first by OKLab distance; it replaces any colour read from `text`.\"},\"corpusScope\":{\"type\":\"string\",\"enum\":[\"all\",\"samplizeCatalogue\",\"materialBankOrderable\",\"materialBankNaOrderable\",\"materialBankNaAndCatalogue\",\"materialBankEuOrderable\",\"designShopOrderable\"],\"description\":\"Which corpus to answer from. samplizeCatalogue admits published US paint colours regardless of stock. ABSENT (or 'all') means the WHOLE GRAPH — every material MaterialGraph knows, orderable or not; absence is never a narrower default. Three transaction-oriented scopes gate on governed CHANNEL membership: 'materialBankNaOrderable' (Material Bank North America, ~277,000 materials), 'materialBankEuOrderable' (Material Bank Europe, ~65,000) and 'designShopOrderable' (DesignShop, ~34,000, with the products DesignShop hides from browse excluded). 'materialBankNaAndCatalogue' is the one-query union of Material Bank North America and the governed Catalogue editorial discovery corpus; that union does not by itself claim every member is transactable. 'materialBankOrderable' is NOT one of them: it selects materials carrying a Material Bank identity, which is a provenance signal rather than a channel one, and it admits 98.4% of the graph — use it to exclude crawl-sourced brands, not to mean orderable. A scope answers membership in its named governed corpus, never suitability: scope on channel, then refine on sector. Every scope is applied INSIDE the query: `limit` fills with eligible rows and `counts` describe the scoped corpus, which post-filtering a page cannot give you. An unknown value is a 400 naming it, never a silent fall back to the whole graph.\"},\"cursor\":{\"description\":\"Opaque cursor from a previous response's `cursor`, for the next page of the same query. A cursor from another query is a 409 telling the caller to restart from the first page.\",\"type\":\"string\",\"minLength\":1},\"explain\":{\"description\":\"Add `timings`: wall-clock milliseconds for reading the plan (`planMs`), the index query (`indexMs`) and hydrating the page (`pageMs`), and `explain.plan`: the receipt of the plan the search ran on, with the plan itself.\",\"type\":\"boolean\"},\"filters\":{\"minItems\":1,\"maxItems\":24,\"type\":\"array\",\"items\":{\"anyOf\":[{\"type\":\"object\",\"properties\":{\"attributeId\":{\"type\":\"string\",\"minLength\":1,\"description\":\"An attribute the search index carries, e.g. \\\"primary_material\\\" or \\\"colour_mood\\\", or \\\"certification_programme\\\" for any certification programme.\"},\"term\":{\"type\":\"string\",\"minLength\":1,\"description\":\"The canonical term the value must carry, e.g. \\\"textile\\\".\"}},\"required\":[\"attributeId\",\"term\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"attributeId\":{\"type\":\"string\",\"minLength\":1,\"description\":\"An attribute the search index carries, e.g. \\\"primary_material\\\" or \\\"colour_mood\\\", or \\\"certification_programme\\\" for any certification programme.\"},\"terms\":{\"minItems\":1,\"maxItems\":50,\"type\":\"array\",\"items\":{\"type\":\"string\",\"minLength\":1},\"description\":\"Canonical terms, any one of which satisfies the filter.\"}},\"required\":[\"attributeId\",\"terms\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"attributeId\":{\"type\":\"string\",\"minLength\":1,\"description\":\"An attribute the search index carries, e.g. \\\"primary_material\\\" or \\\"colour_mood\\\", or \\\"certification_programme\\\" for any certification programme.\"},\"excludesTerm\":{\"type\":\"string\",\"minLength\":1,\"description\":\"A canonical term the value must not carry. A material ",
-    "that states nothing for the attribute passes.\"}},\"required\":[\"attributeId\",\"excludesTerm\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"attributeId\":{\"type\":\"string\",\"minLength\":1,\"description\":\"An attribute the search index carries, e.g. \\\"primary_material\\\" or \\\"colour_mood\\\", or \\\"certification_programme\\\" for any certification programme.\"},\"hasValue\":{\"type\":\"boolean\",\"const\":true,\"description\":\"Require any stated value.\"}},\"required\":[\"attributeId\",\"hasValue\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"attributeId\":{\"type\":\"string\",\"minLength\":1,\"description\":\"A number the search index cuts into bands: a numeric attribute such as \\\"nrc_rating\\\" or \\\"lead_time_days\\\", a dimensions lens such as \\\"dimensions.thickness_mm\\\" or \\\"dimensions.short_side_mm\\\" (millimetres), or a composition share such as \\\"composition_weighted.wool\\\" (0 to 1).\"},\"max\":{\"description\":\"Inclusive upper bound. Omit for a floor.\",\"type\":\"number\"},\"min\":{\"description\":\"Inclusive lower bound. Omit for a ceiling.\",\"type\":\"number\"}},\"required\":[\"attributeId\"],\"additionalProperties\":false}]},\"description\":\"Attribute filters, every one hard, run as token sets on the search index. Each entry is a term (`attributeId` + `term`), a term set (`attributeId` + `terms`, any one satisfies it), an exclusion (`attributeId` + `excludesTerm`; a material stating nothing passes), a presence check (`attributeId` + `hasValue: true`) or a numeric range (`attributeId` + `min` and/or `max`, inclusive), read as the number bands wholly inside it, so a bound between two band edges is read inward and a value the index cannot prove in range is left out. Entries on one attribute are OR'd; entries on different attributes AND together. They are added to what the words were read as and change no ordering. An attribute or term the index does not carry is a 400 naming it.\"},\"image\":{\"description\":\"A query image to search by (URL or base64). It is embedded, and the page is its nearest materials in the image namespace; `text`, when also given, narrows them.\",\"oneOf\":[{\"type\":\"object\",\"properties\":{\"type\":{\"type\":\"string\",\"const\":\"url\"},\"url\":{\"type\":\"string\",\"format\":\"uri\",\"description\":\"HTTP(S) URL of the query image. MUST be an https URL.\"}},\"required\":[\"type\",\"url\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"data\":{\"type\":\"string\",\"minLength\":1,\"description\":\"Base64-encoded image bytes (or a data URI) the caller already holds — e.g. a form upload — so there is nothing to host.\"},\"type\":{\"type\":\"string\",\"const\":\"base64\"}},\"required\":[\"data\",\"type\"],\"additionalProperties\":false}],\"type\":\"object\"},\"limit\":{\"description\":\"Products per page (max 60). Absent, the search's own page size.\",\"type\":\"integer\",\"minimum\":1,\"maximum\":60},\"returnAttributes\":{\"maxItems\":8,\"type\":\"array\",\"items\":{\"type\":\"string\",\"minLength\":1},\"description\":\"Attribute ids whose RESOLVED VALUE should ride each result, under `attributes` keyed by attribute id. Values resolve with the normal variant-over-product precedence. THREE STATES, and they are different: an attribute you did not ask for is not a key at all; an attribute you asked for that this variant carries no accepted value for is `null`; anything else is the value (a string, or an array for a multi-valued attribute). An unknown attribute id is refused naming it, never silently dropped. Pair it with `filters` to show what you filtered on.\"},\"similarTo\":{\"description\":\"Find materials that LOOK like a seed: `variantId` seeds from an existing Variant's image, `materialBankId` from a Material Bank SKU (an unknown SKU is a 400 naming it), `vector` from a pre-computed image-space halfvec literal (`[a,b,...]`). `text`, when also given, narrows the look-alikes.\",\"anyOf\":[{\"type\":\"object\",\"properties\":{\"variantId\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"variantId\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"materialBankId\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"materialBankId\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"vector\":{\"type\":\"string\",\"minLength\":1}},\"",
-    "required\":[\"vector\"],\"additionalProperties\":false}]},\"text\":{\"description\":\"Free-text query (\\\"oak flooring\\\", \\\"sage green velvet\\\", \\\"Kvadrat wool\\\"). Brands, categories, colours and attributes are read from the words unless `brands`, `category`, `colour` or `filters` says so instead; a word no material carries may be corrected, and the response says so under `correctedQuery`. May be omitted when `brands`, `category` or `filters` says what to find.\",\"type\":\"string\",\"maxLength\":500},\"view\":{\"default\":\"full\",\"description\":\"Result projection. \\\"full\\\" (default) returns the complete result items; \\\"card\\\" the lean grid projection. The response echoes `view`, which discriminates the `results` union.\",\"type\":\"string\",\"enum\":[\"full\",\"card\"]}},\"additionalProperties\":false}}},\"method\":\"POST\",\"name\":\"search\",\"operationId\":\"search_materials_post\",\"outputSchema\":{\"$ref\":\"#/$defs/schema0\",\"$defs\":{\"schema0\":{\"type\":\"object\",\"properties\":{\"data\":{\"oneOf\":[{\"type\":\"object\",\"properties\":{\"results\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"resultId\":{\"type\":\"string\",\"description\":\"This exact hit's attribution key — `<responseId>:<rank>`, where rank is 1-based within THIS response. Unique across pages, because each page is its own response with its own id. Store it verbatim next to the outcome; it is opaque, and `attribution.responseId` is the field to group by.\"},\"variantId\":{\"type\":\"string\"},\"brand\":{\"type\":\"string\"},\"product\":{\"type\":\"string\"},\"brandSlug\":{\"type\":[\"string\",\"null\"]},\"productId\":{\"type\":[\"string\",\"null\"]},\"materialBankId\":{\"description\":\"The variant's Material Bank SKU — the ONE EXTERNAL identifier on a result, in contrast to the OPAQUE `variantId`: it is the id you are expected to match against Material Bank's own catalogue (carts, ordering and analytics all key on it), so a result list can be joined without a second lookup. Populated by the search and by Match alike. ABSENT means no MB identity is known for the variant, never that the SKU cannot be ordered; presence is the orderability tell, absence is silence.\",\"type\":\"string\"},\"manufacturerCode\":{\"description\":\"The governed manufacturer/source-native item code from `variants.code` (for example \\\"GADLC02\\\"). Populated when the full-result retrieval source carries that canonical field; Match always hydrates it from the variant row. ABSENT means unknown or an older external serving projection, never an invented code. Independent of materialBankId.\",\"type\":\"string\"},\"projectSaveCapability\":{\"description\":\"Explicit source-governed permission to save this exact source-coded variant to a Project. ABSENT means unknown/not allowed; it is never inferred from the brand or name.\",\"type\":\"string\",\"const\":\"allowed\"},\"sampleable\":{\"description\":\"Whether a physical sample is explicitly known to be orderable. Absent means unknown, never unavailable.\",\"type\":\"boolean\"},\"sourceStatus\":{\"description\":\"The governed data status supporting Project capture. ABSENT means unknown. Provisional data remains source-backed but is not a verified catalogue claim.\",\"type\":\"string\",\"const\":\"provisional\"},\"productType\":{\"type\":\"string\"},\"color\":{\"type\":[\"string\",\"null\"]},\"variantName\":{\"type\":[\"string\",\"null\"]},\"imageUrl\":{\"type\":[\"string\",\"null\"]},\"imageSha256\":{\"description\":\"SHA-256 of the displayed image `imageUrl` points at, as a hex digest. Lets a caller key a cache or dedupe on the asset rather than its URL. ABSENT means no hash is on record, never that there is no image.\",\"type\":\"string\"},\"hasImage\":{\"type\":\"boolean\"},\"variantCount\":{\"description\":\"How many eligible variants the row's product has, the same set `list_variants` pages, so a follow-up list of the product returns this many: the card's \\\"12 colourways\\\". ABSENT means the product is unknown or has no eligible variant.\",\"type\":\"integer\",\"exclusiveMinimum\":0,\"maximum\":9007199254740991},\"palette\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"hex\":{\"type\":\"string\",\"description\":\"`#rrggbb` of the swatch, as extracted from the product image.\"},\"name\":{\"description\":\"Stored human colour name for the swatch, when on",
-    "e was extracted.\",\"type\":[\"string\",\"null\"]},\"proportion\":{\"type\":\"number\",\"description\":\"The swatch's share of the analysed image, in [0,1].\"}},\"required\":[\"hex\",\"proportion\"],\"additionalProperties\":false},\"description\":\"The material's main-image palette — the FULL stored palette, uncapped and in stored order. Colours are EXTRACTED FROM PRODUCT IMAGERY (visual likeness, never a declared colour specification). A one-swatch palette means the extractor found one colour — solid-colour materials are genuinely monochrome — never that the list was trimmed. This array is always present: EMPTY means nothing is on record (unknown), not 'this material has no colours'.\"},\"colourMeta\":{\"type\":\"object\",\"properties\":{\"dominantFamily\":{\"type\":\"string\"},\"dominantHex\":{\"type\":\"string\"},\"mood\":{\"type\":\"string\"}},\"additionalProperties\":false},\"colourChip\":{\"type\":\"object\",\"properties\":{\"hex\":{\"type\":\"string\",\"description\":\"`#rrggbb` to fill the chip with. EXTRACTED FROM the product image (a visual likeness), never a manufacturer-declared colour specification — surfaces must not present it as one.\"}},\"required\":[\"hex\"],\"additionalProperties\":false,\"description\":\"Present when this material's product imagery carries nothing beyond one colour, so a surface should render that colour rather than the photograph. Set for COATINGS (paints, primers, stains, floor coatings) whose stored palette quantises to a single swatch — a paint's photo is a flat fill, and the colour we hold structured beats a JPEG of it. 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'.\"},\"attributes\":{\"description\":\"Resolved attribute values for the ids sent in `returnAttributes`, keyed by attribute id. ABSENT entirely when `returnAttributes` was not sent. A key present with `null` means this variant carries no accepted value for that attribute — absent is not empty and neither is null: the three states are distinct on purpose. Values resolve with the normal variant-over-product precedence.\",\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{\"anyOf\":[{\"type\":\"string\"},{\"type\":\"array\",\"items\":{\"type\":\"string\"}},{\"type\":\"null\"}]}},\"score\":{\"type\":\"number\",\"description\":\"The selected mode's weighted primary score on the [0, maxScore] scale.\"},\"retired\":{\"description\":\"MB lists the SKU as not visible/retired; demoted in ranking. Omitted when false.\",\"type\":\"boolean\"}},\"required\":[\"variantId\",\"brand\",\"product\",\"brandSlug\",\"productId\",\"color\",\"variantName\",\"imageUrl\",\"hasImage\",\"palette\",\"score\"],\"additionalProperties\":false}},\"view\":{\"default\":\"full\",\"description\":\"Projection echo — always 'full' on this envelope variant.\",\"type\":\"string\",\"const\":\"full\"},\"correctedQuery\":{\"description\":\"Present when a word no material carries was corrected before the search ran: `from` is the query as typed (normalised), `to` the phrasing the page shows results for.\",\"type\":\"object\",\"properties\":{\"from\":{\"type\":\"string\"},\"to\":{\"type\":\"string\"}},\"required\":[\"from\",\"to\"],\"additionalProperties\":false},\"attribution\":{\"type\":\"object\",\"properties\":{\"basis\":{\"type\":\"string\",\"enum\":[\"image\",\"colour\",\"lexical\",\"agent\",\"attribute\",\"match\"],\"description\":\"The ranking basis. On /api/v1/search this equals the envelope's `mode`. The historical match basis remains readable for stored outcomes.\"},\"issuedAt\":{\"type\":\"string\",\"description\":\"ISO-8601 timestamp of when this response was assembled, so a stored outcome carries its own age without a second lookup.\"},\"responseId\":{\"type\":\"string\",\"description\":\"This response's stable id — the same value as the `X-Request-Id` header. Store it next to the outcome (an order, a save, a click) to join that outcome back to the ranking that produced it. Opaque: round-trip it verbatim, never parse it.\"}},\"required\":[\"basis\",\"issuedAt\",\"responseId\"],\"additionalProperties\":false,\"description\":\"Result attribution receipt. Present on every successful ranked response. Nothing on our side retains it — what you store IS the record.\"},\"s",
-    "uggestions\":{\"default\":[],\"description\":\"Always empty: the one search offers no refinements. Read nothing from it.\",\"maxItems\":0,\"type\":\"array\",\"items\":{\"not\":{}}},\"mode\":{\"type\":\"string\",\"enum\":[\"image\",\"colour\",\"lexical\",\"agent\",\"attribute\"],\"description\":\"What ordered the page: 'image' (a look-alike: image similarity to the seed), 'colour' (the words or the caller named a colour: colour distance inside that colour's family), 'lexical' (the query's words, ranked by text rank on the index), 'attribute' (no words left to rank on: the category and filters define the page), or 'agent' (the search agent chose these variants and their order; scores are rank-based, 1 for the first result falling linearly, and `maxScore` is 1).\"},\"maxScore\":{\"type\":\"number\"},\"note\":{\"type\":\"string\"},\"cursor\":{\"type\":\"string\"},\"timings\":{\"description\":\"Wall-clock milliseconds per step of the search, keyed by step id. The key set is open and depends on the path a query took, so read it by iterating rather than by naming a key. Present only when `explain` is set: diagnostic, not part of the ranking contract.\",\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{\"type\":\"number\"}},\"explain\":{\"description\":\"Present only under `explain`: the receipt of the plan the search ran on. Diagnostic, like `timings`.\",\"type\":\"object\",\"properties\":{\"plan\":{\"type\":\"object\",\"properties\":{\"cached\":{\"type\":\"boolean\"},\"plan\":{\"type\":\"object\",\"properties\":{\"brands\":{\"anyOf\":[{\"type\":\"object\",\"properties\":{\"ids\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"names\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"phrase\":{\"type\":\"string\"}},\"required\":[\"ids\",\"names\",\"phrase\"],\"additionalProperties\":false},{\"type\":\"null\"}]},\"category\":{\"anyOf\":[{\"type\":\"object\",\"properties\":{\"label\":{\"type\":\"string\"},\"phrase\":{\"type\":\"string\"},\"productTypeIds\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"label\",\"phrase\",\"productTypeIds\"],\"additionalProperties\":false},{\"type\":\"null\"}]},\"colour\":{\"anyOf\":[{\"type\":\"object\",\"properties\":{\"family12\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"familyId\":{\"type\":\"string\"},\"hex\":{\"type\":\"string\"},\"oklab\":{\"type\":\"array\",\"prefixItems\":[{\"type\":\"number\"},{\"type\":\"number\"},{\"type\":\"number\"}],\"items\":false,\"minItems\":3,\"maxItems\":3},\"phrase\":{\"type\":\"string\"},\"range\":{\"type\":\"object\",\"properties\":{\"chroma\":{\"type\":\"array\",\"prefixItems\":[{\"type\":\"number\"},{\"type\":\"number\"}],\"items\":false,\"minItems\":2,\"maxItems\":2},\"hue\":{\"anyOf\":[{\"type\":\"array\",\"prefixItems\":[{\"type\":\"number\"},{\"type\":\"number\"}],\"items\":false,\"minItems\":2,\"maxItems\":2},{\"type\":\"null\"}]},\"lightness\":{\"type\":\"array\",\"prefixItems\":[{\"type\":\"number\"},{\"type\":\"number\"}],\"items\":false,\"minItems\":2,\"maxItems\":2}},\"required\":[\"chroma\",\"hue\",\"lightness\"],\"additionalProperties\":false}},\"required\":[\"family12\",\"familyId\",\"hex\",\"oklab\",\"phrase\"],\"additionalProperties\":false},{\"type\":\"null\"}]},\"corpusScope\":{\"type\":\"string\",\"enum\":[\"samplizeCatalogue\",\"materialBankOrderable\",\"materialBankNaOrderable\",\"materialBankNaAndCatalogue\",\"materialBankEuOrderable\",\"designShopOrderable\"]},\"excludeBrands\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"excludes\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"attributeId\":{\"type\":\"string\"},\"phrase\":{\"type\":\"string\"},\"term\":{\"type\":\"string\"}},\"required\":[\"attributeId\",\"phrase\",\"term\"],\"additionalProperties\":false}},\"leftover\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"normalised\":{\"type\":\"string\"},\"softAlone\":{\"type\":\"boolean\"},\"vendorColourNames\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"wants\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"attributeId\":{\"type\":\"string\"},\"fill\":{\"type\":\"number\"},\"phrase\":{\"type\":\"string\"},\"presence\":{\"type\":\"boolean\",\"const\":true},\"strength\":{\"type\":\"string\",\"enum\":[\"hard\",\"soft\"]},\"terms\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"attributeId\",\"fill\",\"phrase\",\"strength\",\"terms\"],\"additionalProperties\":false}}},\"required\":[\"brands\",\"category\",\"colour\",\"excludeBrands\",\"excludes\",\"leftover\",\"normalised\",\"softAlone\",\"vendorColourNames\",\"wants\"],\"additionalProperties\":false",
-    ",\"description\":\"The plan the search ran on: the category, brands, wanted and excluded attribute terms (each hard or soft, with its fill), the colour, the words left for text, and the caller's corpus scope when one was sent.\"},\"signature\":{\"type\":\"string\"},\"source\":{\"type\":\"string\",\"enum\":[\"dictionary\",\"jev\"]},\"version\":{\"type\":\"string\"}},\"required\":[\"cached\",\"plan\",\"signature\",\"source\",\"version\"],\"additionalProperties\":false}},\"required\":[\"plan\"],\"additionalProperties\":false},\"query\":{\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{}},\"seed\":{\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{}}},\"required\":[\"results\",\"view\",\"suggestions\",\"mode\",\"maxScore\",\"query\"],\"additionalProperties\":false},{\"type\":\"object\",\"properties\":{\"results\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"attributes\":{\"description\":\"Resolved attribute values for the ids sent in `returnAttributes`, keyed by attribute id. ABSENT entirely when `returnAttributes` was not sent. A key present with `null` means this variant carries no accepted value for that attribute — absent is not empty and neither is null: the three states are distinct on purpose. Values resolve with the normal variant-over-product precedence.\",\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{\"anyOf\":[{\"type\":\"string\"},{\"type\":\"array\",\"items\":{\"type\":\"string\"}},{\"type\":\"null\"}]}},\"brand\":{\"type\":\"string\"},\"brandSlug\":{\"type\":[\"string\",\"null\"]},\"imageSha256\":{\"description\":\"SHA-256 of the displayed image `imageUrl` points at, as a hex digest. Lets a caller key a cache or dedupe on the asset rather than its URL. ABSENT means no hash is on record, never that there is no image.\",\"type\":\"string\"},\"imageUrl\":{\"type\":[\"string\",\"null\"]},\"manufacturerCode\":{\"description\":\"The governed manufacturer/source-native item code from `variants.code` (for example \\\"K-7265-BV\\\") — the same key and the same value the full item publishes. It is what separates two cards a reader cannot otherwise tell apart: brand, product name and variant name are shared by 280,334 of 371,515 cardable variants, because `name` is the PRODUCT name and a paint product is a whole collection. ABSENT means no code is recorded for the variant, never an invented one.\",\"type\":\"string\"},\"name\":{\"type\":\"string\",\"description\":\"Product name (the full item's `product`).\"},\"productId\":{\"type\":[\"string\",\"null\"]},\"projectSaveCapability\":{\"type\":\"string\",\"const\":\"allowed\"},\"resultId\":{\"type\":\"string\",\"description\":\"This exact hit's attribution key — `<responseId>:<rank>`, where rank is 1-based within THIS response. Unique across pages, because each page is its own response with its own id. Store it verbatim next to the outcome; it is opaque, and `attribution.responseId` is the field to group by.\"},\"sampleable\":{\"description\":\"Whether a physical sample is explicitly known to be orderable. Absent means unknown, never unavailable.\",\"type\":\"boolean\"},\"score\":{\"type\":\"number\"},\"sourceStatus\":{\"type\":\"string\",\"const\":\"provisional\"},\"variantCount\":{\"description\":\"How many eligible variants the row's product has, the same set `list_variants` pages, so a follow-up list of the product returns this many: the card's \\\"12 colourways\\\". ABSENT means the product is unknown or has no eligible variant.\",\"type\":\"integer\",\"exclusiveMinimum\":0,\"maximum\":9007199254740991},\"variantId\":{\"type\":\"string\"},\"variantName\":{\"type\":[\"string\",\"null\"]}},\"required\":[\"brand\",\"brandSlug\",\"imageUrl\",\"name\",\"productId\",\"score\",\"variantId\",\"variantName\"],\"additionalProperties\":false}},\"view\":{\"type\":\"string\",\"const\":\"card\",\"description\":\"Projection echo — always 'card' on this envelope variant.\"},\"correctedQuery\":{\"description\":\"Present when a word no material carries was corrected before the search ran: `from` is the query as typed (normalised), `to` the phrasing the page shows results for.\",\"type\":\"object\",\"properties\":{\"from\":{\"type\":\"string\"},\"to\":{\"type\":\"string\"}},\"required\":[\"from\",\"to\"],\"additionalProperties\":false},\"attribution\":{\"type\":\"object\",\"properties\":{\"basis\":{\"type\":\"string\",",
-    "\"enum\":[\"image\",\"colour\",\"lexical\",\"agent\",\"attribute\",\"match\"],\"description\":\"The ranking basis. On /api/v1/search this equals the envelope's `mode`. The historical match basis remains readable for stored outcomes.\"},\"issuedAt\":{\"type\":\"string\",\"description\":\"ISO-8601 timestamp of when this response was assembled, so a stored outcome carries its own age without a second lookup.\"},\"responseId\":{\"type\":\"string\",\"description\":\"This response's stable id — the same value as the `X-Request-Id` header. Store it next to the outcome (an order, a save, a click) to join that outcome back to the ranking that produced it. Opaque: round-trip it verbatim, never parse it.\"}},\"required\":[\"basis\",\"issuedAt\",\"responseId\"],\"additionalProperties\":false,\"description\":\"Result attribution receipt. Present on every successful ranked response. Nothing on our side retains it — what you store IS the record.\"},\"suggestions\":{\"default\":[],\"description\":\"Always empty: the one search offers no refinements. Read nothing from it.\",\"maxItems\":0,\"type\":\"array\",\"items\":{\"not\":{}}},\"mode\":{\"type\":\"string\",\"enum\":[\"image\",\"colour\",\"lexical\",\"agent\",\"attribute\"],\"description\":\"What ordered the page: 'image' (a look-alike: image similarity to the seed), 'colour' (the words or the caller named a colour: colour distance inside that colour's family), 'lexical' (the query's words, ranked by text rank on the index), 'attribute' (no words left to rank on: the category and filters define the page), or 'agent' (the search agent chose these variants and their order; scores are rank-based, 1 for the first result falling linearly, and `maxScore` is 1).\"},\"maxScore\":{\"type\":\"number\"},\"note\":{\"type\":\"string\"},\"cursor\":{\"type\":\"string\"},\"timings\":{\"description\":\"Wall-clock milliseconds per step of the search, keyed by step id. The key set is open and depends on the path a query took, so read it by iterating rather than by naming a key. Present only when `explain` is set: diagnostic, not part of the ranking contract.\",\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{\"type\":\"number\"}},\"explain\":{\"description\":\"Present only under `explain`: the receipt of the plan the search ran on. Diagnostic, like `timings`.\",\"type\":\"object\",\"properties\":{\"plan\":{\"type\":\"object\",\"properties\":{\"cached\":{\"type\":\"boolean\"},\"plan\":{\"type\":\"object\",\"properties\":{\"brands\":{\"anyOf\":[{\"type\":\"object\",\"properties\":{\"ids\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"names\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"phrase\":{\"type\":\"string\"}},\"required\":[\"ids\",\"names\",\"phrase\"],\"additionalProperties\":false},{\"type\":\"null\"}]},\"category\":{\"anyOf\":[{\"type\":\"object\",\"properties\":{\"label\":{\"type\":\"string\"},\"phrase\":{\"type\":\"string\"},\"productTypeIds\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"label\",\"phrase\",\"productTypeIds\"],\"additionalProperties\":false},{\"type\":\"null\"}]},\"colour\":{\"anyOf\":[{\"type\":\"object\",\"properties\":{\"family12\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"familyId\":{\"type\":\"string\"},\"hex\":{\"type\":\"string\"},\"oklab\":{\"type\":\"array\",\"prefixItems\":[{\"type\":\"number\"},{\"type\":\"number\"},{\"type\":\"number\"}],\"items\":false,\"minItems\":3,\"maxItems\":3},\"phrase\":{\"type\":\"string\"},\"range\":{\"type\":\"object\",\"properties\":{\"chroma\":{\"type\":\"array\",\"prefixItems\":[{\"type\":\"number\"},{\"type\":\"number\"}],\"items\":false,\"minItems\":2,\"maxItems\":2},\"hue\":{\"anyOf\":[{\"type\":\"array\",\"prefixItems\":[{\"type\":\"number\"},{\"type\":\"number\"}],\"items\":false,\"minItems\":2,\"maxItems\":2},{\"type\":\"null\"}]},\"lightness\":{\"type\":\"array\",\"prefixItems\":[{\"type\":\"number\"},{\"type\":\"number\"}],\"items\":false,\"minItems\":2,\"maxItems\":2}},\"required\":[\"chroma\",\"hue\",\"lightness\"],\"additionalProperties\":false}},\"required\":[\"family12\",\"familyId\",\"hex\",\"oklab\",\"phrase\"],\"additionalProperties\":false},{\"type\":\"null\"}]},\"corpusScope\":{\"type\":\"string\",\"enum\":[\"samplizeCatalogue\",\"materialBankOrderable\",\"materialBankNaOrderable\",\"materialBankNaAndCatalogue\",\"materialBankEuOrderable\",\"designShopOrderable\"]},\"excludeBrands\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"excludes\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"pr",
-    "operties\":{\"attributeId\":{\"type\":\"string\"},\"phrase\":{\"type\":\"string\"},\"term\":{\"type\":\"string\"}},\"required\":[\"attributeId\",\"phrase\",\"term\"],\"additionalProperties\":false}},\"leftover\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"normalised\":{\"type\":\"string\"},\"softAlone\":{\"type\":\"boolean\"},\"vendorColourNames\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"wants\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"attributeId\":{\"type\":\"string\"},\"fill\":{\"type\":\"number\"},\"phrase\":{\"type\":\"string\"},\"presence\":{\"type\":\"boolean\",\"const\":true},\"strength\":{\"type\":\"string\",\"enum\":[\"hard\",\"soft\"]},\"terms\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"attributeId\",\"fill\",\"phrase\",\"strength\",\"terms\"],\"additionalProperties\":false}}},\"required\":[\"brands\",\"category\",\"colour\",\"excludeBrands\",\"excludes\",\"leftover\",\"normalised\",\"softAlone\",\"vendorColourNames\",\"wants\"],\"additionalProperties\":false,\"description\":\"The plan the search ran on: the category, brands, wanted and excluded attribute terms (each hard or soft, with its fill), the colour, the words left for text, and the caller's corpus scope when one was sent.\"},\"signature\":{\"type\":\"string\"},\"source\":{\"type\":\"string\",\"enum\":[\"dictionary\",\"jev\"]},\"version\":{\"type\":\"string\"}},\"required\":[\"cached\",\"plan\",\"signature\",\"source\",\"version\"],\"additionalProperties\":false}},\"required\":[\"plan\"],\"additionalProperties\":false},\"query\":{\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{}},\"seed\":{\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{}}},\"required\":[\"results\",\"view\",\"suggestions\",\"mode\",\"maxScore\",\"query\"],\"additionalProperties\":false}],\"type\":\"object\"},\"links\":{\"type\":\"object\",\"properties\":{},\"additionalProperties\":false},\"meta\":{\"type\":\"object\",\"properties\":{\"operationId\":{\"type\":\"string\",\"enum\":[\"search_materials_post\",\"search_materials_get\"]},\"requestId\":{\"type\":\"string\",\"minLength\":1}},\"required\":[\"operationId\",\"requestId\"],\"additionalProperties\":false},\"warnings\":{\"type\":\"array\",\"items\":{\"type\":\"string\",\"minLength\":1}}},\"required\":[\"data\",\"links\",\"meta\",\"warnings\"],\"additionalProperties\":false}}},\"path\":\"/api/v1/search\",\"requiredHeaders\":[],\"requiresVisibleConfirmation\":false}]",
+    "[{\"annotations\":{\"readOnlyHint\":true,\"untrustedContentHint\":true},\"description\":\"Reads `query` into filters, runs them through `list_variants` and answers with what was understood beside a page of variants. `understood` says what each phrase became: a hard `filter`, a ranking `preference`, or `not_applied` when nothing could serve it. `filters`, `optionalFilters` and `name` are exactly what ran, so the three can be sent to `list_variants` to narrow or widen the same search. A phrase with more than one meaning is answered with one and listed in `choices`: send its `handle` with an alternative's `group` and `id` in `selections` to switch it. `unresolved` lists words nothing in the vocabulary could read. A query that applies nothing returns no items, never the whole catalogue; a preference alone still ranks it. `cursor` is the previous page's `pageInfo.endCursor`, tied to the vocabulary version the query was read against; it pages this operation only, not `list_variants`. Requires the `mg:read` bearer scope.\",\"inputSchema\":{\"$ref\":\"#/$defs/schema0\",\"$defs\":{\"schema0\":{\"type\":\"object\",\"properties\":{\"attributes\":{\"description\":\"Attribute/block ids to add; id fields always return.\",\"maxItems\":20,\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"cursor\":{\"type\":\"string\"},\"limit\":{\"description\":\"5-10 for examples.\",\"type\":\"integer\",\"minimum\":1,\"maximum\":50},\"query\":{\"type\":\"string\",\"minLength\":1,\"maxLength\":200,\"description\":\"What to find, in plain words.\"},\"selections\":{\"description\":\"Switch a choice: its handle plus the alternative's group and id.\",\"maxItems\":8,\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"group\":{\"type\":\"string\"},\"handle\":{\"type\":\"string\"},\"id\":{\"type\":\"string\"}},\"required\":[\"group\",\"handle\",\"id\"],\"additionalProperties\":false}},\"searchCatalogueSubset\":{\"description\":\"Only this corpus scope. Absent or all: every variant.\",\"type\":\"string\",\"enum\":[\"all\",\"samplizeCatalogue\",\"materialBankOrderable\",\"materialBankNaOrderable\",\"materialBankNaAndCatalogue\",\"materialBankEuOrderable\",\"designShopOrderable\"]},\"include\":{\"type\":\"array\",\"items\":{\"type\":\"string\",\"enum\":[\"image\",\"url\"]}}},\"required\":[\"query\"],\"additionalProperties\":false}}},\"method\":\"POST\",\"name\":\"search\",\"operationId\":\"search_variants\",\"outputSchema\":{\"$ref\":\"#/$defs/schema0\",\"$defs\":{\"schema1\":{\"anyOf\":[{\"type\":\"string\"},{\"type\":\"number\"},{\"type\":\"boolean\"},{\"type\":\"null\"},{\"type\":\"array\",\"items\":{\"$ref\":\"#/$defs/schema1\"}},{\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{\"$ref\":\"#/$defs/schema1\"}}]},\"schema0\":{\"type\":\"object\",\"properties\":{\"excludedBySearchCatalogueSubset\":{\"description\":\"Filtered variant ids outside the materials catalogue.\",\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"items\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"category\":{\"anyOf\":[{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\"},\"name\":{\"type\":\"string\"}},\"required\":[\"id\",\"name\"],\"additionalProperties\":false},{\"type\":\"null\"}],\"description\":\"The first original source category, or null when unknown.\"},\"categories\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\"},\"name\":{\"type\":\"string\"}},\"required\":[\"id\",\"name\"],\"additionalProperties\":false},\"description\":\"All original source categories in source order.\"},\"productType\":{\"anyOf\":[{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\"},\"name\":{\"type\":\"string\"}},\"required\":[\"id\",\"name\"],\"additionalProperties\":false},{\"type\":\"null\"}],\"description\":\"The accepted primary specification type, or null for a color sample or unresolved subject.\"},\"sampleSubject\":{\"type\":\"string\",\"enum\":[\"material\",\"paint_color_sample\",\"unknown\",\"conflict\"]},\"colorOptionValueId\":{\"type\":[\"string\",\"null\"]},\"code\":{\"description\":\"The brand's item code.\",\"type\":[\"string\",\"null\"]},\"image\":{\"anyOf\":[{\"type\":\"object\",\"properties\":{\"alt\":{\"type\":\"string\"},\"url\":{\"type\":\"string\"}},\"required\":[\"alt\",\"url\"],\"additionalProperties\":false},{\"type\":\"null\"}],\"description\":\"The primary product image, or null when there is none.\"},\"brand\":{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\"},\"name\":{\"type\":\"st",
+    "ring\"}},\"required\":[\"id\",\"name\"],\"additionalProperties\":false,\"description\":\"The brand. `id` is the slug get_brand takes.\"},\"name\":{\"type\":\"string\",\"description\":\"The variant's own name.\"},\"product\":{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\"},\"name\":{\"type\":\"string\"}},\"required\":[\"id\",\"name\"],\"additionalProperties\":false},\"url\":{\"description\":\"The brand's page for it, or null when none is known.\",\"type\":[\"string\",\"null\"]},\"variantId\":{\"type\":\"string\"},\"materialBankId\":{\"description\":\"The variant's Material Bank SKU. Absent: none recorded.\",\"type\":\"string\"},\"notApplicable\":{\"type\":\"object\",\"properties\":{\"attributes\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"blocks\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"additionalProperties\":false,\"description\":\"Requested blocks or attributes this product type does not carry.\"},\"preference\":{\"type\":\"object\",\"properties\":{\"matched\":{\"type\":\"array\",\"items\":{\"type\":\"number\"}},\"score\":{\"type\":\"number\"}},\"required\":[\"matched\",\"score\"],\"additionalProperties\":false},\"specifications\":{\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{\"type\":\"object\",\"propertyNames\":{\"type\":\"string\"},\"additionalProperties\":{\"$ref\":\"#/$defs/schema1\"}}},\"variantCount\":{\"description\":\"Eligible variants of this product. Absent: none counted.\",\"type\":\"integer\",\"exclusiveMinimum\":0,\"maximum\":9007199254740991}},\"required\":[\"category\",\"categories\",\"productType\",\"sampleSubject\",\"colorOptionValueId\",\"code\",\"brand\",\"name\",\"product\",\"variantId\"],\"additionalProperties\":false}},\"pageInfo\":{\"type\":\"object\",\"properties\":{\"endCursor\":{\"type\":[\"string\",\"null\"]},\"hasNextPage\":{\"type\":\"boolean\"}},\"required\":[\"endCursor\",\"hasNextPage\"],\"additionalProperties\":false},\"preferenceMatchesRemain\":{\"description\":\"False: nothing from this page on meets any optionalFilter.\",\"type\":\"boolean\"},\"unavailableVariantIds\":{\"description\":\"Filtered ids in the catalogue this list can't show, e.g. retired.\",\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"unresolvedVariantIds\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"unstated\":{\"description\":\"Filtered attributes no variant in scope states at all.\",\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"words\":{\"description\":\"Each word asked for, and whether any variant in scope names it.\",\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"matched\":{\"type\":\"boolean\"},\"word\":{\"type\":\"string\"}},\"required\":[\"matched\",\"word\"],\"additionalProperties\":false}},\"choices\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"alternatives\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"group\":{\"type\":\"string\"},\"id\":{\"type\":\"string\"},\"kind\":{\"type\":\"string\"},\"label\":{\"type\":\"string\"}},\"required\":[\"group\",\"id\",\"kind\",\"label\"],\"additionalProperties\":false}},\"basis\":{\"type\":\"string\"},\"handle\":{\"type\":\"string\"},\"reason\":{\"type\":\"string\"},\"selected\":{\"type\":\"object\",\"properties\":{\"group\":{\"type\":\"string\"},\"id\":{\"type\":\"string\"},\"kind\":{\"type\":\"string\"},\"label\":{\"type\":\"string\"}},\"required\":[\"group\",\"id\",\"kind\",\"label\"],\"additionalProperties\":false},\"text\":{\"type\":\"string\"}},\"required\":[\"alternatives\",\"basis\",\"handle\",\"reason\",\"selected\",\"text\"],\"additionalProperties\":false}},\"colors\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"hex\":{\"type\":\"string\",\"pattern\":\"^#[\\\\da-f]{6}$\",\"description\":\"The color's own point in the region; it orders matches.\"},\"intent\":{\"type\":\"string\",\"enum\":[\"required\",\"preferred\"]},\"op\":{\"type\":\"string\",\"enum\":[\"in\",\"not_in\"]},\"range\":{\"type\":\"object\",\"properties\":{\"chroma\":{\"type\":\"array\",\"prefixItems\":[{\"type\":\"number\"},{\"type\":\"number\"}],\"items\":false,\"minItems\":2,\"maxItems\":2},\"hue\":{\"anyOf\":[{\"type\":\"array\",\"prefixItems\":[{\"type\":\"number\"},{\"type\":\"number\"}],\"items\":false,\"minItems\":2,\"maxItems\":2},{\"type\":\"null\"}]},\"lightness\":{\"type\":\"array\",\"prefixItems\":[{\"type\":\"number\"},{\"type\":\"number\"}],\"items\":false,\"minItems\":2,\"maxItems\":2}},\"required\":[\"chroma\",\"hue\",\"lightness\"],\"additionalProperties\":false}},\"required\":[\"hex\",\"op\",\"range\"],\"additionalProperties\":false},\"description\":\"The color regions that ran.\"},\"corrections\":{\"type\":\"array\",\"i",
+    "tems\":{\"type\":\"object\",\"properties\":{\"correction\":{\"type\":\"string\"},\"word\":{\"type\":\"string\"}},\"required\":[\"correction\",\"word\"],\"additionalProperties\":false}},\"filters\":{\"type\":\"object\",\"properties\":{\"anyField\":{\"description\":\"One of values in any of fields (term attributes).\",\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"fields\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"op\":{\"type\":\"string\",\"enum\":[\"in\",\"not_in\"]},\"orText\":{\"type\":\"string\"},\"unstated\":{\"type\":\"string\",\"const\":\"pass\"},\"values\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"fields\",\"op\",\"values\"],\"additionalProperties\":false}},\"numbers\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"field\":{\"type\":\"string\"},\"op\":{\"type\":\"string\",\"enum\":[\"eq\",\"gt\",\"gte\",\"lt\",\"lte\"]},\"value\":{\"type\":\"number\"}},\"required\":[\"field\",\"op\",\"value\"],\"additionalProperties\":false}},\"presence\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"field\":{\"type\":\"string\"},\"op\":{\"type\":\"string\",\"enum\":[\"exists\",\"missing\"]}},\"required\":[\"field\",\"op\"],\"additionalProperties\":false}},\"terms\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"field\":{\"type\":\"string\"},\"op\":{\"type\":\"string\",\"enum\":[\"in\",\"all\",\"not_in\"]},\"orText\":{\"type\":\"string\"},\"unstated\":{\"type\":\"string\",\"const\":\"pass\"},\"values\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"field\",\"op\",\"values\"],\"additionalProperties\":false}}},\"additionalProperties\":false,\"description\":\"The filters that ran, the scope among them.\"},\"name\":{\"type\":\"string\",\"description\":\"The paint name looked up.\"},\"oneRowPer\":{\"type\":\"string\",\"enum\":[\"product\",\"variant\"],\"description\":\"A row per product, or per variant for a paint or color.\"},\"optionalFilters\":{\"type\":\"object\",\"properties\":{\"anyField\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"fields\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"op\":{\"type\":\"string\",\"enum\":[\"in\",\"not_in\"]},\"orText\":{\"type\":\"string\"},\"values\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"weight\":{\"type\":\"integer\",\"minimum\":1,\"maximum\":10}},\"required\":[\"fields\",\"op\",\"values\",\"weight\"],\"additionalProperties\":false}},\"numbers\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"field\":{\"type\":\"string\"},\"op\":{\"type\":\"string\",\"enum\":[\"eq\",\"gt\",\"gte\",\"lt\",\"lte\"]},\"value\":{\"type\":\"number\"},\"weight\":{\"type\":\"integer\",\"minimum\":1,\"maximum\":10}},\"required\":[\"field\",\"op\",\"value\",\"weight\"],\"additionalProperties\":false}},\"presence\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"field\":{\"type\":\"string\"},\"op\":{\"type\":\"string\",\"enum\":[\"exists\",\"missing\"]},\"weight\":{\"type\":\"integer\",\"minimum\":1,\"maximum\":10}},\"required\":[\"field\",\"op\",\"weight\"],\"additionalProperties\":false}},\"terms\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"field\":{\"type\":\"string\"},\"op\":{\"type\":\"string\",\"enum\":[\"in\",\"all\",\"not_in\"]},\"orText\":{\"type\":\"string\"},\"values\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"weight\":{\"type\":\"integer\",\"minimum\":1,\"maximum\":10}},\"required\":[\"field\",\"op\",\"values\",\"weight\"],\"additionalProperties\":false}}},\"additionalProperties\":false,\"description\":\"The preferences that ran.\"},\"outcome\":{\"type\":\"string\",\"enum\":[\"page\",\"no_match\",\"nothing_understood\",\"out_of_scope\",\"brand_not_in_catalogue\"],\"description\":\"How the search ended.\"},\"scope\":{\"type\":\"object\",\"properties\":{\"anyField\":{\"description\":\"One of values in any of fields (term attributes).\",\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"fields\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}},\"op\":{\"type\":\"string\",\"enum\":[\"in\",\"not_in\"]},\"orText\":{\"type\":\"string\"},\"unstated\":{\"type\":\"string\",\"const\":\"pass\"},\"values\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"fields\",\"op\",\"values\"],\"additionalProperties\":false}},\"numbers\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"field\":{\"type\":\"string\"},\"op\":{\"type\":\"string\",\"enum\":[\"eq\",\"gt\",\"gte\",\"lt\",\"lte\"]},\"value\":{\"type\":\"number\"}},\"required\":[\"field\",\"op\",\"value\"],\"additionalProperties\":false}},\"presence\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"field\":{\"type\":\"string\"},\"op\":{\"type\":\"string\",\"enum\":[\"exists\",\"missing\"]}},\"r",
+    "equired\":[\"field\",\"op\"],\"additionalProperties\":false}},\"terms\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"field\":{\"type\":\"string\"},\"op\":{\"type\":\"string\",\"enum\":[\"in\",\"all\",\"not_in\"]},\"orText\":{\"type\":\"string\"},\"unstated\":{\"type\":\"string\",\"const\":\"pass\"},\"values\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"field\",\"op\",\"values\"],\"additionalProperties\":false}}},\"additionalProperties\":false,\"description\":\"The fixed scope, repeated in filters.\"},\"understood\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"applied\":{\"type\":\"string\",\"enum\":[\"filter\",\"preference\",\"not_applied\"],\"description\":\"filter narrows; preference only ranks; not_applied did neither.\"},\"id\":{\"type\":\"string\",\"description\":\"The parser's condition id.\"},\"kind\":{\"type\":\"string\",\"enum\":[\"category\",\"brand\",\"term\",\"number\",\"color\",\"paint\"]},\"label\":{\"type\":\"string\",\"description\":\"What the words were read as.\"},\"note\":{\"type\":\"string\"},\"text\":{\"type\":\"string\",\"description\":\"The query words it came from.\"}},\"required\":[\"applied\",\"id\",\"kind\",\"label\",\"text\"],\"additionalProperties\":false}},\"unresolved\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}},\"required\":[\"items\",\"pageInfo\",\"oneRowPer\",\"outcome\",\"understood\"],\"additionalProperties\":false}}},\"path\":\"/api/v1/variants/search\",\"requiredHeaders\":[],\"requiresVisibleConfirmation\":false}]",
 ].join("");
 export const WEBMCP_TOOLS = JSON.parse(json);

package/attribution-types.d.ts

@@ -1,51 +0,0 @@
-/**
- * Result attribution (MG-1131) — joining an outcome back to the ranking that
- * produced it.
- *
- * When someone orders a sample days after a search, a list of SKUs cannot say
- * which response returned it or on what basis it was ranked. Store
- * {@link SearchResultItem.resultId} next to the order row and
- * {@link ResponseAttribution} beside the search, and both questions become a
- * join in your own warehouse.
- *
- * MaterialGraph keeps no ledger of these ids. What you store IS the record.
- */
-/**
- * The ranking basis, in one vocabulary across both ranked routes.
- *
- * 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" | "agent" | "attribute" | "match";
-/**
- * Envelope-level attribution receipt, on every successful ranked response.
- *
- * Store this beside the search and each result's `resultId` beside the outcome
- * (an order, a save, a click), and "which sample was ordered off which ranking,
- * on what basis" becomes a join in your own warehouse.
- *
- * A `resultId` is `<responseId>:<rank>`, rank being 1-based within the response
- * that returned it — unique across pages, because each page is its own
- * response. On the Match stream lane it also carries the surface id, so a hit
- * sent twice (on its `surface` frame and again inside `complete`) keeps one key.
- *
- * Both ids are OPAQUE: store them verbatim, never parse them. Group on
- * `responseId` and `basis`.
- *
- * 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 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
-     * this field to recover the response that produced them.
-     */
-    responseId: string;
-    /** How this ranking was produced. The field to group outcomes by. */
-    basis: AttributionBasis;
-    /** ISO-8601 timestamp of when the response was assembled. */
-    issuedAt: string;
-};

package/attribution-types.js

@@ -1,13 +0,0 @@
-/**
- * Result attribution (MG-1131) — joining an outcome back to the ranking that
- * produced it.
- *
- * When someone orders a sample days after a search, a list of SKUs cannot say
- * which response returned it or on what basis it was ranked. Store
- * {@link SearchResultItem.resultId} next to the order row and
- * {@link ResponseAttribution} beside the search, and both questions become a
- * join in your own warehouse.
- *
- * MaterialGraph keeps no ledger of these ids. What you store IS the record.
- */
-export {};

package/by-colour-types.d.ts

@@ -1,320 +0,0 @@
-/**
- * Wire types for the single-colour lane — GET `/api/v1/search/colours`.
- *
- * Kept out of `types.ts` for the same reason `palette-search-types.ts` is: the
- * shared mirror is at its source-size budget. Same tolerant-parsing contract as
- * the rest of the mirror — response enums are widened so a new server value
- * still type-checks.
- */
-import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
-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 type MatchCategory = {
-    group: string | null;
-    type: string | null;
-};
-/**
- * One colour-palette match.
- *
- * `distance` and `closeness` are OKLab geometry over colour EXTRACTED FROM
- * PRODUCT IMAGERY. Report the ORDER as visual likeness ("reads close to this
- * colour"), never as a stated colour specification. `hex` itself may be the
- * manufacturer's published colour — read `sourceBasis` before repeating it.
- */
-export type ByColourMatch = {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    brand: string;
-    product: string;
-    /** Record-route brand identity. */
-    brandSlug?: string | null;
-    /** Opaque MaterialGraph product-family identity. */
-    productId?: string | null;
-    /** Material Bank cart/order join key; absent when not on record. */
-    materialBankId?: string;
-    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
-     * repeated as their stated colour. `"derived"`: extracted from product
-     * imagery — visual likeness only. Widened to `string` so a new server value
-     * still type-checks. ABSENT when `hex` is null, or on a response captured
-     * before the field existed.
-     */
-    sourceBasis?: OpenEnum<"declared" | "derived">;
-    /**
-     * OKLab distance from the QUERY colour to this match's `hex` — two single
-     * colours. NOT `distance`, which is the imagery ranking's geometry over whole
-     * PALETTES. The two disagree routinely: a match ranked 4th by imagery is often
-     * the closest by hex. ABSENT when the match has no hex, or when the query was
-     * a palette rather than one colour.
-     */
-    colourDistance?: number;
-    /**
-     * `colourDistance` as a named band, so nobody thresholds a float. Not a
-     * confidence and not a percentage — `very-close` still covers differences a
-     * client would reject in a paint order, so read `sourceBasis` before quoting
-     * any of it as a specification. Widened to `string` so a new server band still
-     * type-checks. ABSENT exactly when `colourDistance` is.
-     */
-    proximity?: OpenEnum<"indistinguishable" | "very-close" | "close" | "related" | "unrelated">;
-    /**
-     * The match's own image palette — the FULL stored palette, uncapped and in
-     * stored order, each swatch with `oklab` (see {@link ByColourSwatch}), so a
-     * card can render, sort or group colours without a second call. A one-swatch
-     * palette means the extractor found one colour (solid-colour materials are
-     * genuinely monochrome), not that the list was trimmed. ABSENT when no palette
-     * is on record: absent means unknown, NOT that the material has no colours.
-     * Like `hex`, these swatches come from product imagery, not from the
-     * manufacturer.
-     */
-    palette?: ByColourSwatch[];
-};
-/** A {@link PaletteSwatch} on the colour lane, where `oklab` is always derived. */
-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 type ColourFamilyGate = {
-    /** The colorscope taxonomy family id the gate kept (normalised). */
-    family: string;
-    /** Candidates the gate examined — the retrieved pool. NOT a corpus total. */
-    considered: number;
-    /**
-     * Candidates the gate rejected — another family, or no readable hex (unknown
-     * is not membership). `considered − matches.length` is not the same number
-     * once the page is cut to `limit`; this is the gate's own cost.
-     */
-    dropped: number;
-    /**
-     * Rows dropped a SECOND time, after the page was hydrated with the brand's
-     * declared `colour_hex`. A paint's chip photograph and its published hex are
-     * different colours and can fall in different families, so the page is
-     * re-gated on the hex it reports — every `hex` you receive belongs to the
-     * family you asked for. Absent means hydration moved nothing across a
-     * boundary.
-     */
-    droppedOnPublishedHex?: number;
-};
-/** Receipt for the hard category gate and its treatment of unknown typing. */
-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. Only responses stored before the one search carry it: the one
- * search pages one row per product, so nothing collapses now.
- */
-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.
- *
- * 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 type ColourLaneReceipt = {
-    /** Which lane answered. Widened so a new server lane still type-checks. */
-    lane: OpenEnum<"index" | "containment" | "palette">;
-    /** Why this lane, in one sentence, for a human reader. */
-    reason: string;
-    /**
-     * How the page was ordered. `representative` — the containment default —
-     * draws the page in the contained set's own proportions of solid and
-     * multi-swatch materials, nearest-first within each, because ordering
-     * containment by proximity alone returns a page of solid-colour materials.
-     */
-    order: OpenEnum<"representative" | "nearest" | "similarity">;
-    /**
-     * The colours the search ACTUALLY ran on, after minor-proportion accents were
-     * dropped. Compare against `query.colours`: a difference means the search that
-     * ran is not the search you asked for.
-     */
-    effectiveColours: string[];
-    /**
-     * Colours removed from your query for carrying a proportion below the accent
-     * threshold. EMPTY is the normal case. Non-empty and those colours were absent
-     * from retrieval entirely — they did not merely rank low, so an empty-looking
-     * result is not evidence that nothing holds them.
-     */
-    droppedColours: string[];
-};
-/** The `search/colours` response. */
-export type ByColourResponse = {
-    query: {
-        /** Raw query provenance, when supplied. */
-        q?: string;
-        colours: string[];
-        categories?: string[];
-        /**
-         * Echoed brand filter as resolved SLUGS — what the canonical ids, slugs,
-         * or exact names you passed resolved to. Present only when a brand scope
-         * applied.
-         */
-        brands?: string[];
-        /** Echoed `family` filter, normalised. Present only when one was applied. */
-        family?: string;
-        /** Applied single-colour containment order. */
-        order?: "representative" | "nearest";
-        /** Applied maximum OKLab distance to each reported match hex. */
-        maxColourDistance?: number;
-        oklab?: OklabTriple;
-    };
-    /** `matches.length` — THIS PAGE. Not a corpus total; this surface states none. */
-    count: number;
-    matches: ByColourMatch[];
-    /**
-     * Present only when `family` was asked for. A gated page can be SHORTER than
-     * `limit` — the gate runs over a retrieved pool, not the corpus — and this is
-     * what says so in counts rather than adjectives.
-     */
-    familyGate?: ColourFamilyGate;
-    /** Applied `maxColourDistance` threshold and its page-bounded drop count. */
-    proximityGate?: {
-        maxColourDistance: number;
-        considered: number;
-        dropped: number;
-    };
-    /**
-     * Present only when `category` was asked for. It states that variants without
-     * an accepted primary product type were excluded by the hard gate; absence
-     * means no category gate ran.
-     */
-    categoryGate?: ColourCategoryGate;
-    /**
-     * What the colour-identity collapse cost this page. Matches are TILES: a page
-     * can be SHORTER than `limit` when the pool collapsed harder than the
-     * overfetch allowed, and this says so in counts rather than adjectives.
-     */
-    collapse?: ColourCollapse;
-    /**
-     * Which retrieval lane answered and the colours it ran on. The live endpoint
-     * always sends it; optional here only so responses captured before the lane
-     * split still type-check.
-     */
-    lane?: ColourLaneReceipt;
-    /**
-     * The corpus this page was drawn from — present ONLY when the request
-     * narrowed it. ABSENT means the whole graph: every material MaterialGraph
-     * knows, orderable or not. Under a scope the `familyGate` and `collapse` pool
-     * counts describe the SCOPED corpus too, because the scope was applied inside
-     * retrieval rather than over the page it produced.
-     */
-    corpusScope?: CorpusScopeReceipt;
-    /** Shared standard-search query-understanding receipt. */
-    understanding?: QueryUnderstanding;
-};
-/** Params for `search/colours`. */
-export type ByColourParams = {
-    /** Raw material-domain query provenance for shared query understanding. */
-    q?: string;
-    /** A single hex (with or without `#`). */
-    hex?: string;
-    /** A palette — repeated as one `colour` query entry each. */
-    colour?: string | string[];
-    /** OKLab triple (all-or-none). */
-    l?: number;
-    a?: number;
-    b?: number;
-    /**
-     * 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
-     * (`sherwin-williams`), or exact display name (`Sherwin-Williams`). Canonical
-     * ids and slugs are case-sensitive and opaque; display names are
-     * case-insensitive.
-     *
-     * This is how the CROSS-BRAND question is asked: pass one brand's colour as
-     * `hex` and scope to another to get that brand's nearest colours to it. It is
-     * applied inside retrieval, so `limit` still fills from the scoped brands —
-     * filtering a returned page instead comes back short, because a
-     * nearest-neighbour scan does not know to look further.
-     *
-     * An unknown brand is a typed 400 naming it, and an exact display name shared
-     * by multiple brands is a typed 400 with the candidates; neither becomes an
-     * empty page. Omitting it (or passing an empty list) searches every brand.
-     */
-    brand?: string | string[];
-    /**
-     * HARD colour-family filter — ONE colorscope taxonomy family id, from the
-     * closed 15-value vocabulary colorscope itself publishes (`white`, `cream`,
-     * `gray`, `black`, `beige`, `taupe`, `brown`, `red`, `orange`, `yellow`,
-     * `green`, `teal`, `blue`, `purple`, `pink`). Case-insensitive; anything else
-     * is a 400 listing the vocabulary.
-     *
-     * This is NOT the `colour_family` facet vocabulary from `colourFacets()`, and
-     * NOT a match's stored dominant-family term — those are colorscope's NAMING
-     * families, a different (13-term) list. The family here is assigned from the
-     * match's dominant hex by colorscope's taxonomy ownership rules.
-     *
-     * A filtered page may come back shorter than `limit`: the gate runs over a
-     * retrieved pool, and `familyGate` on the response reports that pool and the
-     * drop.
-     */
-    family?: string;
-    /**
-     * 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;
-};

package/colour-region-types.d.ts

@@ -1,18 +0,0 @@
-/**
- * A colour word's region in OKLCh: what a name like "sage" covers, rather than
- * one point. A swatch counts inside it, so it is a box (lightness, chroma, hue)
- * and not a distance. Search echoes it on the plan's colour and accepts it back
- * on the request's `colour`, and the colour lookups carry it on each resolved
- * region.
- */
-export type ColourRegionRange = {
-    /** Inclusive OKLab lightness bounds, 0 to 1. */
-    lightness: [number, number];
-    /** Inclusive OKLCh chroma bounds. */
-    chroma: [number, number];
-    /**
-     * The hue arc in degrees, 0 to 360, inclusive. It wraps when its start is past
-     * its end (reds). `null` means any hue, which is what a neutral is.
-     */
-    hue: [number, number] | null;
-};