@instruments/materialgraph 0.19.0 → 0.21.0

package/match-types.d.ts

@@ -1,3 +1,4 @@
+import type { ResponseAttribution } from "./attribution-types.js";
 import type { CorpusScope } from "./corpus-scope-types.js";
 /**
  * @module sdk/match-types
@@ -37,6 +38,15 @@ export interface MatchColourReading {
     measurable: boolean;
 }
 export interface MatchResponse {
+    /**
+     * Result attribution (MG-1131). `basis` is always `"match"` here — this route
+     * has no `mode`, so this is the field that lets a Match outcome be grouped
+     * alongside a `search()` one. Store it beside the query and each item's
+     * `resultId` beside the outcome.
+     *
+     * ABSENT only from a response produced by a server predating MG-1131.
+     */
+    attribution?: ResponseAttribution;
     /** THIS answer, capped by `limit`. Not a total. */
     results: SearchResultItem[];
     inferredCategories: MatchCategoryInference[];

package/material-block-types.d.ts

@@ -52,6 +52,10 @@ export interface MaterialBlockProjectionField {
     value: MaterialBlockFieldValue;
     unit?: string;
     status: MaterialBlockFieldStatus;
+    /** Provenance supplied by the graph when a source-backed claim supports this field. */
+    sourceBasis?: string;
+    /** Claim confidence supplied by the graph; absence means no confidence was emitted. */
+    confidence?: number;
 }
 export interface MaterialBlockProjectionItem {
     canonicalBlockId: string;

package/operations.d.ts

@@ -1,5 +1,5 @@
 export declare const MATERIALGRAPH_API_VERSION = "0.7.0";
-declare const OPERATION_DEFINITIONS: readonly [readonly ["scheduleReferences.list", "GET", "/api/v1/schedules/{scheduleId}/references", "list_schedule_reference_feedback"], readonly ["scheduleReferences.put", "PUT", "/api/v1/schedules/{scheduleId}/references/{referenceId}", "put_schedule_reference_feedback"], readonly ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"], readonly ["catalogPages", "GET", "/api/v1/catalogs/{catalogId}/pages", "list_catalog_pages"], readonly ["catalogPageRepresentation", "GET", "/api/v1/catalog-pages/{pageId}/representation", "get_catalog_page_representation"], readonly ["catalogReferences", "GET", "/api/v1/catalogs/{catalogId}/references", "list_catalog_product_references"], readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["planQuery", "POST", "/api/v1/search/plan", "plan_material_query"], readonly ["samplizeCatalogue", "GET", "/api/v1/catalogues/samplize/products", "samplize_catalogue_products"], 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 ["catalogueReferences", "POST", "/api/v1/catalogues/references", "get_catalogue_references_batch"], readonly ["catalogueCollections", "GET", "/api/v1/catalogues/collections", "list_catalogue_channel_collections"], readonly ["catalogueDocumentAccess", "GET", "/api/v1/catalogues/documents/{documentId}", "get_catalogue_document_access"], 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 ["materialRenderAssets", "GET", "/api/v1/materials/{variantId}/render-assets", "get_material_render_assets"], readonly ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], readonly ["exploration.operators", "GET", "/api/v1/materials/{variantId}/operators", "list_material_operators"], readonly ["exploration.candidates", "POST", "/api/v1/materials/{variantId}/candidates", "read_material_candidates"], 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 ["findSubstitutes", "POST", "/api/v1/materials/{variantId}/substitutes", "find_material_substitutes"], readonly ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"], readonly ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"], readonly ["applicability", "GET", "/api/v1/applicability", "get_applicability"], 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 ["resolve", "POST", "/api/v1/resolve", "resolve_phrases"], readonly ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"], readonly ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"], readonly ["productTypeCoverage", "GET", "/api/v1/taxonomy/coverage", "get_product_type_status_coverage"], 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 ["brandColourDeck", "GET", "/api/v1/brands/{brandSlug}/colours", "brand_colour_deck"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"], readonly ["sourceMaterialComments", "GET", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "list_source_material_comments"], readonly ["sourceMaterialComments", "POST", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "post_source_material_comment"], readonly ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"], readonly ["createRun", "POST", "/api/v1/runs", "create_public_run"], readonly ["listRuns", "GET", "/api/v1/runs", "list_public_runs"], readonly ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"], readonly ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"], readonly ["citation", "GET", "/api/v1/citations/{citationId}", "get_verdict_citation"], 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 ["slotPools", "POST", "/api/v1/schemes/pools", "slot_pools"], 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 ["brandMostSampled", "GET", "/api/v1/brands/most-sampled", "brands.most_sampled"], readonly ["colours.complete", "POST", "/api/v1/colours/palettes/complete", "complete_interior_palette"], readonly ["colours.discover", "GET", "/api/v1/colours/palettes", "discover_interior_palettes"], readonly ["samplizeColorVecCache", "GET", "/api/v1/catalogues/samplize/colorvec", "samplize_colorvec_cache"], readonly ["samplizeCatalogueSearch", "POST", "/api/v1/catalogues/samplize/search", "samplize_catalogue_search"], readonly ["scheduleReferences.list", "GET", "/api/v1/schedules/{scheduleId}/references", "list_schedule_reference_feedback"], readonly ["scheduleReferences.put", "PUT", "/api/v1/schedules/{scheduleId}/references/{referenceId}", "put_schedule_reference_feedback"], readonly ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"], readonly ["catalogPages", "GET", "/api/v1/catalogs/{catalogId}/pages", "list_catalog_pages"], readonly ["catalogPageRepresentation", "GET", "/api/v1/catalog-pages/{pageId}/representation", "get_catalog_page_representation"], readonly ["catalogReferences", "GET", "/api/v1/catalogs/{catalogId}/references", "list_catalog_product_references"], readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["identify", "POST", "/api/v1/identify", "retrieval.identify"], readonly ["compare", "POST", "/api/v1/compare", "retrieval.compare"], readonly ["createCorrection", "POST", "/api/v1/corrections", "corrections.create"], readonly ["getCorrection", "GET", "/api/v1/corrections/{correctionId}", "corrections.get"], readonly ["listCorrections", "GET", "/api/v1/corrections", "corrections.list"], readonly ["planQuery", "POST", "/api/v1/search/plan", "plan_material_query"], readonly ["samplizeCatalogue", "GET", "/api/v1/catalogues/samplize/products", "samplize_catalogue_products"], 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 ["catalogueReferences", "POST", "/api/v1/catalogues/references", "get_catalogue_references_batch"], readonly ["catalogueCollections", "GET", "/api/v1/catalogues/collections", "list_catalogue_channel_collections"], readonly ["catalogueDocumentAccess", "GET", "/api/v1/catalogues/documents/{documentId}", "get_catalogue_document_access"], 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 ["materialRenderAssets", "GET", "/api/v1/materials/{variantId}/render-assets", "get_material_render_assets"], readonly ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], readonly ["exploration.operators", "GET", "/api/v1/materials/{variantId}/operators", "list_material_operators"], readonly ["exploration.candidates", "POST", "/api/v1/materials/{variantId}/candidates", "read_material_candidates"], 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 ["findSubstitutes", "POST", "/api/v1/materials/{variantId}/substitutes", "find_material_substitutes"], readonly ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"], readonly ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"], readonly ["applicability", "GET", "/api/v1/applicability", "get_applicability"], 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 ["resolve", "POST", "/api/v1/resolve", "resolve_phrases"], readonly ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"], readonly ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"], readonly ["productTypeCoverage", "GET", "/api/v1/taxonomy/coverage", "get_product_type_status_coverage"], 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 ["brandColourDeck", "GET", "/api/v1/brands/{brandSlug}/colours", "brand_colour_deck"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"], readonly ["sourceMaterialComments.list", "GET", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "list_source_material_comments"], readonly ["sourceMaterialComments.post", "POST", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "post_source_material_comment"], readonly ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"], readonly ["createRun", "POST", "/api/v1/runs", "create_public_run"], readonly ["listRuns", "GET", "/api/v1/runs", "list_public_runs"], readonly ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"], readonly ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"], readonly ["citation", "GET", "/api/v1/citations/{citationId}", "get_verdict_citation"], 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 ["slotPools", "POST", "/api/v1/schemes/pools", "slot_pools"], 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

@@ -1,6 +1,36 @@
 import { MaterialGraphError } from "./errors.js";
 export const MATERIALGRAPH_API_VERSION = "0.7.0";
 const OPERATION_DEFINITIONS = [
+    [
+        "brandMostSampled",
+        "GET",
+        "/api/v1/brands/most-sampled",
+        "brands.most_sampled",
+    ],
+    [
+        "colours.complete",
+        "POST",
+        "/api/v1/colours/palettes/complete",
+        "complete_interior_palette",
+    ],
+    [
+        "colours.discover",
+        "GET",
+        "/api/v1/colours/palettes",
+        "discover_interior_palettes",
+    ],
+    [
+        "samplizeColorVecCache",
+        "GET",
+        "/api/v1/catalogues/samplize/colorvec",
+        "samplize_colorvec_cache",
+    ],
+    [
+        "samplizeCatalogueSearch",
+        "POST",
+        "/api/v1/catalogues/samplize/search",
+        "samplize_catalogue_search",
+    ],
     [
         "scheduleReferences.list",
         "GET",
@@ -33,6 +63,16 @@ const OPERATION_DEFINITIONS = [
         "list_catalog_product_references",
     ],
     ["search", "POST", "/api/v1/search", "search_materials_post"],
+    ["identify", "POST", "/api/v1/identify", "retrieval.identify"],
+    ["compare", "POST", "/api/v1/compare", "retrieval.compare"],
+    ["createCorrection", "POST", "/api/v1/corrections", "corrections.create"],
+    [
+        "getCorrection",
+        "GET",
+        "/api/v1/corrections/{correctionId}",
+        "corrections.get",
+    ],
+    ["listCorrections", "GET", "/api/v1/corrections", "corrections.list"],
     ["planQuery", "POST", "/api/v1/search/plan", "plan_material_query"],
     [
         "samplizeCatalogue",
@@ -270,13 +310,13 @@ const OPERATION_DEFINITIONS = [
         "get_source_material_batch",
     ],
     [
-        "sourceMaterialComments",
+        "sourceMaterialComments.list",
         "GET",
         "/api/v1/source-material/{batchId}/sources/{sourceId}/comments",
         "list_source_material_comments",
     ],
     [
-        "sourceMaterialComments",
+        "sourceMaterialComments.post",
         "POST",
         "/api/v1/source-material/{batchId}/sources/{sourceId}/comments",
         "post_source_material_comment",

package/package.json

@@ -1,13 +1,24 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "type": "module",
   "exports": {
     ".": {
       "types": "./index.d.ts",
       "import": "./index.js"
+    },
+    "./webmcp": {
+      "types": "./webmcp.d.ts",
+      "import": "./webmcp.js"
+    },
+    "./samplize-colorvec": {
+      "types": "./samplize-colorvec.d.ts",
+      "import": "./samplize-colorvec.js"
     }
   },
+  "dependencies": {
+    "@instruments/colorscope": "7.6.0"
+  },
   "license": "Proprietary",
   "engines": {
     "node": ">=24.0.0"

package/palette-completion-types.d.ts

@@ -0,0 +1,115 @@
+/** Public wire types; the SDK does not load the producer corpus. */
+export type CompositionalRole = "Foundation" | "Supporting" | "Accent";
+export interface RetainedColor {
+    readonly id: string;
+    readonly hex: string;
+    readonly role?: CompositionalRole;
+    readonly paintVariantId?: string;
+}
+export interface CompletionRequest {
+    readonly inputs: readonly RetainedColor[];
+    readonly maxDistance?: number;
+    readonly limit?: number;
+    readonly white?: "published" | "perceptual";
+    readonly memberCount?: number;
+    readonly excludeHexes?: readonly string[];
+}
+export interface CompletionAssignment {
+    readonly input: RetainedColor;
+    readonly referenceIndex: number;
+    readonly referenceHex: string;
+    readonly distance: number;
+}
+export interface CompletionMember {
+    readonly hex: string;
+    readonly referenceHex: string;
+    readonly referenceIndex: number;
+    readonly inputIds: readonly string[];
+    readonly role: CompositionalRole;
+    readonly proportion: number;
+    readonly sourceRole: string | null;
+    readonly sourceRelation: string | null;
+}
+export interface PaletteCompletion {
+    readonly uses?: readonly {
+        readonly inputId: string;
+        readonly role: CompositionalRole;
+        readonly proportions: readonly number[];
+    }[];
+    readonly id: string;
+    readonly reference: {
+        readonly anchorIndex?: number | null;
+        readonly libraryId: string;
+        readonly paletteId: string;
+        readonly name: string | null;
+        readonly maker: string | null;
+        readonly intent: "joint" | "alternatives";
+        readonly provenance: "authored" | "derived" | "generated";
+    };
+    readonly assignments: readonly CompletionAssignment[];
+    readonly members: readonly CompletionMember[];
+    readonly evidenceBasis: "published-composition" | "published-pair" | "nearby-adaptation";
+    readonly proportionBasis: "sourced" | "proposed";
+    readonly worstDistance: number;
+    readonly totalDistance: number;
+}
+export type PaletteCompleteInput = CompletionRequest & {
+    sourceVersion: string;
+};
+export interface PaletteDiscoverInput {
+    sourceVersion: string;
+    character?: "warm" | "cool" | "very-light" | "light" | "dark" | "muted" | "soft" | "vivid";
+    moreLike?: string;
+    cursor?: string;
+    limit?: number;
+}
+export interface MaterializedPalette {
+    completion: PaletteCompletion;
+    samples: Array<{
+        retainedPaint?: {
+            variantId: string;
+            name: string;
+            maker: string;
+        };
+        referenceIndex: number;
+        inputIds: readonly string[];
+        hex: string;
+        product: {
+            variantId: string;
+            productId: string;
+            hex: string;
+            name: string;
+            brand: {
+                slug: string;
+                name: string;
+            };
+        } | null;
+        status: string;
+        distance: number | null;
+        units: "oklab-euclidean";
+    }>;
+}
+interface PaletteVersions {
+    sourceVersion: string;
+    corpusVersion: string;
+    algorithmVersion: string;
+    transport: "colorscope-package";
+}
+export interface PaletteCompleteResponse extends PaletteVersions {
+    results: MaterializedPalette[];
+    coverage: {
+        status: string;
+        supported: number;
+    };
+    tolerance: {
+        bound: number;
+        units: string;
+        policy: string;
+    };
+}
+export interface PaletteDiscoverResponse extends PaletteVersions {
+    results: MaterializedPalette[];
+    total: number;
+    nextCursor: string | null;
+}
+export {};

package/palette-completion-types.js

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

package/samplize-colorvec.d.ts

@@ -0,0 +1,70 @@
+export declare const SAMPLIZE_COLORVEC_RANKING_VERSION = "solid-colorvec-cosine-v2";
+export declare const SAMPLIZE_COLORVEC_EMBEDDING_VERSION = "oklch-anchor-quantiles-v12";
+export interface SamplizeColorVecPaint {
+    variantId: string;
+    hex: string;
+    brand: string;
+    oklab: {
+        L: number;
+        a: number;
+        b: number;
+    };
+    family: string;
+    lightness: string;
+    intensity: string;
+    vector: number[] | string;
+}
+export interface SamplizeColorVecCache {
+    sourceVersion: string;
+    dictionaryVersion: string;
+    embeddingVersion: string;
+    rankingVersion: string;
+    generatedAt: string;
+    paints: SamplizeColorVecPaint[];
+}
+export interface SamplizeColorVecInput {
+    hex?: string;
+    reference?: string;
+    palette?: Array<{
+        hex: string;
+        proportion: number;
+    }>;
+    direction?: "similar" | "lighter" | "darker" | "muted";
+    brand?: string[];
+    family?: string[];
+    lightness?: string[];
+    intensity?: string[];
+    lightnessMin?: number;
+    lightnessMax?: number;
+    temperatureMin?: number;
+    temperatureMax?: number;
+    limit?: number;
+}
+export declare const samplizeSolidColorVector: (hex: string) => number[];
+/** Canonical constraints are shared by full-cache similarity and constrained text retrieval. */
+export declare function selectSamplizeEligiblePaints<T extends Omit<SamplizeColorVecPaint, "vector">>(paints: T[], input: SamplizeColorVecInput): {
+    reference: T | undefined;
+    eligible: T[];
+    counts: Record<"brand" | "family" | "intensity" | "lightness", Record<string, number>>;
+};
+/** Official portable MG ranking over its complete versioned sampling-channel projection. */
+export declare function createSamplizeColorVecIndex(cache: SamplizeColorVecCache): {
+    search(input: SamplizeColorVecInput): {
+        ids: string[];
+        groups: {
+            hex: string;
+            proportion: number;
+            quota: number;
+            ids: string[];
+            shortfall: number;
+        }[];
+        limited: boolean;
+        eligibleCount: number;
+        counts: Record<"brand" | "family" | "intensity" | "lightness", Record<string, number>>;
+        sourceVersion: string;
+        dictionaryVersion: string;
+        embeddingVersion: string;
+        rankingVersion: string;
+        countBasis: "complete-catalogue";
+    };
+};

package/samplize-colorvec.js

@@ -0,0 +1,167 @@
+import { EMBEDDING_VERSION, EMBEDDING_VECTOR_SIZE, embeddingCosineSimilarity, paletteToEmbedding, } from "@instruments/colorscope/embedding";
+export const SAMPLIZE_COLORVEC_RANKING_VERSION = "solid-colorvec-cosine-v2";
+export const SAMPLIZE_COLORVEC_EMBEDDING_VERSION = EMBEDDING_VERSION;
+const decodeVector = (encoded) => {
+    const bytes = Uint8Array.from(atob(encoded), (c) => c.charCodeAt(0));
+    if (bytes.length !== EMBEDDING_VECTOR_SIZE * 4)
+        throw new Error("Invalid colour vector size.");
+    const view = new DataView(bytes.buffer);
+    return Array.from({ length: EMBEDDING_VECTOR_SIZE }, (_, i) => view.getFloat32(i * 4, true));
+};
+const facets = ["brand", "family", "lightness", "intensity"];
+const identityOrder = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+export const samplizeSolidColorVector = (hex) => {
+    if (!/^#[0-9a-f]{6}$/i.test(hex))
+        throw new Error("A six-digit published colour is required.");
+    return paletteToEmbedding([{ hex, proportion: 1 }], { validateOklab: true });
+};
+/** Canonical constraints are shared by full-cache similarity and constrained text retrieval. */
+export function selectSamplizeEligiblePaints(paints, input) {
+    const reference = input.reference
+        ? paints.find((p) => p.variantId === input.reference)
+        : undefined;
+    if (input.reference && !reference)
+        throw new Error("The reference is absent from this catalogue version.");
+    const low = input.lightnessMin ?? 0, high = input.lightnessMax ?? 1;
+    const cool = input.temperatureMin ?? -0.4, warm = input.temperatureMax ?? 0.4;
+    if (![low, high, cool, warm].every(Number.isFinite) ||
+        low > high ||
+        cool > warm)
+        throw new Error("Appearance ranges must be finite and ordered.");
+    const candidates = paints.filter((p) => {
+        if (!reference)
+            return true;
+        if (p.variantId === reference.variantId)
+            return false;
+        if (input.direction === "lighter")
+            return p.oklab.L > reference.oklab.L;
+        if (input.direction === "darker")
+            return p.oklab.L < reference.oklab.L;
+        if (input.direction === "muted")
+            return (Math.hypot(p.oklab.a, p.oklab.b) <
+                Math.hypot(reference.oklab.a, reference.oklab.b));
+        return true;
+    });
+    const matches = (p, omit) => p.oklab.L >= low &&
+        p.oklab.L <= high &&
+        p.oklab.b >= cool &&
+        p.oklab.b <= warm &&
+        facets.every((f) => f === omit || !input[f]?.length || input[f].includes(p[f]));
+    const counts = {
+        brand: {},
+        family: {},
+        lightness: {},
+        intensity: {},
+    };
+    for (const p of candidates)
+        for (const f of facets)
+            if (matches(p, f))
+                counts[f][p[f]] = (counts[f][p[f]] ?? 0) + 1;
+    const eligible = candidates.filter((p) => matches(p));
+    return { reference, eligible, counts };
+}
+/** Official portable MG ranking over its complete versioned sampling-channel projection. */
+export function createSamplizeColorVecIndex(cache) {
+    if (cache.embeddingVersion !== EMBEDDING_VERSION ||
+        cache.rankingVersion !== SAMPLIZE_COLORVEC_RANKING_VERSION)
+        throw new Error("The colour cache uses an incompatible embedding or ranking version. Refresh it before searching.");
+    if (!cache.sourceVersion ||
+        !cache.dictionaryVersion ||
+        !Number.isFinite(Date.parse(cache.generatedAt)))
+        throw new Error("The colour cache is missing its provenance.");
+    const paints = cache.paints.map((p) => ({
+        ...p,
+        vector: typeof p.vector === "string" ? decodeVector(p.vector) : p.vector,
+    }));
+    const identities = new Set();
+    for (const paint of paints) {
+        if (identities.has(paint.variantId) ||
+            paint.vector.length !== EMBEDDING_VECTOR_SIZE ||
+            !paint.vector.every(Number.isFinite) ||
+            ![paint.oklab.L, paint.oklab.a, paint.oklab.b].every(Number.isFinite))
+            throw new Error("The colour cache contains invalid or duplicate paint records.");
+        identities.add(paint.variantId);
+    }
+    const vectors = new Map();
+    const vectorFor = (hex) => {
+        const key = hex.toLowerCase();
+        let value = vectors.get(key);
+        if (!value) {
+            value = samplizeSolidColorVector(hex);
+            if (vectors.size >= 512)
+                vectors.delete(vectors.keys().next().value);
+            vectors.set(key, value);
+        }
+        return value;
+    };
+    return {
+        search(input) {
+            const limit = input.limit ?? 48;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+                throw new Error("Choose between 1 and 100 suggestions.");
+            const { reference, eligible, counts } = selectSamplizeEligiblePaints(paints, input);
+            const palette = (input.palette?.length
+                ? input.palette
+                : [{ hex: input.hex ?? reference?.hex ?? "", proportion: 1 }])
+                .map((p) => ({ ...p, hex: p.hex.toLowerCase() }))
+                .sort((a, b) => b.proportion - a.proportion || identityOrder(a.hex, b.hex));
+            if (palette.length > 12 ||
+                palette.some((p) => !Number.isFinite(p.proportion) ||
+                    p.proportion <= 0 ||
+                    p.proportion > 1))
+                throw new Error("Supply up to twelve positive image colour shares.");
+            const total = palette.reduce((sum, p) => sum + p.proportion, 0);
+            const buckets = palette.map((p, position) => ({
+                ...p,
+                position,
+                vector: vectorFor(p.hex),
+                quota: Math.floor((limit * p.proportion) / total),
+                remainder: ((limit * p.proportion) / total) % 1,
+                paints: [],
+            }));
+            let remaining = limit - buckets.reduce((sum, p) => sum + p.quota, 0);
+            for (const p of [...buckets].sort((a, b) => b.remainder - a.remainder || a.position - b.position))
+                if (remaining-- > 0)
+                    p.quota++;
+            for (const paint of eligible) {
+                let best = buckets[0], score = embeddingCosineSimilarity(paint.vector, best.vector);
+                for (let i = 1; i < buckets.length; i++) {
+                    const candidate = buckets[i], next = embeddingCosineSimilarity(paint.vector, candidate.vector);
+                    if (next > score) {
+                        best = candidate;
+                        score = next;
+                    }
+                }
+                best.paints.push({ id: paint.variantId, score });
+            }
+            const groups = buckets
+                .sort((a, b) => b.proportion - a.proportion || a.position - b.position)
+                .map((p) => {
+                const ids = p.paints
+                    .sort((a, b) => b.score - a.score || identityOrder(a.id, b.id))
+                    .slice(0, p.quota)
+                    .map((paint) => paint.id);
+                return {
+                    hex: p.hex,
+                    proportion: p.proportion,
+                    quota: p.quota,
+                    ids,
+                    shortfall: p.quota - ids.length,
+                };
+            });
+            const ids = groups.flatMap((p) => p.ids);
+            return {
+                ids,
+                groups,
+                limited: eligible.length > ids.length,
+                eligibleCount: eligible.length,
+                counts,
+                sourceVersion: cache.sourceVersion,
+                dictionaryVersion: cache.dictionaryVersion,
+                embeddingVersion: cache.embeddingVersion,
+                rankingVersion: cache.rankingVersion,
+                countBasis: "complete-catalogue",
+            };
+        },
+    };
+}

package/search-card-types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @module sdk/search-card-types
+ * @description The `view:"card"` search projection — the lean grid item and the
+ * envelope that carries it.
+ *
+ * Split out of `types.ts` — which is over the repository's source-size limit —
+ * along the same seam `match-types.ts` took: one view of one surface, and
+ * nothing else. The full-view item and the shared envelope stay in `types.ts`,
+ * which this module reads `SearchResponse` from.
+ */
+import type { ProductId, VariantId } from "./identifiers.js";
+import type { OpenEnum, SearchData, SearchResponse } from "./types.js";
+/**
+ * The lean `view:"card"` result item — identity + name + thumbnail + score.
+ *
+ * A PROJECTION, not a smaller answer: a field the card omits (palette, verdict,
+ * signals, availability) is unread here, never known-absent. Re-read the same
+ * `variantId` at `view: "full"` or via `material()` before claiming anything the
+ * card does not carry.
+ */
+export interface SearchCardItem {
+    /** Accepted sampleability fact. Absent means unknown, never false. */
+    sampleable?: boolean;
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
+    productId: ProductId | null;
+    brandSlug: string | null;
+    brand: string;
+    /** Product name (the full item's `product`). */
+    name: string;
+    variantName: string | null;
+    imageUrl: string | null;
+    projectSaveCapability?: "allowed";
+    sourceStatus?: "provisional";
+    score: number;
+    /**
+     * Resolved values for the attribute ids sent in `returnAttributes`, keyed by
+     * attribute id. ABSENT entirely when `returnAttributes` was not sent.
+     *
+     * Three states, all different, and reading them as two is the mistake this
+     * shape exists to prevent: no `attributes` key means you did not ask; a key
+     * whose value is `null` means this material carries no accepted value for that
+     * attribute; anything else is what the graph holds. Values resolve with the
+     * normal variant-over-product precedence, and an array is a multi-valued
+     * attribute rather than a list of candidates.
+     */
+    attributes?: Record<string, string | string[] | null>;
+}
+/** The `view:"card"` response form — the lean grid projection of {@link SearchResponse}. */
+export interface SearchCardResponse extends Omit<SearchResponse, "data"> {
+    data: Omit<SearchData, "view" | "results"> & {
+        view: OpenEnum<"card">;
+        results: SearchCardItem[];
+    };
+}

package/search-card-types.js

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

package/search-response-types.d.ts

@@ -0,0 +1,11 @@
+import type { SearchData } from "./types.js";
+/** Canonical Search wire response. Raw SDK methods preserve this envelope. */
+export interface SearchResponse {
+    data: SearchData;
+    meta: {
+        operationId: "search_materials_post" | "search_materials_get";
+        requestId: string;
+    };
+    links: Record<string, never>;
+    warnings: never[];
+}

package/search-response-types.js

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