@instruments/materialgraph 0.4.0 → 0.6.0

package/client.js

@@ -60,6 +60,7 @@ export class MaterialGraphClient {
         });
         this.colours = new ColoursClient({
             get: (operationId, query, signal) => this.#get(operationId, query, signal),
+            post: (operationId, body, signal) => this.#post(operationId, body, signal),
         });
     }
     get lastRateLimit() {

package/colour-aggregate-types.d.ts

@@ -8,8 +8,12 @@
  * widened so a new server value still type-checks.
  */
 import type { OpenEnum } from "./types.js";
-/** Which taxonomy tier a colour profile's `categoryKey` names. */
-export type CategoryTier = OpenEnum<"group" | "type">;
+/**
+ * Which taxonomy tier a colour profile's `categoryKey` names — or `"merged"`,
+ * where the key is a composite over a caller-defined key set rather than a
+ * taxonomy node.
+ */
+export type CategoryTier = OpenEnum<"group" | "type" | "merged">;
 /** How the endpoint picks which colours to keep. */
 export type ColourProfileSelect = OpenEnum<"frequency" | "diverse">;
 /** One representative colour bucket of a category. */
@@ -29,6 +33,11 @@ export interface CategoryColourProfile {
     level: CategoryTier;
     name: string;
     path: string;
+    /**
+     * Under `groupBy: "merged"`, the requested keys in composite-key order, so
+     * `categoryKey` never has to be split. Absent on a single-category profile.
+     */
+    members?: string[];
     variantCount: number;
     avgLightness: number;
     avgChroma: number;
@@ -51,8 +60,11 @@ export interface CategoryColourProfilesResponse {
 export interface ColourProfilesParams {
     /** 1–8 category keys, at the tier named by `groupBy`. */
     productTypeIds: readonly string[];
-    /** `"group"` merges each group's leaf product types into one palette. */
-    groupBy?: "group" | "type";
+    /**
+     * `"group"` merges each group's leaf product types into one palette;
+     * `"merged"` merges EVERY key's leaves into a single combined palette.
+     */
+    groupBy?: "group" | "type" | "merged";
     /** Representative colours per category, 1–64. */
     topN?: number;
     /** `"diverse"` maximises visual distinctness instead of frequency. */

package/colours-client.d.ts

@@ -1,26 +1,31 @@
 /**
- * The colour AGGREGATE surface, namespaced as `mg.colours`.
+ * The colour surface, namespaced as `mg.colours` — the aggregate reads
+ * (`stats`, `profiles`) plus MULTI-COLOUR search (`palette`, `gradient`).
  *
- * Two reads that answer the same question at two altitudes — "how much colour
- * does the graph hold at all" (`stats`) and "what colours does this category
- * come in" (`profiles`) — so they live together rather than as two more flat
- * methods on an already-large client facade. `mg.codes` and `mg.browse` set the
- * precedent for a namespace when a capability is a small family rather than a
- * single verb.
+ * One colour family rather than four more flat methods on an already-large
+ * client facade: "how much colour does the graph hold at all" (`stats`), "what
+ * colours does this category come in" (`profiles`), "what goes with these
+ * colours" (`palette`), and "what moves from this colour to that one"
+ * (`gradient`). `mg.codes` and `mg.browse` set the precedent for a namespace
+ * when a capability is a family rather than a single verb.
  *
  * The namespace holds no transport of its own: the client hands it a bound
- * `get`, so auth, rate-limit accounting and error shaping stay in one place.
+ * `get`/`post`, so auth, rate-limit accounting and error shaping stay in one
+ * place.
  *
- * Both responses carry a `basis`. These are reads of a materialized view that is
- * refreshed on a schedule, not on write, so a caller can and should check how
- * much of the corpus the answer actually covers before treating it as complete.
+ * The two AGGREGATE responses carry a `basis`. Those are reads of a
+ * materialized view refreshed on a schedule, not on write, so a caller can and
+ * should check how much of the corpus the answer actually covers before
+ * treating it as complete. The two SEARCH responses are live and uncached.
  */
 import type { CategoryColourProfilesResponse, ColourProfilesParams, ColourStatsResponse } from "./colour-aggregate-types.js";
 import type { QueryParams } from "./http-transport.js";
 import type { SdkOperationId } from "./operations.js";
-/** The client's own request primitive, handed down so this file owns no transport. */
+import type { SearchGradientInput, SearchGradientResponse, SearchPaletteInput, SearchPaletteResponse } from "./palette-search-types.js";
+/** The client's own request primitives, handed down so this file owns no transport. */
 export interface ColoursTransport {
     get<T>(operationId: SdkOperationId, query?: QueryParams, signal?: AbortSignal): Promise<T>;
+    post<T>(operationId: SdkOperationId, body: unknown, signal?: AbortSignal): Promise<T>;
 }
 export declare class ColoursClient {
     #private;
@@ -37,6 +42,13 @@ export declare class ColoursClient {
      * cannot recover that spread from a truncated frequency list, which is why it
      * is a server mode rather than a local sort.
      *
+     * `groupBy: "merged"` merges across the KEYS as well and returns ONE profile
+     * over the union of their leaves — the palette of a caller-defined facet such
+     * as "Wood" (`wood_surface` + `wood_flooring`) that the taxonomy holds no
+     * single node for, and that no combination of per-key responses reconstructs.
+     * Its keys may sit at either tier, `categoryKey` is those keys sorted and
+     * joined with `+`, and `members` hands them back so nothing has to split it.
+     *
      * A selected category with no colour data comes back as a zero-count profile,
      * not a missing key.
      */
@@ -49,4 +61,42 @@ export declare class ColoursClient {
      * answer, listed rather than silently absent.
      */
     stats(signal?: AbortSignal): Promise<ColourStatsResponse>;
+    /**
+     * Find materials that go with a WHOLE PALETTE — N colours at once, not one
+     * colour repeated (POST `/api/v1/search/palettes`).
+     *
+     * Each colour scores `sim × prop`: `sim` is OKLab closeness on the same
+     * mapping `byColour` ranks with, and `prop` rewards a candidate whose own
+     * swatch SHARE sits near the `proportion` you asked for. So the same colours
+     * at different proportions come back in a different order — a colour at 60%
+     * of the surface is a different query from one at 5%. `logic: "all"` (the
+     * default) applies a per-colour eligibility floor and returns the weighted
+     * geometric mean, so a candidate missing one colour is rejected rather than
+     * merely ranked low; `logic: "any"` is a noisy-OR that accepts partial
+     * answers but saturates once several colours score well, so prefer `all`
+     * when the ORDER is what matters.
+     *
+     * Every match carries the candidate's full `palette` plus a per-colour
+     * receipt naming the swatch that answered each queried colour.
+     *
+     * @example
+     * const { matches } = await mg.colours.palette({
+     *   colours: [
+     *     { hex: "F5EFE0", proportion: 0.6 },
+     *     { hex: "9CAF88", proportion: 0.2 },
+     *     { hex: "3E3B36", proportion: 0.2 },
+     *   ],
+     * });
+     */
+    palette(input: SearchPaletteInput, signal?: AbortSignal): Promise<SearchPaletteResponse>;
+    /**
+     * Find materials that move ALONG a colour transition — "cream to rust", in
+     * order (POST `/api/v1/search/gradients`).
+     *
+     * Not a palette: the score is multiplied by `coverage`, the share of the path
+     * the candidate actually spans, so a material owning only one end ranks below
+     * one that travels the whole way, and a flat single-colour material is
+     * rejected outright however close its hue sits to the path.
+     */
+    gradient(input: SearchGradientInput, signal?: AbortSignal): Promise<SearchGradientResponse>;
 }

package/colours-client.js

@@ -15,6 +15,13 @@ export class ColoursClient {
      * cannot recover that spread from a truncated frequency list, which is why it
      * is a server mode rather than a local sort.
      *
+     * `groupBy: "merged"` merges across the KEYS as well and returns ONE profile
+     * over the union of their leaves — the palette of a caller-defined facet such
+     * as "Wood" (`wood_surface` + `wood_flooring`) that the taxonomy holds no
+     * single node for, and that no combination of per-key responses reconstructs.
+     * Its keys may sit at either tier, `categoryKey` is those keys sorted and
+     * joined with `+`, and `members` hands them back so nothing has to split it.
+     *
      * A selected category with no colour data comes back as a zero-count profile,
      * not a missing key.
      */
@@ -36,4 +43,46 @@ export class ColoursClient {
     stats(signal) {
         return this.#transport.get("get_colour_stats", undefined, signal);
     }
+    /**
+     * Find materials that go with a WHOLE PALETTE — N colours at once, not one
+     * colour repeated (POST `/api/v1/search/palettes`).
+     *
+     * Each colour scores `sim × prop`: `sim` is OKLab closeness on the same
+     * mapping `byColour` ranks with, and `prop` rewards a candidate whose own
+     * swatch SHARE sits near the `proportion` you asked for. So the same colours
+     * at different proportions come back in a different order — a colour at 60%
+     * of the surface is a different query from one at 5%. `logic: "all"` (the
+     * default) applies a per-colour eligibility floor and returns the weighted
+     * geometric mean, so a candidate missing one colour is rejected rather than
+     * merely ranked low; `logic: "any"` is a noisy-OR that accepts partial
+     * answers but saturates once several colours score well, so prefer `all`
+     * when the ORDER is what matters.
+     *
+     * Every match carries the candidate's full `palette` plus a per-colour
+     * receipt naming the swatch that answered each queried colour.
+     *
+     * @example
+     * const { matches } = await mg.colours.palette({
+     *   colours: [
+     *     { hex: "F5EFE0", proportion: 0.6 },
+     *     { hex: "9CAF88", proportion: 0.2 },
+     *     { hex: "3E3B36", proportion: 0.2 },
+     *   ],
+     * });
+     */
+    palette(input, signal) {
+        return this.#transport.post("search_by_palette", input, signal);
+    }
+    /**
+     * Find materials that move ALONG a colour transition — "cream to rust", in
+     * order (POST `/api/v1/search/gradients`).
+     *
+     * Not a palette: the score is multiplied by `coverage`, the share of the path
+     * the candidate actually spans, so a material owning only one end ranks below
+     * one that travels the whole way, and a flat single-colour material is
+     * rejected outright however close its hue sits to the path.
+     */
+    gradient(input, signal) {
+        return this.#transport.post("search_by_gradient", input, signal);
+    }
 }

package/index.d.ts

@@ -21,6 +21,7 @@ export type * from "./codes-types.js";
 export { ColoursClient } from "./colours-client.js";
 export type { ColoursTransport } from "./colours-client.js";
 export type * from "./colour-aggregate-types.js";
+export type * from "./palette-search-types.js";
 export type * from "./brand-types.js";
 export type * from "./material-asset-types.js";
 export type * from "./material-block-types.js";

package/operations.d.ts

@@ -1,5 +1,5 @@
 export declare const MATERIALGRAPH_API_VERSION = "0.7.0";
-declare const OPERATION_DEFINITIONS: readonly [readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["searchGet", "GET", "/api/v1/search", "search_materials_get"], readonly ["match", "POST", "/api/v1/search/match", "match_material"], readonly ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"], readonly ["material", "GET", "/api/v1/materials/{variantId}", "get_material"], readonly ["siblings", "GET", "/api/v1/materials/{variantId}/siblings", "get_material_siblings"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["materialAssets", "GET", "/api/v1/materials/{variantId}/assets", "list_material_assets"], readonly ["schema", "GET", "/api/v1/schema/blocks", "list_schema_blocks"], readonly ["schema", "GET", "/api/v1/schema/attributes", "list_schema_attributes"], readonly ["schema", "GET", "/api/v1/schema/verticals", "list_schema_verticals"], readonly ["schema", "GET", "/api/v1/schema/product-types", "list_schema_product_types"], readonly ["schema", "GET", "/api/v1/schema/units", "list_schema_units"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["schema", "GET", "/api/v1/schema/source-requirements", "list_schema_source_requirements"], readonly ["schema", "GET", "/api/v1/schema/product-type-templates", "list_schema_product_type_templates"], readonly ["schema", "GET", "/api/v1/schema/mappings", "list_schema_mappings"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"], readonly ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"], readonly ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"], readonly ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"], readonly ["colours.profiles", "GET", "/api/v1/colours/profiles", "get_category_colour_profiles"], readonly ["colours.stats", "GET", "/api/v1/colours/stats", "get_colour_stats"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"], readonly ["suggest", "GET", "/api/v1/search/suggest", "search_suggest"], readonly ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"], readonly ["resolveAttributeValue", "GET", "/api/v1/catalog/attributes/{attributeId}/values/resolve", "catalog_resolve_value"], readonly ["searchVocabulary", "GET", "/api/v1/catalog/vocabulary/search", "catalog_vocabulary_search"], readonly ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"], readonly ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"], readonly ["demand", "GET", "/api/v1/demand", "get_material_demand"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"], readonly ["attributeValues", "GET", "/api/v1/catalog/attributes/{attributeId}/values", "list_attribute_values"], readonly ["applicableSpecs", "GET", "/api/v1/taxonomy/categories/{key}/specs", "get_applicable_specs"], readonly ["glossary", "GET", "/api/v1/glossary/{term}", "explain_material_term"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["brand", "GET", "/api/v1/brands/{brandSlug}", "get_brand_profile"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"], readonly ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"], readonly ["createRun", "POST", "/api/v1/runs", "create_public_run"], readonly ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"], readonly ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"], readonly ["streamRunEvents", "GET", "/api/v1/runs/{runId}/events", "list_public_run_events"], readonly ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"], readonly ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"], readonly ["varyScheme", "POST", "/api/v1/schemes/vary", "vary_schemes"], readonly ["createProject", "POST", "/api/v1/projects", "create_box_project"], readonly ["listProjects", "GET", "/api/v1/projects", "list_box_projects"], readonly ["getProject", "GET", "/api/v1/projects/{projectId}", "get_box_project"], readonly ["appendProjectEvent", "POST", "/api/v1/projects/{projectId}/events", "append_box_project_event"], readonly ["demandBatch", "POST", "/api/v1/demand/batch", "get_demand_batch"], readonly ["codeAdvisory", "POST", "/api/v1/codes/advisory", "resolveCodeAdvisory"], readonly ["codes.context", "GET", "/api/v1/codes/context", "list_code_context"], readonly ["codes.requirements", "GET", "/api/v1/codes/requirements", "list_code_requirements"]];
+declare const OPERATION_DEFINITIONS: readonly [readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["searchGet", "GET", "/api/v1/search", "search_materials_get"], readonly ["match", "POST", "/api/v1/search/match", "match_material"], readonly ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"], readonly ["material", "GET", "/api/v1/materials/{variantId}", "get_material"], readonly ["siblings", "GET", "/api/v1/materials/{variantId}/siblings", "get_material_siblings"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["materialAssets", "GET", "/api/v1/materials/{variantId}/assets", "list_material_assets"], readonly ["schema", "GET", "/api/v1/schema/blocks", "list_schema_blocks"], readonly ["schema", "GET", "/api/v1/schema/attributes", "list_schema_attributes"], readonly ["schema", "GET", "/api/v1/schema/verticals", "list_schema_verticals"], readonly ["schema", "GET", "/api/v1/schema/product-types", "list_schema_product_types"], readonly ["schema", "GET", "/api/v1/schema/units", "list_schema_units"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["schema", "GET", "/api/v1/schema/source-requirements", "list_schema_source_requirements"], readonly ["schema", "GET", "/api/v1/schema/product-type-templates", "list_schema_product_type_templates"], readonly ["schema", "GET", "/api/v1/schema/mappings", "list_schema_mappings"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"], readonly ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"], readonly ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"], readonly ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"], readonly ["colours.profiles", "GET", "/api/v1/colours/profiles", "get_category_colour_profiles"], readonly ["colours.stats", "GET", "/api/v1/colours/stats", "get_colour_stats"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"], readonly ["suggest", "GET", "/api/v1/search/suggest", "search_suggest"], readonly ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"], readonly ["resolveAttributeValue", "GET", "/api/v1/catalog/attributes/{attributeId}/values/resolve", "catalog_resolve_value"], readonly ["searchVocabulary", "GET", "/api/v1/catalog/vocabulary/search", "catalog_vocabulary_search"], readonly ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"], readonly ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"], readonly ["demand", "GET", "/api/v1/demand", "get_material_demand"], readonly ["colours.palette", "POST", "/api/v1/search/palettes", "search_by_palette"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["colours.gradient", "POST", "/api/v1/search/gradients", "search_by_gradient"], readonly ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"], readonly ["attributeValues", "GET", "/api/v1/catalog/attributes/{attributeId}/values", "list_attribute_values"], readonly ["applicableSpecs", "GET", "/api/v1/taxonomy/categories/{key}/specs", "get_applicable_specs"], readonly ["glossary", "GET", "/api/v1/glossary/{term}", "explain_material_term"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["brand", "GET", "/api/v1/brands/{brandSlug}", "get_brand_profile"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"], readonly ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"], readonly ["createRun", "POST", "/api/v1/runs", "create_public_run"], readonly ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"], readonly ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"], readonly ["streamRunEvents", "GET", "/api/v1/runs/{runId}/events", "list_public_run_events"], readonly ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"], readonly ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"], readonly ["varyScheme", "POST", "/api/v1/schemes/vary", "vary_schemes"], readonly ["createProject", "POST", "/api/v1/projects", "create_box_project"], readonly ["listProjects", "GET", "/api/v1/projects", "list_box_projects"], readonly ["getProject", "GET", "/api/v1/projects/{projectId}", "get_box_project"], readonly ["appendProjectEvent", "POST", "/api/v1/projects/{projectId}/events", "append_box_project_event"], readonly ["demandBatch", "POST", "/api/v1/demand/batch", "get_demand_batch"], readonly ["codeAdvisory", "POST", "/api/v1/codes/advisory", "resolveCodeAdvisory"], readonly ["codes.context", "GET", "/api/v1/codes/context", "list_code_context"], readonly ["codes.requirements", "GET", "/api/v1/codes/requirements", "list_code_requirements"]];
 export type SdkOperationId = (typeof OPERATION_DEFINITIONS)[number][3];
 export type SdkOperation = Readonly<{
     clientMethod: (typeof OPERATION_DEFINITIONS)[number][0];

package/operations.js

@@ -40,7 +40,9 @@ const OPERATION_DEFINITIONS = [
     ["whoami", "GET", "/api/v1/whoami", "whoami"],
     ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"],
     ["demand", "GET", "/api/v1/demand", "get_material_demand"],
+    ["colours.palette", "POST", "/api/v1/search/palettes", "search_by_palette"],
     ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"],
+    ["colours.gradient", "POST", "/api/v1/search/gradients", "search_by_gradient"],
     ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"],
     [
         "attributeValues",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "exports": {
     ".": {

package/palette-search-types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Wire types for MULTI-COLOUR search — `POST /api/v1/search/palettes` and
+ * `POST /api/v1/search/gradients`.
+ *
+ * Kept out of `types.ts` for the same reason `colour-aggregate-types.ts` and
+ * `codes-types.ts` are: 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.
+ *
+ * The MATCH SEMANTICS these types carry are the server's, stated on
+ * {@link SearchPaletteInput.logic} and {@link GradientMatch.coverage} rather
+ * than left to the endpoint docs.
+ */
+import type { OklabTriple, OpenEnum } from "./types.js";
+/** How the per-colour scores are combined across a palette. */
+export type PaletteLogic = OpenEnum<"all" | "any">;
+/** One queried palette colour — exactly one of `hex` or `oklab`. */
+export interface PaletteQueryColour {
+    hex?: string;
+    oklab?: OklabTriple;
+    /**
+     * Share of the surface this colour should occupy, in (0,1]. Stating it
+     * CHANGES the ranking: a colour asked for at 0.6 rewards candidates whose own
+     * swatch sits near 0.6, not merely candidates that contain the colour.
+     */
+    proportion?: number;
+    /** Relative importance; defaults to 1 and is normalised across the query. */
+    weight?: number;
+}
+/** One gradient stop — exactly one of `hex` or `oklab`. Order is meaningful. */
+export interface GradientStop {
+    hex?: string;
+    oklab?: OklabTriple;
+}
+export interface SearchPaletteInput {
+    /** The palette to match, 1–8 colours. */
+    colours: PaletteQueryColour[];
+    /**
+     * `all` (the default) requires every queried colour to clear a per-colour
+     * eligibility floor and scores the weighted geometric mean; `any` is a
+     * noisy-OR and never rejects a candidate for missing one colour.
+     */
+    logic?: PaletteLogic;
+    /** Results to return; defaults to 24, capped at 48. */
+    limit?: number;
+}
+export interface SearchGradientInput {
+    /** The ordered colour transition, 2–6 stops. */
+    stops: GradientStop[];
+    /** Results to return; defaults to 24, capped at 48. */
+    limit?: number;
+}
+/** One swatch of a candidate's colorscope-extracted palette. */
+export interface CandidateSwatch {
+    hex: string;
+    proportion: number;
+    name: string | null;
+}
+/** Why a queried colour (or gradient sample) scored what it scored. */
+export interface ColourMatchReceipt {
+    queryHex: string;
+    /** `colourScore × proportionScore` for the best-matching swatch. */
+    score: number;
+    /** OKLab closeness alone, in [0,1]. */
+    colourScore: number;
+    /** Proportion agreement alone, in [0,1]. */
+    proportionScore: number;
+    /** The swatch that produced the score, or null when nothing matched. */
+    matched: CandidateSwatch | null;
+}
+/** Identity and evidence shared by both multi-colour match shapes. */
+export interface MultiColourMatchBase {
+    variantId: string;
+    brand: string;
+    product: string;
+    brandSlug: string | null;
+    productId: string | null;
+    color: string | null;
+    variantName: string | null;
+    imageUrl: string | null;
+    /** MB has retired or hidden this SKU. */
+    retired: boolean;
+    /** The candidate's full extracted palette — the evidence scored against. */
+    palette: CandidateSwatch[];
+    /** The aggregate match score in [0,1]; higher is closer. */
+    score: number;
+}
+export interface PaletteMatch extends MultiColourMatchBase {
+    /** One receipt per queried colour, in query order. */
+    colours: ColourMatchReceipt[];
+}
+export interface GradientMatch extends MultiColourMatchBase {
+    /**
+     * Distinct matched thirds of the path over 3. A material owning only one end
+     * of the transition caps out around 0.33 — coverage is what separates a real
+     * gradient match from a good match on a single stop.
+     */
+    coverage: number;
+    /** One receipt per sampled point along the path, in path order. */
+    samples: ColourMatchReceipt[];
+}
+export interface SearchPaletteResponse {
+    query: {
+        colours: Array<{
+            hex: string;
+            proportion?: number;
+            weight?: number;
+        }>;
+        logic: PaletteLogic;
+    };
+    count: number;
+    matches: PaletteMatch[];
+}
+export interface SearchGradientResponse {
+    query: {
+        stops: string[];
+        /** The sampled path points the search actually ran against. */
+        samples: string[];
+    };
+    count: number;
+    matches: GradientMatch[];
+}

package/palette-search-types.js

@@ -0,0 +1 @@
+export {};