@instruments/materialgraph 0.24.0 → 0.26.0

package/palette-search-types.d.ts

@@ -17,7 +17,7 @@ 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 {
+export type PaletteQueryColour = {
     hex?: string;
     oklab?: OklabTriple;
     /**
@@ -28,13 +28,13 @@ export interface PaletteQueryColour {
     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 {
+export type GradientStop = {
     hex?: string;
     oklab?: OklabTriple;
-}
-export interface SearchPaletteInput {
+};
+export type SearchPaletteInput = {
     corpusScope?: CorpusScope;
     /** The palette to match, 1–8 colours. */
     colours: PaletteQueryColour[];
@@ -46,26 +46,26 @@ export interface SearchPaletteInput {
     logic?: PaletteLogic;
     /** Results to return; defaults to 24, capped at 48. */
     limit?: number;
-}
-export interface SearchGradientInput {
+};
+export type SearchGradientInput = {
     corpusScope?: CorpusScope;
     /** The ordered colour transition, 2–6 stops. */
     stops: GradientStop[];
     /** Results to return; defaults to 24, capped at 48. */
     limit?: number;
-}
+};
 /**
  * One swatch used for scoring. Samplize paint uses its selected published hex;
  * other materials use colorscope palettes extracted from imagery. `name` is null when no human
  * name was resolved — unnamed, not colourless.
  */
-export interface CandidateSwatch {
+export type CandidateSwatch = {
     hex: string;
     proportion: number;
     name: string | null;
-}
+};
 /** Why a queried colour (or gradient sample) scored what it scored. */
-export interface ColourMatchReceipt {
+export type ColourMatchReceipt = {
     queryHex: string;
     /** `colourScore × proportionScore` for the best-matching swatch. */
     score: number;
@@ -75,9 +75,9 @@ export interface ColourMatchReceipt {
     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 {
+export type MultiColourMatchBase = {
     /** Opaque — round-trip verbatim. */
     variantId: VariantId;
     brand: string;
@@ -105,12 +105,12 @@ export interface MultiColourMatchBase {
     palette: CandidateSwatch[];
     /** The aggregate match score in [0,1]; higher is closer. */
     score: number;
-}
-export interface PaletteMatch extends MultiColourMatchBase {
+};
+export type PaletteMatch = {
     /** One receipt per queried colour, in query order. */
     colours: ColourMatchReceipt[];
-}
-export interface GradientMatch extends MultiColourMatchBase {
+} & MultiColourMatchBase;
+export type GradientMatch = {
     /**
      * 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
@@ -119,7 +119,7 @@ export interface GradientMatch extends MultiColourMatchBase {
     coverage: number;
     /** One receipt per sampled point along the path, in path order. */
     samples: ColourMatchReceipt[];
-}
+} & MultiColourMatchBase;
 /**
  * The hue-family ADMISSION gate the page was scored under: a candidate swatch
  * may satisfy a query colour only if colorscope's `isHueCompatible` admits it
@@ -129,35 +129,35 @@ export interface GradientMatch extends MultiColourMatchBase {
  * request knob); the receipt exists so a threshold change is visible on the
  * wire.
  */
-export interface HueGateReceipt {
+export type HueGateReceipt = {
     /** Below this query chroma the colour is achromatic and any hue is admitted. */
     achromaticQueryChroma: number;
     /** A swatch must carry at least this share of the query colour's chroma. */
     minChromaRatio: number;
     /** Floor on the cosine agreement between the two hue vectors. */
     minHueCosine: number;
-}
+};
 /**
  * A PAGE, NOT A CORPUS. `count` is `matches.length` under `limit` (24 default,
  * 48 max) — this surface states no corpus total and has no cursor, so "N
  * materials match this palette" is not a claim you can make from it.
  */
-export interface SearchPaletteResponse {
+export type SearchPaletteResponse = {
     corpusScope?: CorpusScopeReceipt;
     /** The query as interpreted — check it before trusting a surprising order. */
     query: {
         /** Colours that actually ran after minor stated shares were omitted. */
-        colours: Array<{
+        colours: {
             hex: string;
             proportion?: number;
             weight?: number;
-        }>;
+        }[];
         /** Colours not searched because their stated share was below 5%. */
-        droppedColours: Array<{
+        droppedColours: {
             hex: string;
             proportion?: number;
             weight?: number;
-        }>;
+        }[];
         logic: PaletteLogic;
         /** `no_effective_colours` means no material query ran. */
         outcome: OpenEnum<"matches" | "no_effective_colours">;
@@ -167,9 +167,9 @@ export interface SearchPaletteResponse {
     /** `matches.length`, capped by `limit`. Never a corpus total. */
     count: number;
     matches: PaletteMatch[];
-}
+};
 /** A PAGE, NOT A CORPUS — see {@link SearchPaletteResponse}. */
-export interface SearchGradientResponse {
+export type SearchGradientResponse = {
     corpusScope?: CorpusScopeReceipt;
     query: {
         stops: string[];
@@ -179,4 +179,4 @@ export interface SearchGradientResponse {
     /** `matches.length`, capped by `limit`. Never a corpus total. */
     count: number;
     matches: GradientMatch[];
-}
+};

package/query-understanding-types.d.ts

@@ -1,7 +1,9 @@
+import type { MatchTarget } from "@instruments/colorscope/match";
+import type { ColorResolution } from "@instruments/colorscope/naming";
 import type { SearchFilter } from "./search-refinement-types.js";
 import type { OpenEnum } from "./types.js";
 export type QuerySenseKind = OpenEnum<"brand" | "product" | "paint_identity" | "category" | "material" | "colour" | "attribute" | "attribute_value" | "certification">;
-export interface QuerySense {
+export type QuerySense = {
     id: string;
     kind: QuerySenseKind;
     label: string;
@@ -26,14 +28,16 @@ export interface QuerySense {
         hex?: string;
     };
     reason?: string;
-}
-export interface CanonicalLexicalAuthorityReceipt {
+};
+export type CanonicalLexicalAuthorityReceipt = {
     authority: OpenEnum<"taxonomy" | "colorscope">;
     version: string;
     revision: string;
     digest?: string;
-}
-export interface CanonicalLexicalReading {
+};
+export type CanonicalLexicalReading = {
+    matchTarget?: MatchTarget;
+    colorResolution?: ColorResolution;
     authority: OpenEnum<"taxonomy" | "colorscope">;
     identity: string;
     outcome: OpenEnum<"equivalent" | "ambiguous" | "declined">;
@@ -59,8 +63,8 @@ export interface CanonicalLexicalReading {
         snapshot?: string;
         source: string;
     };
-}
-export interface CanonicalLexicalMatch {
+};
+export type CanonicalLexicalMatch = {
     original: string;
     canonical: string;
     rule: OpenEnum<"exact" | "plural-to-singular" | "typo-to-canonical">;
@@ -76,24 +80,24 @@ export interface CanonicalLexicalMatch {
         rule: OpenEnum<"exact" | "plural-to-singular" | "typo-to-canonical">;
         authorities: CanonicalLexicalAuthorityReceipt[];
     };
-}
-export interface CanonicalLexicalReceipt {
+};
+export type CanonicalLexicalReceipt = {
     original: string;
     outcome: OpenEnum<"resolved" | "ambiguous" | "declined" | "partial" | "unresolved">;
     matches: CanonicalLexicalMatch[];
     unresolved: CanonicalLexicalMatch[];
-}
-export interface QueryResidualReceipt {
+};
+export type QueryResidualReceipt = {
     kind: OpenEnum<"compound" | "descriptive" | "ambiguous" | "empty">;
     tokens: string[];
     resolvedTokens: string[];
     unresolvedTokens: string[];
     resolvedRatio: number;
     comparisonFrame: boolean;
-}
+};
 /** Deterministic criteria compiled from the query before retrieval. */
-export interface QueryCriteriaReceipt {
-    applied: Array<{
+export type QueryCriteriaReceipt = {
+    applied: {
         criterion: SearchFilter;
         lane: OpenEnum<"filter" | "preference">;
         lexicalSignal?: {
@@ -110,30 +114,30 @@ export interface QueryCriteriaReceipt {
         };
         source: OpenEnum<"compiled" | "taxonomy-adapter">;
         span: string;
-    }>;
-    conflicts: Array<{
+    }[];
+    conflicts: {
         attributeId: string;
         caller: SearchFilter;
         compiled: SearchFilter;
         reason: string;
-    }>;
-    exclusions: Array<{
+    }[];
+    exclusions: {
         criterion: SearchFilter;
         execution: OpenEnum<"blocked-positive-only-contract">;
         lane: OpenEnum<"hard" | "soft">;
         missingValuePolicy: OpenEnum<"retain-unknown">;
         span: string;
-    }>;
+    }[];
     preferences: SearchFilter[];
     residualText: string | null;
-    unresolved: Array<{
+    unresolved: {
         code: OpenEnum<"missing-searchable-attribute" | "missing-dimension-pair-contract" | "missing-explicit-comparator" | "negative-criterion-contract-blocked" | "registry-contract-drift" | "unsupported-numeric-format" | "unsupported-unit" | "unsupported-strict-comparator">;
         reason: string;
         span: string;
-    }>;
-}
+    }[];
+};
 /** How the query named or inferred a product type before retrieval. */
-export interface QueryProductTypeReceipt {
+export type QueryProductTypeReceipt = {
     kind: OpenEnum<"leaf" | "group" | "vector" | "ambiguous" | "none">;
     gate: OpenEnum<"hard" | "constrain" | "none">;
     pass: OpenEnum<"taxonomy" | "synonym" | "display-name" | "group" | "head-noun" | "vector" | "none">;
@@ -148,14 +152,14 @@ export interface QueryProductTypeReceipt {
     vectorPassRan: boolean;
     registryVersion: string;
     durationMs: number;
-    candidates: Array<{
+    candidates: {
         productTypeId: string;
         displayName: string;
         similarity: number;
-    }>;
-}
+    }[];
+};
 /** The selected retrieval arm; null when the path is browse or criteria-only. */
-export interface QueryArmReceipt {
+export type QueryArmReceipt = {
     arm: OpenEnum<"dense" | "lexical" | "colour"> | null;
     reason: string;
     reasonDetail?: OpenEnum<"derived-colour-veto" | "typo-recovery" | "literal-compound-without-type">;
@@ -165,8 +169,8 @@ export interface QueryArmReceipt {
     productTypeIds: string[];
     residual: QueryResidualReceipt;
     registryVersion: string;
-}
-export interface QueryAmbiguityReceipt {
+};
+export type QueryAmbiguityReceipt = {
     outcome: OpenEnum<"applied" | "abstained" | "refused" | "timeout">;
     modelId: string | null;
     providerRan: boolean;
@@ -178,24 +182,24 @@ export interface QueryAmbiguityReceipt {
     routing: OpenEnum<"compound" | "descriptive"> | null;
     productTypeIds: string[];
     changedArm: boolean;
-}
+};
 export interface QueryCategoryScopeReceipt {
     source: OpenEnum<"caller" | "anchor">;
-    mechanism: OpenEnum<"sql-predicate" | "allowlist" | "prune">;
+    mechanism: OpenEnum<"sql-predicate" | "provider-filter" | "allowlist" | "prune">;
     variantCount: number | null;
     ceiling: number;
     specScanBounded?: boolean;
     [key: string]: unknown;
 }
-export interface QuerySpecAllowlistReceipt {
+export type QuerySpecAllowlistReceipt = {
     limit: number;
     returned: number;
     retrieved?: number;
     truncated: boolean;
     emptyMeansScarcity: boolean;
     outcome?: OpenEnum<"corpus-scarcity" | "retrieval-miss" | "unknown">;
-}
-export interface QueryUnsatisfiableNarrowing {
+};
+export type QueryUnsatisfiableNarrowing = {
     narrowing: OpenEnum<"product-type">;
     gate: OpenEnum<"hard">;
     productTypeId: string;
@@ -203,8 +207,11 @@ export interface QueryUnsatisfiableNarrowing {
     productTypeIds: string[];
     pass: string;
     evidence: OpenEnum<"zero-accepted-variants">;
-    relaxedTo: OpenEnum<"none">;
-}
+    relaxedDisplayName?: string;
+    relaxedProductTypeId?: string;
+    relaxedProductTypeIds?: string[];
+    relaxedTo: OpenEnum<"head-noun" | "none">;
+};
 /** Inspectable interpretation of the raw query by ordinary MaterialGraph search. */
 export interface QueryUnderstanding {
     version: OpenEnum<"1">;

package/render-assets-types.d.ts

@@ -2,12 +2,12 @@ import type { VariantId } from "./identifiers.js";
 export type RenderAssetChannelRole = "base-color" | "normal" | "roughness" | "metalness" | "height" | "ambient-occlusion";
 export type RenderAssetSourceBasis = "catalog_feed" | "declared" | "derived";
 export type RenderAssetUnavailableReason = "no_accepted_appearance" | "pending" | "withheld" | "rejected" | "superseded" | "variant_inactive" | "delivery_unverified" | "integrity_error";
-export interface RenderAssetFreshness {
+export type RenderAssetFreshness = {
     revision: string;
     updatedAt: string | null;
     checkedAt: string | null;
-}
-export interface RenderAssetChannel {
+};
+export type RenderAssetChannel = {
     role: RenderAssetChannelRole;
     url: string;
     sha256: string;
@@ -17,8 +17,8 @@ export interface RenderAssetChannel {
     height: number;
     bitDepth: 8 | 16;
     colorSpace: "srgb" | "linear";
-}
-export interface MaterialRenderAssetsAvailable {
+};
+export type MaterialRenderAssetsAvailable = {
     schemaVersion: "pbr-render-assets/v1";
     variantId: VariantId;
     status: "available";
@@ -51,8 +51,8 @@ export interface MaterialRenderAssetsAvailable {
     channels: RenderAssetChannel[];
     supersedesSetIds: string[];
     freshness: RenderAssetFreshness;
-}
-export interface MaterialRenderAssetsUnavailable {
+};
+export type MaterialRenderAssetsUnavailable = {
     schemaVersion: "pbr-render-assets/v1";
     variantId: VariantId;
     status: "unavailable";
@@ -61,5 +61,5 @@ export interface MaterialRenderAssetsUnavailable {
     sourceBasis: RenderAssetSourceBasis | null;
     reasonCodes: RenderAssetUnavailableReason[];
     freshness: RenderAssetFreshness;
-}
+};
 export type MaterialRenderAssets = MaterialRenderAssetsAvailable | MaterialRenderAssetsUnavailable;

package/resolve-client.d.ts

@@ -76,7 +76,7 @@ import type { VocabularySearchOptions, VocabularySearchResponse } from "./types.
  * resolved independently, so one meaningless phrase never spoils the batch.
  * @param options `category` to scope the coverage answer, and an `AbortSignal`.
  */
-export declare function resolvePhrasesRequest(transport: HttpTransport, phrases: string[], scope?: ResolvePhrasesScope): Promise<ResolveResponse>;
+export declare const resolvePhrasesRequest: (transport: HttpTransport, phrases: string[], scope?: ResolvePhrasesScope) => Promise<ResolveResponse>;
 /**
  * THE QUESTION: "is 'FloorScore' an attribute or a value, and what is it called
  * here?" The catch-all for ONE phrase when you do not know which half of an
@@ -87,4 +87,4 @@ export declare function resolvePhrasesRequest(transport: HttpTransport, phrases:
  * phrase might name a brand, paint, colour or category rather than a spec, and
  * `mg.glossary()` to EXPLAIN a term rather than find it.
  */
-export declare function searchVocabularyRequest(transport: HttpTransport, query: string, options?: VocabularySearchOptions, signal?: AbortSignal): Promise<VocabularySearchResponse>;
+export declare const searchVocabularyRequest: (transport: HttpTransport, query: string, options?: VocabularySearchOptions, signal?: AbortSignal) => Promise<VocabularySearchResponse>;

package/resolve-client.js

@@ -49,11 +49,11 @@ import { resolveOperation } from "./operations.js";
  * resolved independently, so one meaningless phrase never spoils the batch.
  * @param options `category` to scope the coverage answer, and an `AbortSignal`.
  */
-export function resolvePhrasesRequest(transport, phrases, scope) {
+export const resolvePhrasesRequest = async (transport, phrases, scope) => {
     // A bare signal is what this took before `category` existed; keep accepting it
     // so no published call site had to change to gain coverage.
     const options = scope instanceof AbortSignal ? { signal: scope } : (scope ?? {});
-    return transport.requestJson(resolveOperation("resolve_phrases"), {
+    return await transport.requestJson(resolveOperation("resolve_phrases"), {
         body: {
             phrases,
             ...(options.category === undefined
@@ -62,7 +62,7 @@ export function resolvePhrasesRequest(transport, phrases, scope) {
         },
         signal: options.signal,
     });
-}
+};
 /**
  * THE QUESTION: "is 'FloorScore' an attribute or a value, and what is it called
  * here?" The catch-all for ONE phrase when you do not know which half of an
@@ -73,6 +73,4 @@ export function resolvePhrasesRequest(transport, phrases, scope) {
  * phrase might name a brand, paint, colour or category rather than a spec, and
  * `mg.glossary()` to EXPLAIN a term rather than find it.
  */
-export function searchVocabularyRequest(transport, query, options, signal) {
-    return transport.requestJson(resolveOperation("catalog_vocabulary_search"), { query: { q: query, limit: options?.limit, kind: options?.kind }, signal });
-}
+export const searchVocabularyRequest = async (transport, query, options, signal) => await transport.requestJson(resolveOperation("catalog_vocabulary_search"), { query: { kind: options?.kind, limit: options?.limit, q: query }, signal });

package/resolve-colour-types.d.ts

@@ -1,20 +1,22 @@
+import type { MatchTarget } from "@instruments/colorscope/match";
 /**
  * Colour-name resolution (GET `/api/v1/search/colours/resolve`): the resolved
  * colour, and whether the named paint is a variant in the catalogue.
  */
+import type { ColorResolution } from "@instruments/colorscope/naming";
 import type { CorpusScope } from "./corpus-scope-types.js";
 import type { VariantId } from "./identifiers.js";
 import type { OpenEnum } from "./types.js";
 /** Options for `resolveColour`. */
-export interface ResolveColourOptions {
+export type ResolveColourOptions = {
     /**
      * Sets `inScope` on each catalogue variant the lookup reports. It never
      * narrows the lookup. Absent leaves every `inScope` null.
      */
     corpusScope?: CorpusScope;
-}
+};
 /** One catalogue variant carrying the named paint. */
-export interface ResolveColourCatalogueVariant {
+export type ResolveColourCatalogueVariant = {
     variantId: VariantId;
     /** The brand exactly as stored, suspect or not. */
     brand: {
@@ -30,7 +32,7 @@ export interface ResolveColourCatalogueVariant {
      * made it. The variant is still the right one for the name.
      */
     parentageSuspect: boolean;
-}
+};
 /**
  * Whether the named paint is a variant in the catalogue. Exact, global, and
  * never narrowed by `corpusScope`, and run only for a `brand` library hit.
@@ -48,8 +50,22 @@ export type ResolveColourVariant = ({
     status: "not-looked-up";
     reason: OpenEnum<"reference-colour" | "descriptive-colour" | "no-paint-identity" | "generic-colour" | "several-paints">;
 };
-export interface ResolveColourResponse {
+export type ResolveColourResponse = {
+    /** Examples within the governed range. They do not replace its representative or bounds. */
+    rangeSamples?: string[];
+    /** Explicit manufacturer choices for an ambiguous paint name. Never selected automatically. */
+    alternatives?: {
+        query: string;
+        name: string;
+        hex: string;
+        libraryId: string;
+        libraryName: string;
+        code?: string;
+    }[];
+    /** Generic meaning; maker-specific paint identity is carried by match. */
+    genericResolution: ColorResolution;
     match: {
+        matchTarget: MatchTarget;
         hex: string;
         name: string;
         code?: string;
@@ -64,4 +80,4 @@ export interface ResolveColourResponse {
         /** The catalogue lookup for the name. Absent from servers that predate it. */
         variant?: ResolveColourVariant;
     } | null;
-}
+};

package/resolve-types.d.ts

@@ -51,7 +51,7 @@ export type ResolutionKind = "brand" | "paint_identity" | "colour" | "category"
  */
 export type ResolutionRung = "exact" | "alias" | "lexical";
 /** One thing a phrase turned out to mean. */
-export interface ResolvedMeaning {
+export type ResolvedMeaning = {
     kind: ResolutionKind;
     /**
      * The canonical token. OPAQUE — hand it back verbatim, never parse, tidy or
@@ -91,9 +91,9 @@ export interface ResolvedMeaning {
      * nothing rather than a figure measured a different way.
      */
     coverage?: MeaningCoverage;
-}
+};
 /** How much of the catalogue stands behind one reading. */
-export interface MeaningCoverage {
+export type MeaningCoverage = {
     /**
      * How many variants carry this reading, CORPUS-WIDE and across every brand —
      * never scoped to the `category` you sent, even when you sent one. `0` is a
@@ -121,9 +121,9 @@ export interface MeaningCoverage {
      * category holds SOME value for the attribute, not that it holds this one.
      */
     inCategory?: boolean;
-}
+};
 /** What one phrase resolved to — including, explicitly, nothing. */
-export interface PhraseResolution {
+export type PhraseResolution = {
     /** The phrase exactly as you sent it, so you can rejoin the batch by value. */
     phrase: string;
     /**
@@ -147,9 +147,9 @@ export interface PhraseResolution {
      * material world.
      */
     unresolved: boolean;
-}
+};
 /** Optional scoping for a resolve call. */
-export interface ResolvePhrasesOptions {
+export type ResolvePhrasesOptions = {
     /**
      * The product category you are grounding these words FOR — a slot, not a
      * filter. It adds {@link MeaningCoverage.inCategory} to every `attribute` and
@@ -157,7 +157,7 @@ export interface ResolvePhrasesOptions {
      */
     category?: string;
     signal?: AbortSignal;
-}
+};
 /**
  * What `mg.resolve()` accepts as its second argument. A bare `AbortSignal` is
  * still accepted, exactly as before {@link ResolvePhrasesOptions} existed, so no
@@ -165,7 +165,7 @@ export interface ResolvePhrasesOptions {
  */
 export type ResolvePhrasesScope = AbortSignal | ResolvePhrasesOptions;
 /** The resolve response: one entry per phrase, in the order you sent them. */
-export interface ResolveResponse {
+export type ResolveResponse = {
     /** One per phrase, in request order — never reordered, never deduplicated. */
     resolutions: PhraseResolution[];
-}
+};