@instruments/materialgraph 0.7.1 → 0.9.0

package/resolve-types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The vocabulary lens (MG-913) — the hand-mirrored wire types for
+ * `POST /api/v1/resolve`.
+ *
+ * Split out of `types.ts` for the repository's source-file size budget, the same
+ * reason `suggest-types.ts` sits beside it; both are re-exported from `types.ts`,
+ * so importers see no difference.
+ *
+ * THE LENS: it turns WORDS into vocabulary, never into materials.
+ * `mg.search()` answers "I want materials" and `mg.answer` questions want prose;
+ * this answers "what do these words mean in your vocabulary?" — the question you
+ * ask BEFORE you spend a token on a filter, a facet or a brand slug. It is the
+ * reason you should not keep a hand-written table mapping your users' words onto
+ * this API's tokens: that table is a copy of a registry you do not own, and it
+ * drifts silently the moment the registry moves.
+ */
+/**
+ * Which controlled vocabulary a reading came from — and therefore what `id`
+ * means and where you can spend it.
+ *
+ * - `brand` — a brand slug, for `mg.brand()` or a brand filter.
+ * - `paint_identity` — one exact vendor paint (a library colour), by its vendor
+ *   code where the library has one.
+ * - `colour` — a canonical colour-family term, namespaced (`colour_family.green`).
+ * - `category` — a product-category taxonomy node key.
+ * - `attribute` — a registry attribute id: the LEFT half of an `attribute:value`
+ *   pair, for `mg.bySpec()` or `search({ filters })`.
+ * - `attribute_value` — a value-dictionary term, namespaced (`ms_sheen.matte`):
+ *   the RIGHT half.
+ */
+export type ResolutionKind = "brand" | "paint_identity" | "colour" | "category" | "attribute" | "attribute_value";
+/**
+ * How the phrase matched, strongest first. `exact` — it IS the canonical token;
+ * `alias` — it IS a recorded alternative name for it; `lexical` — it resembles
+ * one closely enough to clear the resolver's own confidence floor.
+ *
+ * There is deliberately no `semantic` rung on this lens. Every tier that would
+ * cost an embedding round-trip is switched off, which is what keeps resolution
+ * millisecond-class; a phrase only a semantic match could have caught comes back
+ * unresolved rather than slow.
+ */
+export type ResolutionRung = "exact" | "alias" | "lexical";
+/** One thing a phrase turned out to mean. */
+export interface ResolvedMeaning {
+    kind: ResolutionKind;
+    /**
+     * The canonical token. OPAQUE — hand it back verbatim, never parse, tidy or
+     * construct one. The single thing worth knowing about the SHAPE: a
+     * value-dictionary term id is unique only within its dictionary, so `colour`
+     * and `attribute_value` ids arrive namespaced as `<dictionaryId>.<termId>`.
+     */
+    id: string;
+    /** The canonical display term — what to show a human, not what to send back. */
+    term: string;
+    rung: ResolutionRung;
+    /**
+     * The resolver's own confidence in [0,1], present only when the underlying
+     * resolver produces one. Its ABSENCE is meaningful rather than missing data:
+     * the rung is then the whole statement, because an exact paint identity is an
+     * equality and not a score.
+     */
+    confidence?: number;
+    /**
+     * Present only when the resolver reported a runner-up. A small `gap` means the
+     * answer was nearly something else; when the resolver refused to break the tie,
+     * every tied reading is listed and `gap` is 0.
+     */
+    ambiguity?: {
+        gap: number;
+    };
+}
+/** What one phrase resolved to — including, explicitly, nothing. */
+export interface PhraseResolution {
+    /** The phrase exactly as you sent it, so you can rejoin the batch by value. */
+    phrase: string;
+    /**
+     * The phrase in the one normalised form the resolvers fold to — the same
+     * `normalise` stage a search query passes through. Empty when the phrase was
+     * all punctuation.
+     */
+    normalised: string;
+    /**
+     * Everything the phrase means here, best first. A phrase can legitimately mean
+     * several things at once ("sage" is two vendor paints AND a colour family), so
+     * this is a list rather than a winner.
+     */
+    resolved: ResolvedMeaning[];
+    /**
+     * TRUE when nothing resolved. Read this rather than inferring it from
+     * `resolved.length`: the redundancy is deliberate, because a consumer that
+     * cannot SEE what failed to resolve cannot tell a word this vocabulary does
+     * not have from a word something quietly dropped. Absent is not false — an
+     * unresolved phrase is a statement about this vocabulary, never about the
+     * material world.
+     */
+    unresolved: boolean;
+}
+/** The resolve response: one entry per phrase, in the order you sent them. */
+export interface ResolveResponse {
+    /** One per phrase, in request order — never reordered, never deduplicated. */
+    resolutions: PhraseResolution[];
+}

package/resolve-types.js

@@ -0,0 +1,17 @@
+/**
+ * The vocabulary lens (MG-913) — the hand-mirrored wire types for
+ * `POST /api/v1/resolve`.
+ *
+ * Split out of `types.ts` for the repository's source-file size budget, the same
+ * reason `suggest-types.ts` sits beside it; both are re-exported from `types.ts`,
+ * so importers see no difference.
+ *
+ * THE LENS: it turns WORDS into vocabulary, never into materials.
+ * `mg.search()` answers "I want materials" and `mg.answer` questions want prose;
+ * this answers "what do these words mean in your vocabulary?" — the question you
+ * ask BEFORE you spend a token on a filter, a facet or a brand slug. It is the
+ * reason you should not keep a hand-written table mapping your users' words onto
+ * this API's tokens: that table is a copy of a registry you do not own, and it
+ * drifts silently the moment the registry moves.
+ */
+export {};

package/run-events.d.ts

@@ -50,7 +50,18 @@ export interface CompositionReviewCriteriaSuggestion {
 export interface CompositionReviewCriteriaUnresolved {
     slotId: string;
     raw: string;
+    /**
+     * Ranked corrections, best first. MG-994: every one of these is an attribute
+     * the slot's own category holds accepted values for, so accepting the top
+     * suggestion can never leave the slot unfillable.
+     */
     suggestions: CompositionReviewCriteriaSuggestion[];
+    /**
+     * MG-994: attribute ids ranked for this phrase and then withheld — the slot's
+     * category holds no accepted value for them. ABSENT when nothing was withheld
+     * (absent means nothing was removed, not that nothing could be).
+     */
+    withheld?: string[];
 }
 /**
  * Payload of a `composition.review-criteria` / `material-box.review-criteria`

package/run-types.d.ts

@@ -233,6 +233,31 @@ export interface CreatePublicRunResponse {
 export interface PublicRunResponse {
     run: PublicRun;
 }
+/** Query for `GET /api/v1/runs` ({@link MaterialGraphClient.listRuns}). */
+export interface ListRunsOptions {
+    /**
+     * Return only Runs in this status. `"suspended"` is the recovery question:
+     * which of my Runs is still waiting on an answer?
+     */
+    status?: PublicRunStatus;
+    /** Page size, 1–100. Defaults to 20 server-side. */
+    limit?: number;
+    /**
+     * The previous page's {@link PublicRunListResponse.nextCursor}, round-tripped
+     * VERBATIM. It is opaque — never parse or construct one.
+     */
+    cursor?: string;
+    signal?: AbortSignal;
+}
+/** The `GET /api/v1/runs` response envelope — one page, newest first. */
+export interface PublicRunListResponse {
+    runs: PublicRun[];
+    /**
+     * Pass as {@link ListRunsOptions.cursor} for the next page. ABSENT — not
+     * empty-string, not null — once the last page has been served.
+     */
+    nextCursor?: string;
+}
 /** Body for `POST /api/v1/runs/{runId}/resume`. */
 export interface ResumePublicRunRequest {
     /** The resume payload, validated against the suspended step's resume schema. */

package/runs.d.ts

@@ -1,6 +1,6 @@
 import { HttpTransport } from "./http-transport.js";
 import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
-import { type CapabilityManifestResponse, type CreatePublicRunRequest, type CreatePublicRunResponse, type DrainRunEventsOptions, type PublicRunResponse, type ResumeRunOptions, type RunEvent, type SourceMaterialBatchDetail, type SourceMaterialBatchReceipt, type StreamRunEventsOptions, type UploadSourceMaterialInput } from "./run-types.js";
+import { type CapabilityManifestResponse, type CreatePublicRunRequest, type CreatePublicRunResponse, type DrainRunEventsOptions, type ListRunsOptions, type PublicRunListResponse, type PublicRunResponse, type ResumeRunOptions, type RunEvent, type SourceMaterialBatchDetail, type SourceMaterialBatchReceipt, type StreamRunEventsOptions, type UploadSourceMaterialInput } from "./run-types.js";
 /**
  * Upload one atomic source-material batch (`POST /api/v1/source-material`).
  * Accepts the pile-of-files shape (`{ files }` → repeatable `files` field) or
@@ -25,6 +25,20 @@ export declare function getSourceMaterialBatch(transport: HttpTransport, batchId
 export declare function capabilities(transport: HttpTransport, signal?: AbortSignal): Promise<CapabilityManifestResponse>;
 /** Start an asynchronous capability Run (`POST /api/v1/runs`). */
 export declare function createRun(transport: HttpTransport, body: CreatePublicRunRequest, signal?: AbortSignal): Promise<CreatePublicRunResponse>;
+/**
+ * List your own Runs, newest first (`GET /api/v1/runs`).
+ *
+ * The recovery path for a client that still holds its API key but has lost a Run
+ * id — a reinstalled app, or a crash before the id from {@link createRun} was
+ * persisted. `{ status: "suspended" }` finds the Run still waiting on an answer.
+ *
+ * Only the calling principal's own Runs are ever returned; there is no
+ * cross-principal listing.
+ *
+ * Page by following `nextCursor` until it is ABSENT — a full page is not the
+ * signal to stop, and an absent cursor is the only one.
+ */
+export declare function listRuns(transport: HttpTransport, options?: ListRunsOptions): Promise<PublicRunListResponse>;
 /** Get a Run's current state (`GET /api/v1/runs/{runId}`). */
 export declare function getRun(transport: HttpTransport, runId: string, signal?: AbortSignal): Promise<PublicRunResponse>;
 /**

package/runs.js

@@ -99,6 +99,30 @@ export function createRun(transport, body, signal) {
         signal,
     });
 }
+/**
+ * List your own Runs, newest first (`GET /api/v1/runs`).
+ *
+ * The recovery path for a client that still holds its API key but has lost a Run
+ * id — a reinstalled app, or a crash before the id from {@link createRun} was
+ * persisted. `{ status: "suspended" }` finds the Run still waiting on an answer.
+ *
+ * Only the calling principal's own Runs are ever returned; there is no
+ * cross-principal listing.
+ *
+ * Page by following `nextCursor` until it is ABSENT — a full page is not the
+ * signal to stop, and an absent cursor is the only one.
+ */
+export function listRuns(transport, options = {}) {
+    const query = {
+        ...(options.status === undefined ? {} : { status: options.status }),
+        ...(options.limit === undefined ? {} : { limit: options.limit }),
+        ...(options.cursor === undefined ? {} : { cursor: options.cursor }),
+    };
+    return transport.requestJson(runOperation("list_public_runs"), {
+        ...(Object.keys(query).length > 0 ? { query } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+}
 /** Get a Run's current state (`GET /api/v1/runs/{runId}`). */
 export function getRun(transport, runId, signal) {
     return transport.requestJson(runOperation("get_public_run"), {

package/schema-resource-types.d.ts

@@ -1,20 +1,23 @@
-/**
- * Wire types for the governed STATIC schema (`GET /api/v1/schema/*`).
- *
- * THE LENS: "what does the registry DEFINE?" — blocks, attributes, units, value
- * dictionaries, product types and their external mappings. Definitions, not
- * data: nothing here says how many materials carry an attribute or which values
- * the corpus holds. For that, use `mg.specificationFacets()` and
- * `mg.attributeValues()`; for one term explained in prose, `mg.glossary()`; for
- * what one material has been determined on, `mg.materialBlocks()`.
- *
- * Every id here (`attributeId`, `blockId`, product-type keys) is canonical
- * VOCABULARY, not an opaque token — this is where you discover it rather than
- * invent it.
- */
 import type { OpenEnum } from "./types.js";
 /** The nine governed static resources. */
 export type SchemaResource = "blocks" | "attributes" | "verticals" | "productTypes" | "units" | "valueDictionaries" | "sourceRequirements" | "productTypeTemplates" | "mappings";
+/**
+ * Resource → the operation that serves it. Internal to the SDK (`index.ts`
+ * re-exports this module's TYPES only), and it lives beside
+ * {@link SchemaResource} rather than in the client so the mapping and the union
+ * it must cover cannot drift apart.
+ */
+export declare const SCHEMA_RESOURCE_OPERATION_IDS: {
+    readonly blocks: "list_schema_blocks";
+    readonly attributes: "list_schema_attributes";
+    readonly verticals: "list_schema_verticals";
+    readonly productTypes: "list_schema_product_types";
+    readonly units: "list_schema_units";
+    readonly valueDictionaries: "list_schema_value_dictionaries";
+    readonly sourceRequirements: "list_schema_source_requirements";
+    readonly productTypeTemplates: "list_schema_product_type_templates";
+    readonly mappings: "list_schema_mappings";
+};
 export type SchemaResourceRequest = SchemaResource;
 export interface SchemaLifecycle {
     status: OpenEnum<"draft" | "active" | "deprecated">;

package/schema-resource-types.js

@@ -1 +1,17 @@
-export {};
+/**
+ * Resource → the operation that serves it. Internal to the SDK (`index.ts`
+ * re-exports this module's TYPES only), and it lives beside
+ * {@link SchemaResource} rather than in the client so the mapping and the union
+ * it must cover cannot drift apart.
+ */
+export const SCHEMA_RESOURCE_OPERATION_IDS = {
+    blocks: "list_schema_blocks",
+    attributes: "list_schema_attributes",
+    verticals: "list_schema_verticals",
+    productTypes: "list_schema_product_types",
+    units: "list_schema_units",
+    valueDictionaries: "list_schema_value_dictionaries",
+    sourceRequirements: "list_schema_source_requirements",
+    productTypeTemplates: "list_schema_product_type_templates",
+    mappings: "list_schema_mappings",
+};

package/search-result-validation.js

@@ -143,6 +143,14 @@ export function checkSearchResultItem(value, what, fail) {
     requireString(record.product, `${what}.product`, fail);
     requireNullableString(record.brandSlug, `${what}.brandSlug`, fail);
     requireNullableString(record.productId, `${what}.productId`, fail);
+    // `z.string().optional()` — absent, or a string. NOT nullable: the emit path
+    // omits the key rather than sending null when no MB identity is known.
+    requireOptionalString(record.materialBankId, `${what}.materialBankId`, fail);
+    // Same shape as `materialBankId`: absent, or a string. The emit path omits
+    // the key when no primary product type is on record rather than sending null,
+    // so "we don't know what this is" and "this is a null kind of thing" cannot
+    // be confused.
+    requireOptionalString(record.productType, `${what}.productType`, fail);
     requireNullableString(record.color, `${what}.color`, fail);
     requireNullableString(record.variantName, `${what}.variantName`, fail);
     requireNullableString(record.imageUrl, `${what}.imageUrl`, fail);

package/types.d.ts

@@ -25,6 +25,7 @@
  *     match set. Follow the cursor for the rest, and never report a page size as
  *     a total.
  */
+import type { ByColourSwatch } from "./by-colour-types.js";
 import type { BySpecVerdict } from "./by-spec-types.js";
 import type { Cursor, ProductId, VariantId } from "./identifiers.js";
 import type { MaterialDetail, MaterialTile } from "./material-types.js";
@@ -39,12 +40,22 @@ export type OpenEnum<T extends string> = T | (string & {});
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
-/** One palette swatch of a material's main image. */
+/**
+ * One palette swatch of a material's main image — colour DERIVED FROM PRODUCT
+ * IMAGERY, so read it as visual likeness, never as a declared colour spec.
+ */
 export interface PaletteSwatch {
     hex: string;
     proportion: number;
     /** Stored human colour name for the swatch, when one was extracted. */
     name?: string | null;
+    /**
+     * `hex` in OKLab, derived server-side so you can sort or measure swatches
+     * without converting them yourself. Additive, so optional: the colour lane and
+     * the material record carry it, other surfaces may not, and absent means "not
+     * derived here" — never "achromatic".
+     */
+    oklab?: OklabTriple;
 }
 /** Loose colour metadata for a search result's main image; every field is independently optional. */
 export interface ColourMeta {
@@ -109,6 +120,30 @@ export interface SearchResultItem {
     product: string;
     brandSlug: string | null;
     productId: ProductId | null;
+    /**
+     * The variant's Material Bank SKU — the same `materialBankId` the material
+     * record carries, so a match card can render straight from a result instead of
+     * paying a per-result lookup. Populated on the MATCH lanes (`match()` and
+     * `matchStream()` frames).
+     *
+     * ABSENT means no MB identity is known for the variant — never that the SKU
+     * cannot be ordered. Presence is the orderability tell; absence is silence.
+     */
+    materialBankId?: string;
+    /**
+     * What kind of material this is — the variant's primary product type, as a
+     * display name (`"Wall Tile"`, `"Modular Carpet"`, `"Interior Paint"`).
+     *
+     * This is the field that lets you tell a wall tile from a bar stool without
+     * parsing `product`. Before it existed, callers grading Match results had to
+     * regex the product's NAME, and one such grader scored pendant lights and
+     * electrical sockets as correct answers for a wall — because they are neither
+     * a stool nor a chair.
+     *
+     * ABSENT means no primary type is on record for the variant. Unknown, never
+     * "uncategorised" and never "not a material".
+     */
+    productType?: string;
     color: string | null;
     variantName: string | null;
     imageUrl: string | null;
@@ -117,6 +152,35 @@ export interface SearchResultItem {
     colourMeta?: ColourMeta;
     /** Fused score — range [0, sum of active weights]; see `maxScore`. */
     score: number;
+    /**
+     * Match only. How close this material is to the query, as an ABSOLUTE
+     * image-space similarity in [0,1] adjusted for colour — the same unit as
+     * `qualityFloor` and `comparison.bestRejected`, so all three sit on one axis.
+     *
+     * Never normalised against the page, so the same material reads the same in
+     * two different searches. It is the TRUE value and MAY reach 1 — rendering it
+     * so that no card claims "100%" is yours to do (round toward zero, or show
+     * "99%+"); `Math.round` prints 100% from 0.995 up. Capping it server-side
+     * would put it on a different ceiling from `comparison.bestRejected`, which
+     * publishes the same unit uncapped, and the two are meant to be comparable.
+     * `score` is the ranking value and lives on a different scale.
+     */
+    confidence?: number;
+    /**
+     * `confidence` as a word — `strong` >= 0.85, `good` >= 0.72, `fair` >= 0.55
+     * (the default quality floor), `weak` below it and only reachable under
+     * `includeBelowFloor`. Present exactly when `confidence` is.
+     */
+    confidenceBand?: "strong" | "good" | "fair" | "weak";
+    /**
+     * Match only. Proportion-weighted OKLab distance from the query crop's palette
+     * to this material's. `null` means the material carries no stored palette —
+     * UNKNOWN colour, never "no colour" and never "distant". Absent when the
+     * colour stage did not run.
+     */
+    colourDistance?: number | null;
+    /** `colourDistance` as a word, or null when unmeasurable. */
+    colourBand?: string | null;
     signals?: SearchResultSignals;
     retired?: boolean;
     /**
@@ -223,69 +287,6 @@ export interface SearchCardResponse extends Omit<SearchResponse, "view" | "resul
     view: OpenEnum<"card">;
     results: SearchCardItem[];
 }
-/** An inferred product-type category from the query image, with its boost. */
-export interface MatchCategoryInference {
-    productTypeId: string;
-    displayName: string;
-    boost: number;
-}
-/**
- * The Material Match response (non-streaming form).
- *
- * `poolSize` is the candidate pool the floor was applied to, NOT a corpus total
- * and NOT "how many materials look like this". An empty `results` with
- * `droppedBelowFloor > 0` means "candidates existed and none was good enough" —
- * a different answer from `poolSize: 0`, which means the image found nothing to
- * search against at all.
- */
-export interface MatchResponse {
-    /** THIS answer, capped by `limit`. Not a total. */
-    results: SearchResultItem[];
-    inferredCategories: MatchCategoryInference[];
-    qualityFloor: number;
-    poolSize: number;
-    droppedBelowFloor: number;
-    droppedAsDuplicateProduct: number;
-    note?: string;
-}
-/** Coarse group + fine type of a colour match's primary product type. */
-export interface MatchCategory {
-    group: string | null;
-    type: string | null;
-}
-/**
- * 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.
- */
-export interface ByColourMatch {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    brand: string;
-    product: string;
-    color: string | null;
-    variantName: string | null;
-    imageUrl: string | null;
-    hex: string | null;
-    distance: number;
-    closeness: number;
-    category: MatchCategory | null;
-    oklab: OklabTriple | null;
-}
-/** The `search/colours` response. */
-export interface ByColourResponse {
-    query: {
-        colours: string[];
-        categories?: string[];
-        oklab?: OklabTriple;
-    };
-    /** `matches.length` — THIS PAGE. Not a corpus total; this surface states none. */
-    count: number;
-    matches: ByColourMatch[];
-}
 /** One item from the pure colour-scalar browse. */
 export interface BrowseResultItem {
     /** Opaque — round-trip verbatim. */
@@ -303,6 +304,17 @@ export interface BrowseResultItem {
         vibrancy: number | null;
     };
     retired?: boolean;
+    /**
+     * The row's own image palette — the FULL stored palette of the SAME image
+     * `imageUrl` serves, uncapped and in stored order, each swatch with `oklab`
+     * (see {@link ByColourSwatch}), so a card can render, sort or group colours
+     * without a second call. A one-swatch palette means the extractor found one
+     * colour (solid-colour materials are genuinely monochrome), not that the list
+     * was trimmed. ABSENT when no palette is on record for that image: absent
+     * means unknown, NOT that the material has no colours. These swatches come
+     * from product imagery, not from the manufacturer.
+     */
+    palette?: ByColourSwatch[];
 }
 /**
  * A single page of the colour browse — the SDK's one genuinely cursor-paginated
@@ -508,6 +520,7 @@ export interface ResolveAttributeResponse {
     candidates: AttributeCandidate[];
 }
 export type * from "./catalog-discovery-types.js";
+export type * from "./resolve-types.js";
 export type * from "./suggest-types.js";
 export type * from "./by-spec-types.js";
 export interface WhoamiResponse {
@@ -626,20 +639,6 @@ export interface SearchGetParams {
     /** Result projection — `"full"` (default) or the lean `"card"` grid form. */
     view?: OpenEnum<"full" | "card">;
 }
-/** Params for `search/colours`. */
-export interface ByColourParams {
-    /** A single hex (with or without `#`). */
-    hex?: string;
-    /** A palette — repeated as one `colour` query entry each. */
-    colour?: string | string[];
-    /** OKLab triple (all-or-none). */
-    l?: number;
-    a?: number;
-    b?: number;
-    /** HARD category filter — display names or taxonomy ids (repeatable). */
-    category?: string | string[];
-    limit?: number;
-}
 /** Params for the pure colour `search/browse` surface. */
 export interface BrowseParams {
     sort: OpenEnum<"light" | "dark" | "vivid" | "muted" | "colourful">;
@@ -650,34 +649,14 @@ export interface BrowseParams {
     cursor?: Cursor;
     /** Page size. */
     limit?: number;
-    /** Comma-separated product-type ids to restrict the browse to. */
-    types?: string;
-}
-/** The Material Match request body — exactly one of `imageBase64`, `imageUrl`, `vector`. */
-export interface MatchInput {
-    imageBase64?: string;
-    imageUrl?: string;
-    vector?: string;
-    limit?: number;
-    qualityFloor?: number;
-    categoryTopK?: number;
-    categoryMinBoost?: number;
-    detectionLabel?: string;
-    materialFunction?: string;
-    detectionCategory?: string;
     /**
-     * Opt-in: also return quality-floor rejects, flagged `belowFloor: true` and
-     * appended after the kept results. Absent/false = default behaviour;
-     * `droppedBelowFloor` is unchanged.
+     * Comma-separated taxonomy keys to restrict the browse to, at EITHER tier of
+     * `/api/v1/taxonomy/categories`. A GROUP key (`tile_surfaces`) expands to
+     * every product type under it, a TYPE key (`ceramic_porcelain_tile`) stands
+     * for itself, and a mixed list is their deduplicated union. A key in neither
+     * tier is a 400 listing the valid keys — never an empty page.
      */
-    includeBelowFloor?: boolean;
-    requestedType?: OpenEnum<"swatch" | "installation" | "flatplan">;
-    /** Hard spec gates forwarded verbatim to the inner search — term match or presence, each with an optional trust bar. */
-    filters?: SearchFilter[];
-    /** Soft criteria (rank-never-exclude). A miss demotes within the page but never removes a hit. */
-    preferences?: SearchFilter[];
-    /** Opt in to seed-relative verdict cells; inert unless the inner search carries a variant seed. */
-    verdicts?: boolean;
+    types?: string;
 }
 /** Options for a batch material read. */
 export interface MaterialsBatchOptions {