@instruments/materialgraph 0.9.0 → 0.10.0

package/brands-client.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The BRAND lens: the catalogue collection, one brand's profile, and one
+ * brand's whole colour range, as thin wrappers over the shared
+ * {@link HttpTransport}. `MaterialGraphClient.brands` / `.brand` /
+ * `.brandColourDeck` delegate here; the contract lives in this file.
+ *
+ * A brand is a COMPANY, not a catalogue. Every count these reads return is
+ * coverage — what MaterialGraph has ingested — and never a claim about how
+ * many products the maker sells.
+ */
+import type { BrandCatalogListPage, BrandsOptions } from "./brand-types.js";
+import type { BrandFanDeck } from "./fan-deck-types.js";
+import { HttpTransport } from "./http-transport.js";
+import type { BrandOptions, BrandProfileResponse } from "./types.js";
+/**
+ * THE QUESTION: "whose catalogs are in here, and how big is each?" The SDK's
+ * one OFFSET-paginated surface: read `meta.total` for the collection size and
+ * `meta.hasMore` to keep walking. Instead use {@link brandProfile} for one
+ * brand's profile and trade signals.
+ */
+export declare function listBrands(transport: HttpTransport, options?: BrandsOptions, signal?: AbortSignal): Promise<BrandCatalogListPage>;
+/**
+ * THE QUESTION: "who is this brand, and what do they claim?" — profile plus the
+ * trade/spec signals ON RECORD. `trade` is keyed by attribute id and an ABSENT
+ * key means no value is held — never infer `false`. Instead use `search()` to
+ * find their materials; this describes the company, not the catalog.
+ */
+export declare function brandProfile(transport: HttpTransport, brandSlug: string, options?: BrandOptions, signal?: AbortSignal): Promise<BrandProfileResponse>;
+/**
+ * THE QUESTION: "show me this maker's whole range, the way a fan deck reads."
+ * Colours grouped by family — creams together, then greys, then browns — and
+ * ordered light to dark within each. No stored scalar produces that order: a
+ * lightness sort interleaves the whites and the creams, and a reader loses the
+ * sense that they are looking at two different families.
+ *
+ * Deliberately unpaginated, so there is no cursor to walk and no all-brands
+ * form: family order is only correct over a COMPLETE range, because the greys
+ * cannot be placed against the browns while holding one page of each. A range
+ * past the server ceiling reports `truncatedAt` rather than being quietly cut,
+ * and an absent `truncatedAt` means the deck is whole.
+ *
+ * Every swatch carries the maker's PUBLISHED hex — this read never returns a
+ * colour derived from imagery. For "what is near this colour, across makers"
+ * use `byColour()` instead.
+ *
+ * @param brandSlug The brand's slug, as `listBrands()` reports it.
+ */
+export declare function brandColourDeck(transport: HttpTransport, brandSlug: string, signal?: AbortSignal): Promise<BrandFanDeck>;

package/brands-client.js

@@ -0,0 +1,45 @@
+import { HttpTransport } from "./http-transport.js";
+import { resolveOperation } from "./operations.js";
+/**
+ * THE QUESTION: "whose catalogs are in here, and how big is each?" The SDK's
+ * one OFFSET-paginated surface: read `meta.total` for the collection size and
+ * `meta.hasMore` to keep walking. Instead use {@link brandProfile} for one
+ * brand's profile and trade signals.
+ */
+export function listBrands(transport, options = {}, signal) {
+    return transport.requestJson(resolveOperation("list_brands"), {
+        query: { q: options.q, limit: options.limit, offset: options.offset },
+        signal,
+    });
+}
+/**
+ * THE QUESTION: "who is this brand, and what do they claim?" — profile plus the
+ * trade/spec signals ON RECORD. `trade` is keyed by attribute id and an ABSENT
+ * key means no value is held — never infer `false`. Instead use `search()` to
+ * find their materials; this describes the company, not the catalog.
+ */
+export function brandProfile(transport, brandSlug, options, signal) {
+    return transport.requestJson(resolveOperation("get_brand_profile"), { query: { q: options?.q }, pathParams: { brandSlug }, signal });
+}
+/**
+ * THE QUESTION: "show me this maker's whole range, the way a fan deck reads."
+ * Colours grouped by family — creams together, then greys, then browns — and
+ * ordered light to dark within each. No stored scalar produces that order: a
+ * lightness sort interleaves the whites and the creams, and a reader loses the
+ * sense that they are looking at two different families.
+ *
+ * Deliberately unpaginated, so there is no cursor to walk and no all-brands
+ * form: family order is only correct over a COMPLETE range, because the greys
+ * cannot be placed against the browns while holding one page of each. A range
+ * past the server ceiling reports `truncatedAt` rather than being quietly cut,
+ * and an absent `truncatedAt` means the deck is whole.
+ *
+ * Every swatch carries the maker's PUBLISHED hex — this read never returns a
+ * colour derived from imagery. For "what is near this colour, across makers"
+ * use `byColour()` instead.
+ *
+ * @param brandSlug The brand's slug, as `listBrands()` reports it.
+ */
+export function brandColourDeck(transport, brandSlug, signal) {
+    return transport.requestJson(resolveOperation("brand_colour_deck"), { pathParams: { brandSlug }, signal });
+}

package/by-colour-types.d.ts

@@ -7,7 +7,7 @@
  * enums are widened so a new server value still type-checks.
  */
 import type { VariantId } from "./identifiers.js";
-import type { OklabTriple, PaletteSwatch } from "./types.js";
+import type { OklabTriple, OpenEnum, PaletteSwatch } from "./types.js";
 /** Coarse group + fine type of a colour match's primary product type. */
 export interface MatchCategory {
     group: string | null;
@@ -16,10 +16,10 @@ export interface MatchCategory {
 /**
  * One colour-palette match.
  *
- * `hex`, `distance` and `closeness` are OKLab geometry over colour EXTRACTED
- * FROM PRODUCT IMAGERY, not declared by the manufacturer. Report it as visual
- * likeness ("reads close to this colour"), never as a stated colour
- * specification.
+ * `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 interface ByColourMatch {
     /** Opaque — round-trip verbatim. */
@@ -34,6 +34,31 @@ export interface ByColourMatch {
     closeness: number;
     category: MatchCategory | null;
     oklab: OklabTriple | null;
+    /**
+     * 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
@@ -86,6 +111,11 @@ export interface ByColourResponse {
     query: {
         colours: string[];
         categories?: string[];
+        /**
+         * Echoed brand filter as resolved SLUGS — what the 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;
         oklab?: OklabTriple;
@@ -118,6 +148,20 @@ export interface ByColourParams {
     b?: number;
     /** HARD category filter — display names or taxonomy ids (repeatable). */
     category?: string | string[];
+    /**
+     * HARD brand filter (repeatable) — a brand SLUG (`sherwin-williams`) or its
+     * display name (`Sherwin-Williams`), 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 400 naming it, never 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`,

package/client.d.ts

@@ -1,25 +1,26 @@
-import { type RateLimit } from "./errors.js";
 import type { MaterialGraphClientOptions } from "./client-config.js";
+import { type RateLimit } from "./errors.js";
 export * from "./client-config.js";
 import { type BrowseNamespace } from "./client-browse.js";
 export type { BrowseNamespace } from "./client-browse.js";
-import type { CapabilityManifestResponse, CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, ListRunsOptions, PublicRunListResponse, PublicRunResponse, ResumeRunOptions, RunEvent, SourceMaterialBatchDetail, SourceMaterialBatchReceipt, StreamRunEventsOptions, UploadSourceMaterialInput } from "./run-types.js";
-import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
-import type { MatchStreamEvent } from "./match-stream-types.js";
-import type { AppendProjectEventRequest, CreateProjectRequest, ProjectEventReceipt, ProjectListResponse, ProjectState } from "./project-types.js";
-import type { VarySchemesRequest, VarySchemesResponse } from "./composition-types.js";
-import { CodesClient } from "./codes-client.js";
-import { ColoursClient } from "./colours-client.js";
-import type { CodeAdvisoryInput, CodeAdvisoryResponse } from "./codes-types.js";
 import type { AssociatedOptions } from "./association-types.js";
 import type { BrandCatalogListPage, BrandsOptions } from "./brand-types.js";
+import type { ByColourParams, ByColourResponse } from "./by-colour-types.js";
+import { CodesClient } from "./codes-client.js";
+import type { CodeAdvisoryInput, CodeAdvisoryResponse } from "./codes-types.js";
+import { ColoursClient } from "./colours-client.js";
+import type { VarySchemesRequest, VarySchemesResponse } from "./composition-types.js";
+import type { BatchId, ProjectId, RunId, VariantId } from "./identifiers.js";
+import type { MatchStreamEvent } from "./match-stream-types.js";
+import type { MatchInput, MatchResponse } from "./match-types.js";
 import type { MaterialAssetProjection } from "./material-asset-types.js";
 import type { MaterialBlockProjection } from "./material-block-types.js";
+import type { AppendProjectEventRequest, CreateProjectRequest, ProjectEventReceipt, ProjectListResponse, ProjectState } from "./project-types.js";
+import { resolvePhrasesRequest as resolvePhrases } from "./resolve-client.js";
+import type { CapabilityManifestResponse, CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, ListRunsOptions, PublicRunListResponse, PublicRunResponse, ResumeRunOptions, RunEvent, SourceMaterialBatchDetail, SourceMaterialBatchReceipt, StreamRunEventsOptions, UploadSourceMaterialInput } from "./run-types.js";
+import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
 import type { SchemaResource, SchemaResourceResponse } from "./schema-resource-types.js";
-import type { BatchId, ProjectId, RunId, VariantId } from "./identifiers.js";
-import type { ByColourParams, ByColourResponse } from "./by-colour-types.js";
 import type { ApplicableSpecsResponse, BrandOptions, BrandProfileResponse, BySpecOptions, BySpecResponse, ColourFacetsResponse, CoordinateInput, CoordinateResponse, DemandBatchInput, DemandBatchResponse, DemandParams, DemandResponse, ExtractPaletteInput, ExtractPaletteResponse, GlossaryTermResponse, MaterialResponse, MaterialsBatchDetailResponse, MaterialsBatchGetOptions, MaterialsBatchOptions, MaterialsBatchTileResponse, PairingsOptions, PairingsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SiblingsResponse, SpecFacetsDistributionResponse, SpecFacetsListResponse, SuggestColourResponse, SuggestOptions, SuggestResponse, TaxonomyResponse, VocabularySearchOptions, WhoamiResponse } from "./types.js";
-import type { MatchInput, MatchResponse } from "./match-types.js";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
  *
@@ -172,8 +173,7 @@ export declare class MaterialGraphClient {
      * {@link MaterialGraphClient.browse} to walk by lightness/vividness, and
      * {@link MaterialGraphClient.search} when colour is one signal among many.
      * Report matches as visual likeness, never a stated colour specification.
-     * `family` gates the answer to ONE colorscope colour family when nearness
-     * alone crosses a hue boundary; a gated page can be shorter than `limit`.
+     * `family` gates to ONE colorscope family (a gated page can be short); `brand` gates to named brands — one brand's nearest colour to another's.
      */
     byColour(params: ByColourParams, signal?: AbortSignal): Promise<ByColourResponse>;
     /**
@@ -326,33 +326,29 @@ export declare class MaterialGraphClient {
     resolveAttributeValue(attributeId: string, query: string, options?: ResolveAttributeValueOptions, signal?: AbortSignal): Promise<ResolveAttributeValueResponse>;
     /** "Is this phrase an attribute or a value?" — see {@link searchVocabularyRequest}. */
     searchVocabulary(query: string, options?: VocabularySearchOptions, signal?: AbortSignal): Promise<import("./catalog-discovery-types.js").VocabularySearchResponse>;
-    /** "I have words — what do they mean in YOUR vocabulary?" — see {@link resolvePhrasesRequest}. */
-    resolve(phrases: string[], signal?: AbortSignal): Promise<import("./resolve-types.js").ResolveResponse>;
+    /** "I have words — what do they mean, and what stands behind them?" — see {@link resolvePhrases}. */
+    resolve(phrases: string[], scope?: Parameters<typeof resolvePhrases>[2]): Promise<import("./resolve-types.js").ResolveResponse>;
     /**
      * THE QUESTION: "which materials, from ANYONE, are ASTM E84 Class A AND
-     * GREENGUARD-certified?" — hard specifications, no ranking, every brand at once
-     * whatever each called the value in source.
+     * GREENGUARD-certified?" — hard specifications, no ranking, every brand at
+     * once whatever each called the value in source. The value-anchored,
+     * spec-only primitive (GET `/api/v1/search/specifications`).
      *
      * Instead use `search({ filters })` when the spec merely GATES a ranked
      * question, `codes.advisory()` when the real question is what a space demands,
-     * and {@link MaterialGraphClient.specificationFacets} first if you do not know
-     * the canonical tokens. Guessing one no longer returns a silently empty
-     * answer: an unresolvable criterion means the query NEVER RAN, and the
-     * response says so — read {@link BySpecResponse.unresolvedCriteria} before
-     * treating an empty `matches` as "nothing qualifies".
-     *
-     * A PAGE, NOT A CORPUS, unusually so: `totalMatches` is the size of the
-     * returned sample under `limit`, not a corpus count. See {@link BySpecResponse}.
-     *
-     * Find materials by canonical specification across every brand — the
-     * value-anchored, spec-only primitive (GET `/api/v1/search/specifications`).
-     * Each `spec` is an `attribute:value` criterion; a variant must satisfy ALL of
-     * them, and each match carries per-criterion trust (`confidence` +
-     * `sourceBasis`). Answers "which materials, from anyone, are ASTM E84 Class A
-     * AND GREENGUARD-certified?" Build the strings with `specCriterion` /
-     * `certificationProgrammeCriterion` (e.g.
-     * `certificationProgrammeCriterion("GREENGUARD Gold")`); discover the queryable
-     * vocabulary with {@link specificationFacets} and {@link attributeValues}.
+     * and {@link specificationFacets} first if you do not know the canonical
+     * tokens. Guessing one no longer returns a silently empty answer: an
+     * unresolvable criterion means the query NEVER RAN and the response says so —
+     * read {@link BySpecResponse.unresolvedCriteria} before treating an empty
+     * `matches` as "nothing qualifies". A PAGE, NOT A CORPUS, unusually so:
+     * `totalMatches` is the returned sample's size under `limit`, not a corpus
+     * count. Each `spec` is an `attribute:value` criterion built with
+     * `specCriterion` / `certificationProgrammeCriterion`; a variant must satisfy
+     * ALL of them, and each match carries per-criterion trust (`confidence` +
+     * `sourceBasis`). NUMBER-valued specs take BOUNDS, not values — pass
+     * `options.ranges` built with `specRangeCriterion("light_reflectance_value",
+     * { min: 60 })`; bounds are inclusive, at least one is required, and a
+     * non-numeric stored value is excluded rather than read as zero.
      */
     bySpec(spec: string | string[], options?: BySpecOptions, signal?: AbortSignal): Promise<BySpecResponse>;
     /**
@@ -479,21 +475,12 @@ export declare class MaterialGraphClient {
      * {@link MaterialGraphClient.attributeValues} for the values it takes.
      */
     glossary(term: string, signal?: AbortSignal): Promise<GlossaryTermResponse>;
-    /**
-     * THE QUESTION: "whose catalogs are in here, and how big is each?" The SDK's
-     * one OFFSET-paginated surface: read `meta.total` for the collection size and
-     * `meta.hasMore` to keep walking. Instead use {@link MaterialGraphClient.brand}
-     * for one brand's profile and trade signals.
-     */
+    /** "Whose catalogs are in here, and how big is each?" — {@link listBrands}. */
     brands(options?: BrandsOptions, signal?: AbortSignal): Promise<BrandCatalogListPage>;
-    /**
-     * THE QUESTION: "who is this brand, and what do they claim?" — profile plus the
-     * trade/spec signals ON RECORD. `trade` is keyed by attribute id and an ABSENT
-     * key means no value is held — never infer `false`. Instead use
-     * {@link MaterialGraphClient.search} to find their materials; this describes the
-     * company, not the catalog.
-     */
+    /** "Who is this brand, and what do they claim?" — {@link brandProfile}. */
     brand(brandSlug: string, options?: BrandOptions, signal?: AbortSignal): Promise<BrandProfileResponse>;
+    /** "This maker's whole range, the way a fan deck reads" — {@link brandColourDeck}. */
+    brandColourDeck(brandSlug: string, signal?: AbortSignal): Promise<import("./fan-deck-types.js").BrandFanDeck>;
     /**
      * Upload one atomic source-material batch (POST `/api/v1/source-material`,
      * multipart). Pass a heterogeneous pile via `{ files }` (any mix of PDF,

package/client.js

@@ -1,20 +1,21 @@
+import { DEFAULT_BASE_URL, MAX_BATCH_IDS } from "./client-config.js";
 import { MaterialGraphError } from "./errors.js";
 import { HttpTransport } from "./http-transport.js";
 // Aliased to `operation` — the local name every call site here already used.
-import { resolveOperation as operation } from "./operations.js";
+import { resolveOperation as operation, } from "./operations.js";
 import { cancelRun, capabilities as capabilitiesRun, createRun, drainRunEvents, getRun, getRunSchedule, getSourceMaterialBatch as getSourceMaterialBatchCall, listRuns, resumeRun, streamRunEvents, uploadSourceMaterial, } from "./runs.js";
-import { DEFAULT_BASE_URL, MAX_BATCH_IDS } from "./client-config.js";
 // Re-exported whole so `index.ts` and every existing importer keep their path.
 export * from "./client-config.js";
-import { browseQuery, createBrowseNamespace } from "./client-browse.js";
-import { suggestQuery } from "./suggest-types.js";
-import { matchStream as matchStreamCall } from "./match-stream.js";
-import { appendProjectEvent as appendProjectEventCall, createProject as createProjectCall, getProject as getProjectCall, listProjects as listProjectsCall, } from "./projects.js";
+import { browseQuery, createBrowseNamespace, } from "./client-browse.js";
+import { declaredFinishes, declaredProducts } from "./associations-client.js";
+import { brandColourDeck, brandProfile, listBrands } from "./brands-client.js";
 import { CodesClient } from "./codes-client.js";
 import { ColoursClient } from "./colours-client.js";
-import { resolvePhrasesRequest, searchVocabularyRequest } from "./resolve-client.js";
-import { declaredFinishes, declaredProducts } from "./associations-client.js";
+import { matchStream as matchStreamCall } from "./match-stream.js";
+import { appendProjectEvent as appendProjectEventCall, createProject as createProjectCall, getProject as getProjectCall, listProjects as listProjectsCall, } from "./projects.js";
+import { resolvePhrasesRequest as resolvePhrases, searchVocabularyRequest, } from "./resolve-client.js";
 import { SCHEMA_RESOURCE_OPERATION_IDS } from "./schema-resource-types.js";
+import { suggestQuery } from "./suggest-types.js";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
  *
@@ -112,10 +113,17 @@ export class MaterialGraphClient {
         return this.#transport.lastRateLimit;
     }
     #get(operationId, query, signal, pathParams) {
-        return this.#transport.requestJson(operation(operationId), { query, signal, pathParams });
+        return this.#transport.requestJson(operation(operationId), {
+            query,
+            signal,
+            pathParams,
+        });
     }
     #post(operationId, body, signal) {
-        return this.#transport.requestJson(operation(operationId), { body, signal });
+        return this.#transport.requestJson(operation(operationId), {
+            body,
+            signal,
+        });
     }
     /**
      * THE QUESTION: "find me materials like this" — a RANKED answer over words, a
@@ -202,8 +210,7 @@ export class MaterialGraphClient {
      * {@link MaterialGraphClient.browse} to walk by lightness/vividness, and
      * {@link MaterialGraphClient.search} when colour is one signal among many.
      * Report matches as visual likeness, never a stated colour specification.
-     * `family` gates the answer to ONE colorscope colour family when nearness
-     * alone crosses a hue boundary; a gated page can be shorter than `limit`.
+     * `family` gates to ONE colorscope family (a gated page can be short); `brand` gates to named brands — one brand's nearest colour to another's.
      */
     byColour(params, signal) {
         return this.#get("search_by_colour", {
@@ -213,6 +220,7 @@ export class MaterialGraphClient {
             a: params.a,
             b: params.b,
             category: params.category,
+            brand: params.brand,
             family: params.family,
             limit: params.limit,
         }, signal);
@@ -307,7 +315,11 @@ export class MaterialGraphClient {
         if (ids.length > MAX_BATCH_IDS) {
             throw MaterialGraphError.unexpected(`MaterialGraphClient.materials(): at most ${MAX_BATCH_IDS} ids per call, received ${ids.length}. Split into multiple batches.`);
         }
-        return this.#post("get_materials_batch_post", { ids, view: options?.view ?? "tile", idKind: options?.idKind ?? "variantId" }, signal);
+        return this.#post("get_materials_batch_post", {
+            ids,
+            view: options?.view ?? "tile",
+            idKind: options?.idKind ?? "variantId",
+        }, signal);
     }
     materialsCached(ids, options, signal) {
         if (ids.length > MAX_BATCH_IDS) {
@@ -388,38 +400,38 @@ export class MaterialGraphClient {
     searchVocabulary(query, options, signal) {
         return searchVocabularyRequest(this.#transport, query, options, signal);
     }
-    /** "I have words — what do they mean in YOUR vocabulary?" — see {@link resolvePhrasesRequest}. */
-    resolve(phrases, signal) {
-        return resolvePhrasesRequest(this.#transport, phrases, signal);
+    /** "I have words — what do they mean, and what stands behind them?" — see {@link resolvePhrases}. */
+    resolve(phrases, scope) {
+        return resolvePhrases(this.#transport, phrases, scope);
     }
     /**
      * THE QUESTION: "which materials, from ANYONE, are ASTM E84 Class A AND
-     * GREENGUARD-certified?" — hard specifications, no ranking, every brand at once
-     * whatever each called the value in source.
+     * GREENGUARD-certified?" — hard specifications, no ranking, every brand at
+     * once whatever each called the value in source. The value-anchored,
+     * spec-only primitive (GET `/api/v1/search/specifications`).
      *
      * Instead use `search({ filters })` when the spec merely GATES a ranked
      * question, `codes.advisory()` when the real question is what a space demands,
-     * and {@link MaterialGraphClient.specificationFacets} first if you do not know
-     * the canonical tokens. Guessing one no longer returns a silently empty
-     * answer: an unresolvable criterion means the query NEVER RAN, and the
-     * response says so — read {@link BySpecResponse.unresolvedCriteria} before
-     * treating an empty `matches` as "nothing qualifies".
-     *
-     * A PAGE, NOT A CORPUS, unusually so: `totalMatches` is the size of the
-     * returned sample under `limit`, not a corpus count. See {@link BySpecResponse}.
-     *
-     * Find materials by canonical specification across every brand — the
-     * value-anchored, spec-only primitive (GET `/api/v1/search/specifications`).
-     * Each `spec` is an `attribute:value` criterion; a variant must satisfy ALL of
-     * them, and each match carries per-criterion trust (`confidence` +
-     * `sourceBasis`). Answers "which materials, from anyone, are ASTM E84 Class A
-     * AND GREENGUARD-certified?" Build the strings with `specCriterion` /
-     * `certificationProgrammeCriterion` (e.g.
-     * `certificationProgrammeCriterion("GREENGUARD Gold")`); discover the queryable
-     * vocabulary with {@link specificationFacets} and {@link attributeValues}.
+     * and {@link specificationFacets} first if you do not know the canonical
+     * tokens. Guessing one no longer returns a silently empty answer: an
+     * unresolvable criterion means the query NEVER RAN and the response says so —
+     * read {@link BySpecResponse.unresolvedCriteria} before treating an empty
+     * `matches` as "nothing qualifies". A PAGE, NOT A CORPUS, unusually so:
+     * `totalMatches` is the returned sample's size under `limit`, not a corpus
+     * count. Each `spec` is an `attribute:value` criterion built with
+     * `specCriterion` / `certificationProgrammeCriterion`; a variant must satisfy
+     * ALL of them, and each match carries per-criterion trust (`confidence` +
+     * `sourceBasis`). NUMBER-valued specs take BOUNDS, not values — pass
+     * `options.ranges` built with `specRangeCriterion("light_reflectance_value",
+     * { min: 60 })`; bounds are inclusive, at least one is required, and a
+     * non-numeric stored value is excluded rather than read as zero.
      */
     bySpec(spec, options, signal) {
-        return this.#get("catalog_by_spec", { spec: Array.isArray(spec) ? spec : [spec], limit: options?.limit }, signal);
+        return this.#get("catalog_by_spec", {
+            spec: Array.isArray(spec) ? spec : [spec],
+            ...(options?.ranges?.length ? { specRange: options.ranges } : {}),
+            limit: options?.limit,
+        }, signal);
     }
     // ── Taxonomy + meta ──────────────────────────────────────────────────────────
     /**
@@ -575,26 +587,17 @@ export class MaterialGraphClient {
         return this.#get("explain_material_term", undefined, signal, { term });
     }
     // ── Brands ───────────────────────────────────────────────────────────────────
-    /**
-     * THE QUESTION: "whose catalogs are in here, and how big is each?" The SDK's
-     * one OFFSET-paginated surface: read `meta.total` for the collection size and
-     * `meta.hasMore` to keep walking. Instead use {@link MaterialGraphClient.brand}
-     * for one brand's profile and trade signals.
-     */
+    /** "Whose catalogs are in here, and how big is each?" — {@link listBrands}. */
     brands(options = {}, signal) {
-        return this.#get("list_brands", { q: options.q, limit: options.limit, offset: options.offset }, signal);
+        return listBrands(this.#transport, options, signal);
     }
-    /**
-     * THE QUESTION: "who is this brand, and what do they claim?" — profile plus the
-     * trade/spec signals ON RECORD. `trade` is keyed by attribute id and an ABSENT
-     * key means no value is held — never infer `false`. Instead use
-     * {@link MaterialGraphClient.search} to find their materials; this describes the
-     * company, not the catalog.
-     */
+    /** "Who is this brand, and what do they claim?" — {@link brandProfile}. */
     brand(brandSlug, options, signal) {
-        return this.#get("get_brand_profile", { q: options?.q }, signal, {
-            brandSlug,
-        });
+        return brandProfile(this.#transport, brandSlug, options, signal);
+    }
+    /** "This maker's whole range, the way a fan deck reads" — {@link brandColourDeck}. */
+    brandColourDeck(brandSlug, signal) {
+        return brandColourDeck(this.#transport, brandSlug, signal);
     }
     // ── Runs (the hosted agentic surface) ────────────────────────────────────────
     /**

package/errors.js

@@ -53,7 +53,9 @@ function sanitizeRecord(value, secrets, depth) {
         .slice(0, MAX_EXTENSION_ITEMS)
         .flatMap(([key, item]) => {
         const sanitized = sanitizeValue(item, secrets, depth + 1);
-        return sanitized === undefined ? [] : [[safeString(key, secrets), sanitized]];
+        return sanitized === undefined
+            ? []
+            : [[safeString(key, secrets), sanitized]];
     });
     return Object.fromEntries(entries);
 }
@@ -66,10 +68,13 @@ function sanitizeIssues(value, secrets) {
         .map((issue) => sanitizeRecord(issue, secrets, 0));
 }
 function sanitizeSuggestions(value, secrets) {
-    if (!Array.isArray(value) || value.some((suggestion) => typeof suggestion !== "string")) {
+    if (!Array.isArray(value) ||
+        value.some((suggestion) => typeof suggestion !== "string")) {
         return undefined;
     }
-    return value.slice(0, MAX_EXTENSION_ITEMS).map((suggestion) => safeString(suggestion, secrets));
+    return value
+        .slice(0, MAX_EXTENSION_ITEMS)
+        .map((suggestion) => safeString(suggestion, secrets));
 }
 function normalizeProblem(body, secrets) {
     if (!isRecord(body) ||
@@ -89,11 +94,15 @@ function normalizeProblem(body, secrets) {
         title: safeString(body.title, secrets),
         status: body.status,
         detail: safeString(body.detail, secrets),
-        ...(body.instance === undefined ? {} : { instance: safeString(body.instance, secrets) }),
+        ...(body.instance === undefined
+            ? {}
+            : { instance: safeString(body.instance, secrets) }),
         is_retriable: body.is_retriable,
         trace_id: safeString(body.trace_id, secrets),
         ...(suggestions === undefined ? {} : { suggestions }),
-        ...(typeof body.doc_uri === "string" ? { doc_uri: safeString(body.doc_uri, secrets) } : {}),
+        ...(typeof body.doc_uri === "string"
+            ? { doc_uri: safeString(body.doc_uri, secrets) }
+            : {}),
         ...(issues === undefined ? {} : { issues }),
     };
 }
@@ -107,7 +116,9 @@ function normalizeSimple(body, secrets) {
     };
 }
 function unexpectedMessage(status, responseText, secrets) {
-    const sanitized = redact(responseText, secrets).trim().slice(0, MAX_UNEXPECTED_TEXT);
+    const sanitized = redact(responseText, secrets)
+        .trim()
+        .slice(0, MAX_UNEXPECTED_TEXT);
     return sanitized.length > 0
         ? `MaterialGraph request failed with HTTP ${status}: ${sanitized}`
         : `MaterialGraph request failed with HTTP ${status}`;
@@ -143,7 +154,10 @@ export class MaterialGraphError extends Error {
         return this.retriable;
     }
     static unexpected(message) {
-        return new MaterialGraphError(message, { kind: "unexpected", retriable: false });
+        return new MaterialGraphError(message, {
+            kind: "unexpected",
+            retriable: false,
+        });
     }
     static fromTransport(input) {
         if (input.callerSignal?.aborted === true) {
@@ -174,7 +188,9 @@ export class MaterialGraphError extends Error {
         const retriable = RETRIABLE_STATUS.has(input.status);
         const metadata = requestMetadata(input);
         if (input.status === 429) {
-            return new MaterialGraphError(problem?.detail ?? simple?.error ?? "MaterialGraph rate limit exceeded (429)", {
+            return new MaterialGraphError(problem?.detail ??
+                simple?.error ??
+                "MaterialGraph rate limit exceeded (429)", {
                 ...metadata,
                 status: input.status,
                 rateLimit: input.rateLimit,

package/fan-deck-types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Wire types for a maker's whole range — GET `/api/v1/brands/{brandSlug}/colours`.
+ *
+ * The one read in the SDK that is deliberately UNPAGINATED. Family order is only
+ * correct over a complete range: the greys cannot be placed against the browns
+ * while holding one page of each. So the response carries the brand, and
+ * `truncatedAt` appears only if a range ever exceeds the server's ceiling.
+ */
+export interface FanDeckSwatch {
+    /** Opaque token. Never parse or construct one. */
+    variantId: string;
+    brand: string;
+    /** The maker's own colour name. Null when the catalogue publishes none. */
+    name: string | null;
+    /** The maker's PUBLISHED hex. This read never returns a derived colour. */
+    hex: string;
+    /** colorscope's family id, lower case (`cream`, `gray`, `blue`). */
+    family: string;
+    /** OKLab L, 0–1. The sort key within a family: light to dark. */
+    lightness: number;
+    imageUrl: string | null;
+}
+export interface FanDeckFamily {
+    family: string;
+    /** Count over the WHOLE range, computed before any truncation. */
+    count: number;
+}
+export interface BrandFanDeck {
+    /** The brands the deck covers, as resolved from the slug. */
+    brands: string[];
+    /** Grouped by `families` order, light to dark within each family. */
+    swatches: FanDeckSwatch[];
+    families: FanDeckFamily[];
+    /**
+     * Present ONLY when the range exceeded the server ceiling. Absent means the
+     * deck is complete — absent is not zero.
+     */
+    truncatedAt?: number;
+}

package/fan-deck-types.js

@@ -0,0 +1,9 @@
+/**
+ * Wire types for a maker's whole range — GET `/api/v1/brands/{brandSlug}/colours`.
+ *
+ * The one read in the SDK that is deliberately UNPAGINATED. Family order is only
+ * correct over a complete range: the greys cannot be placed against the browns
+ * while holding one page of each. So the response carries the brand, and
+ * `truncatedAt` appears only if a range ever exceeds the server's ceiling.
+ */
+export {};