@instruments/materialgraph 0.10.0 → 0.11.0

package/browse-types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Wire types for the browse lane — GET `/api/v1/search/browse`.
+ *
+ * The SDK's one genuinely cursor-paginated surface, and the only lane with no
+ * query, no relevance and no ranking: the corpus in a stated order. That is what
+ * a category listing or a brand fan deck actually needs, and it is why `count`
+ * matters here more than anywhere else — a listing that cannot state its own
+ * size has to either walk every page or report a page size as a total.
+ *
+ * Lifted out of `types.ts` for the repository's source-file size budget when the
+ * lane gained its non-colour sorts and its feed count (MG-1483 / MG-1542).
+ * Nothing about the client's surface changed: `index.ts` re-exports these
+ * exactly as before.
+ */
+import type { ByColourSwatch } from "./by-colour-types.js";
+import type { Cursor, ProductId, VariantId } from "./identifiers.js";
+import type { CountedTotal, OpenEnum } from "./types.js";
+/** One item from the pure colour-scalar browse. */
+export interface BrowseResultItem {
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
+    brand: string;
+    product: string;
+    brandSlug: string | null;
+    productId: ProductId | null;
+    color: string | null;
+    variantName: string | null;
+    imageUrl: string | null;
+    scalars: {
+        l: number | null;
+        chroma: number | null;
+        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[];
+}
+/** The browse orders. `name` (A→Z) is the default; `recent` is newest first. */
+export type BrowseSort = OpenEnum<"name" | "recent" | "light" | "dark" | "vivid" | "muted" | "colourful">;
+/**
+ * The browse feed's total — how many materials the browse DESCRIBES, which is
+ * never `results.length`.
+ *
+ * Uncapped, unlike {@link SearchCounts}: `basis:"exact"` is the true figure
+ * whatever its size, and `basis:"lowerBound"` means the count query timed out
+ * and the value is a floor. Counted over the SAME filters the page was drawn
+ * from, so a `types=`, `brands=` or `corpusScope=` narrowed browse reports the
+ * narrowed total — you will never get a whole-graph number beside a filtered
+ * page.
+ */
+export interface BrowseCounts {
+    variants: CountedTotal;
+}
+/**
+ * A single page of the browse — the SDK's one genuinely cursor-paginated
+ * surface. `results.length` is this page. Ask for `count: true` and `counts`
+ * states the total; without it the browse states no total at all, and a corpus
+ * claim can only come from walking every page (`client.browse.pages(...)` does
+ * the loop).
+ */
+export interface BrowseResponse {
+    /** THIS PAGE. */
+    results: BrowseResultItem[];
+    /** Opaque keyset for the next page. Absent = the walk is finished. */
+    cursor?: Cursor;
+    /**
+     * The order this page was built in — echoed, because `sort` is optional and
+     * defaulted, so a caller that omitted it need not know the server's default
+     * to label its own listing.
+     */
+    sort: BrowseSort;
+    /**
+     * The total, present ONLY when `count: true` was passed. Absent means it was
+     * not asked for — never that the set is empty.
+     */
+    counts?: BrowseCounts;
+    /**
+     * The corpus this page was drawn from — present ONLY when the request
+     * narrowed it. ABSENT means the whole graph: every material MaterialGraph
+     * knows, orderable or not.
+     */
+    corpusScope?: {
+        scope: OpenEnum<"all" | "materialBankOrderable">;
+        /** What the scope admits, in one sentence, for a human reader. */
+        description: string;
+    };
+}
+/** Params for the pure colour `search/browse` surface. */
+export interface BrowseParams {
+    /**
+     * OPTIONAL. Defaults to `name` (A→Z); `recent` is newest first.
+     *
+     * The five colour ramps (`light`/`dark`/`vivid`/`muted`/`colourful`) order by
+     * an EXTRACTED colour scalar and therefore see only colour-extracted
+     * materials — a genuinely smaller set than `name` and `recent` walk. That is
+     * not a bug to route around; ask for `count` and each sort reports the size of
+     * the set it actually describes.
+     */
+    sort?: BrowseSort;
+    /**
+     * The previous page's `cursor`, verbatim. Opaque keyset state — not an offset.
+     * Changing `sort`, `limit`, `types`, `brands` or `corpusScope` invalidates it.
+     */
+    cursor?: Cursor;
+    /** Page size. */
+    limit?: number;
+    /**
+     * Return `counts.variants` — the total size of the set this browse walks,
+     * counted over the same filters the page came from.
+     *
+     * Opt-in, because it is a second query. A category listing that cannot state
+     * how many things it is listing has to either walk every page or report the
+     * page size as a total; this is the third option.
+     */
+    count?: boolean;
+    /**
+     * 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.
+     */
+    types?: string;
+    /**
+     * Comma-separated brand slugs (`farrow-ball`) or display names
+     * (`Farrow & Ball`), case-insensitive. One brand plus a colour `sort` is that
+     * brand's fan deck. An unknown brand is a 400 naming it, never an empty page.
+     */
+    brands?: string;
+    /**
+     * Which corpus to walk. ABSENT means the whole graph — every material
+     * MaterialGraph knows, orderable or not. `materialBankOrderable` restricts to
+     * materials carrying a Material Bank identity, applied inside the scan, so a
+     * scoped page is still a full page and `cursor` still means another eligible
+     * row exists.
+     */
+    corpusScope?: OpenEnum<"all" | "materialBankOrderable">;
+}

package/browse-types.js

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

package/by-colour-types.d.ts

@@ -106,6 +106,44 @@ export interface ColourCollapse {
     /** Rows dropped for resolving to a better-ranked row's stored photograph. */
     droppedBySharedImage: number;
 }
+/**
+ * Receipt naming which retrieval lane answered, and the colours it actually ran
+ * on. The live endpoint always sends it.
+ *
+ * Two lanes answer two different questions. A ONE-COLOUR query is a CONTAINMENT
+ * question — which materials hold a swatch near this colour — and is answered as
+ * a bounded OKLab ball over stored palette swatches. A multi-colour query is a
+ * SIMILARITY question — which palettes as a whole resemble this palette — and is
+ * answered by nearest-neighbour over the palette embedding. The two rank on
+ * different geometries, so `colourDistance` on a match means a different thing
+ * in each and is NOT comparable across them.
+ */
+export interface ColourLaneReceipt {
+    /** Which lane answered. Widened so a new server lane still type-checks. */
+    lane: OpenEnum<"containment" | "palette">;
+    /** Why this lane, in one sentence, for a human reader. */
+    reason: string;
+    /**
+     * How the page was ordered. `representative` — the containment default —
+     * draws the page in the contained set's own proportions of solid and
+     * multi-swatch materials, nearest-first within each, because ordering
+     * containment by proximity alone returns a page of solid-colour materials.
+     */
+    order: OpenEnum<"representative" | "nearest" | "similarity">;
+    /**
+     * The colours the search ACTUALLY ran on, after minor-proportion accents were
+     * dropped. Compare against `query.colours`: a difference means the search that
+     * ran is not the search you asked for.
+     */
+    effectiveColours: string[];
+    /**
+     * Colours removed from your query for carrying a proportion below the accent
+     * threshold. EMPTY is the normal case. Non-empty and those colours were absent
+     * from retrieval entirely — they did not merely rank low, so an empty-looking
+     * result is not evidence that nothing holds them.
+     */
+    droppedColours: string[];
+}
 /** The `search/colours` response. */
 export interface ByColourResponse {
     query: {
@@ -135,6 +173,24 @@ export interface ByColourResponse {
      * overfetch allowed, and this says so in counts rather than adjectives.
      */
     collapse?: ColourCollapse;
+    /**
+     * Which retrieval lane answered and the colours it ran on. The live endpoint
+     * always sends it; optional here only so responses captured before the lane
+     * split still type-check.
+     */
+    lane?: ColourLaneReceipt;
+    /**
+     * The corpus this page was drawn from — present ONLY when the request
+     * narrowed it. ABSENT means the whole graph: every material MaterialGraph
+     * knows, orderable or not. Under a scope the `familyGate` and `collapse` pool
+     * counts describe the SCOPED corpus too, because the scope was applied inside
+     * retrieval rather than over the page it produced.
+     */
+    corpusScope?: {
+        scope: OpenEnum<"all" | "materialBankOrderable">;
+        /** What the scope admits, in one sentence, for a human reader. */
+        description: string;
+    };
 }
 /** Params for `search/colours`. */
 export interface ByColourParams {

package/client-browse.d.ts

@@ -9,7 +9,7 @@
  * the pagination LOOP, which is the only real logic here and the only part worth
  * testing on its own.
  */
-import type { BrowseParams, BrowseResponse } from "./types.js";
+import type { BrowseParams, BrowseResponse } from "./browse-types.js";
 /**
  * `client.browse(...)` — callable for ONE PAGE, `.pages()` for the whole walk.
  *
@@ -24,14 +24,24 @@ export interface BrowseNamespace {
 /** Fetch one page. The client supplies this, so the transport stays private. */
 export type BrowsePageFetcher = (params: BrowseParams, signal?: AbortSignal) => Promise<BrowseResponse>;
 /**
- * The query string for one browse page — the four params the route reads, named
- * here so the client method and the pagination loop cannot disagree about them.
+ * The query string for one browse page — EVERY param the route reads, named here
+ * so the client method and the pagination loop cannot disagree about them.
+ *
+ * "Every" is load-bearing. This is an allow-list wrapper, and an allow-list
+ * wrapper that rebuilds a query from named fields is precisely the shape that
+ * silently drops a param the server already honours: `brands` shipped on the
+ * route and never reached it from here, so the fan deck was unreachable through
+ * the published client while the server had supported it all along. When the
+ * route gains a param, it gains a line HERE too, or it is not shipped.
  */
 export declare function browseQuery(params: BrowseParams): {
     sort: BrowseParams["sort"];
     cursor: BrowseParams["cursor"];
     limit: BrowseParams["limit"];
+    count: BrowseParams["count"];
     types: BrowseParams["types"];
+    brands: BrowseParams["brands"];
+    corpusScope: BrowseParams["corpusScope"];
 };
 /**
  * Walk every page from `params.cursor` onward.

package/client-browse.js

@@ -1,13 +1,23 @@
 /**
- * The query string for one browse page — the four params the route reads, named
- * here so the client method and the pagination loop cannot disagree about them.
+ * The query string for one browse page — EVERY param the route reads, named here
+ * so the client method and the pagination loop cannot disagree about them.
+ *
+ * "Every" is load-bearing. This is an allow-list wrapper, and an allow-list
+ * wrapper that rebuilds a query from named fields is precisely the shape that
+ * silently drops a param the server already honours: `brands` shipped on the
+ * route and never reached it from here, so the fan deck was unreachable through
+ * the published client while the server had supported it all along. When the
+ * route gains a param, it gains a line HERE too, or it is not shipped.
  */
 export function browseQuery(params) {
     return {
         sort: params.sort,
         cursor: params.cursor,
         limit: params.limit,
+        count: params.count,
         types: params.types,
+        brands: params.brands,
+        corpusScope: params.corpusScope,
     };
 }
 /**

package/client-exploration.d.ts

@@ -0,0 +1,9 @@
+import type { CandidateReadInput, CandidateReadResponse, GraphOperatorEvidence } from "./exploration-types.js";
+import type { HttpTransport } from "./http-transport.js";
+import type { VariantId } from "./identifiers.js";
+/** Discovery and traversal share one namespace so availability precedes use. */
+export interface ExplorationNamespace {
+    operators(variantId: VariantId, signal?: AbortSignal): Promise<GraphOperatorEvidence>;
+    candidates(variantId: VariantId, input: CandidateReadInput, signal?: AbortSignal): Promise<CandidateReadResponse>;
+}
+export declare function createExplorationNamespace(transport: HttpTransport): ExplorationNamespace;

package/client-exploration.js

@@ -0,0 +1,7 @@
+import { resolveOperation } from "./operations.js";
+export function createExplorationNamespace(transport) {
+    return {
+        operators: (variantId, signal) => transport.requestJson(resolveOperation("list_material_operators"), { pathParams: { variantId }, signal }),
+        candidates: (variantId, input, signal) => transport.requestJson(resolveOperation("read_material_candidates"), { body: input, pathParams: { variantId }, signal }),
+    };
+}

package/client-source-material-comments.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The per-file comment surface, namespaced as `mg.sourceMaterialComments` — the
+ * argument people leave on one uploaded file (MG-1345).
+ *
+ * A namespace rather than two more flat methods on an already-large facade,
+ * following `mg.codes` and `mg.colours`: reading a thread and adding to it are
+ * one family, they share a `(batchId, sourceId)` referent, and neither makes
+ * sense without the other. The namespace holds no transport of its own — the
+ * client hands it the shared one, so auth, rate-limit accounting and error
+ * shaping stay in one place.
+ *
+ * TWO RULES A CONSUMER MUST NOT GET WRONG.
+ *
+ * **The author name is REPORTED, never verified.** Every comment carries
+ * `author.attribution: "reported"` — a name somebody typed — plus `recordedBy`,
+ * the authenticated principal that actually wrote the row. Render "recorded as
+ * from Ruth Fielding", never "Ruth Fielding said". The API takes a machine key,
+ * and the person whose argument a remark carries is usually not the person at
+ * the keyboard; presenting the one as the other is the failure this field
+ * exists to prevent.
+ *
+ * **A reply is not a root.** {@link SourceMaterialCommentsNamespace.post}
+ * returns a result discriminated on `kind`: switch on it rather than reaching
+ * for `replies`, which a `reply` does not have. Threads are one level deep and
+ * the database enforces it, so a reply can never grow replies of its own.
+ *
+ * ROUTING OUT OF THIS NAMESPACE. `mg.sourceMaterialBatch(batchId)` already
+ * inlines every file's thread, so opening a batch is ONE call — do not loop this
+ * namespace over a batch's files to rebuild what that read returns. Reach for
+ * `list` when you are watching a single file.
+ */
+import { HttpTransport } from "./http-transport.js";
+import type { PostSourceMaterialCommentInput, PostSourceMaterialCommentResult, SourceMaterialCommentThread } from "./run-types.js";
+export interface SourceMaterialCommentsNamespace {
+    /**
+     * One file's thread, oldest root first, each root carrying its replies.
+     * `comments` is always an array; `truncated` says whether you are holding the
+     * whole thread. A file that is not in that batch, or a batch you do not own,
+     * raises the same 404 as a file that never existed.
+     */
+    list(batchId: string, sourceId: string, signal?: AbortSignal): Promise<SourceMaterialCommentThread>;
+    /**
+     * Add one remark. Pass `parentCommentId` to answer a ROOT comment on the same
+     * file; nesting deeper is a 400. Pass `idempotencyKey` so a retry after a
+     * network timeout returns the comment you already posted rather than a
+     * permanent duplicate.
+     */
+    post(batchId: string, sourceId: string, input: PostSourceMaterialCommentInput, signal?: AbortSignal): Promise<PostSourceMaterialCommentResult>;
+}
+/** Bind the comment operations to the client's shared transport. */
+export declare function createSourceMaterialCommentsNamespace(transport: HttpTransport): SourceMaterialCommentsNamespace;

package/client-source-material-comments.js

@@ -0,0 +1,40 @@
+/**
+ * The per-file comment surface, namespaced as `mg.sourceMaterialComments` — the
+ * argument people leave on one uploaded file (MG-1345).
+ *
+ * A namespace rather than two more flat methods on an already-large facade,
+ * following `mg.codes` and `mg.colours`: reading a thread and adding to it are
+ * one family, they share a `(batchId, sourceId)` referent, and neither makes
+ * sense without the other. The namespace holds no transport of its own — the
+ * client hands it the shared one, so auth, rate-limit accounting and error
+ * shaping stay in one place.
+ *
+ * TWO RULES A CONSUMER MUST NOT GET WRONG.
+ *
+ * **The author name is REPORTED, never verified.** Every comment carries
+ * `author.attribution: "reported"` — a name somebody typed — plus `recordedBy`,
+ * the authenticated principal that actually wrote the row. Render "recorded as
+ * from Ruth Fielding", never "Ruth Fielding said". The API takes a machine key,
+ * and the person whose argument a remark carries is usually not the person at
+ * the keyboard; presenting the one as the other is the failure this field
+ * exists to prevent.
+ *
+ * **A reply is not a root.** {@link SourceMaterialCommentsNamespace.post}
+ * returns a result discriminated on `kind`: switch on it rather than reaching
+ * for `replies`, which a `reply` does not have. Threads are one level deep and
+ * the database enforces it, so a reply can never grow replies of its own.
+ *
+ * ROUTING OUT OF THIS NAMESPACE. `mg.sourceMaterialBatch(batchId)` already
+ * inlines every file's thread, so opening a batch is ONE call — do not loop this
+ * namespace over a batch's files to rebuild what that read returns. Reach for
+ * `list` when you are watching a single file.
+ */
+import { HttpTransport } from "./http-transport.js";
+import { listSourceMaterialComments, postSourceMaterialComment, } from "./runs.js";
+/** Bind the comment operations to the client's shared transport. */
+export function createSourceMaterialCommentsNamespace(transport) {
+    return {
+        list: (batchId, sourceId, signal) => listSourceMaterialComments(transport, batchId, sourceId, signal),
+        post: (batchId, sourceId, input, signal) => postSourceMaterialComment(transport, batchId, sourceId, input, signal),
+    };
+}

package/client.d.ts

@@ -2,7 +2,11 @@ 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";
+import { type ExplorationNamespace } from "./client-exploration.js";
 export type { BrowseNamespace } from "./client-browse.js";
+export type { ExplorationNamespace } from "./client-exploration.js";
+import { type SourceMaterialCommentsNamespace } from "./client-source-material-comments.js";
+export type { SourceMaterialCommentsNamespace } from "./client-source-material-comments.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";
@@ -20,6 +24,7 @@ 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 { SlotPoolsRequest, SlotPoolsResponse } from "./slot-pool-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";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
@@ -61,14 +66,21 @@ export declare class MaterialGraphClient {
     #private;
     readonly baseUrl: string;
     /**
-     * THE QUESTION: "show me everything, ordered lightest / most vivid / most
-     * muted." Pure colour scalars — no query, no relevance. `browse({ sort })` is
-     * one page; `browse.pages({ sort })` walks them all, and only the walk can
-     * support a corpus claim.
+     * THE QUESTION: "show me everything in this category / this brand, in a plain
+     * order." No query, no relevance, no ranking. `browse(params)` is one page;
+     * `browse.pages(params)` walks them all.
+     *
+     * `sort` is optional (`name` A→Z by default, `recent` for newest first, plus
+     * the five colour ramps), `types`/`brands`/`corpusScope` narrow it, and
+     * `count: true` returns the total so a listing can say how many things it is
+     * listing without walking every page. `results.length` remains a PAGE.
      *
      * Instead use {@link MaterialGraphClient.byColour} for materials NEAR a colour,
      * {@link MaterialGraphClient.search} when there is anything to rank against,
      * and `colours.profiles()` for a category's palette rather than its members.
+     *
+     * @example A category listing that can state its own size
+     * const page = await client.browse({ types: "tile_surfaces", count: true });
      */
     readonly browse: BrowseNamespace;
     /**
@@ -94,6 +106,14 @@ export declare class MaterialGraphClient {
      * likeness, never a declared colour specification.
      */
     readonly colours: ColoursClient;
+    /** Discover honest graph questions, then traverse one explicit operator. */
+    readonly exploration: ExplorationNamespace;
+    /**
+     * THE QUESTION: "what did people say about this uploaded file, and record what
+     * they said." Names on these remarks are REPORTED, never verified — see
+     * {@link SourceMaterialCommentsNamespace}.
+     */
+    readonly sourceMaterialComments: SourceMaterialCommentsNamespace;
     constructor(options: MaterialGraphClientOptions);
     get lastRateLimit(): RateLimit | null;
     /**
@@ -364,17 +384,7 @@ export declare class MaterialGraphClient {
      * and `mg:admin` unlocks extra evidence fields.
      */
     whoami(signal?: AbortSignal): Promise<WhoamiResponse>;
-    /**
-     * THE QUESTION: "here is my whole scheme so far — what completes it?" The
-     * multi-seed form of {@link MaterialGraphClient.pairings}: lift is summed across
-     * seeds, so a companion suiting one pick ranks below one suiting several.
-     * Instead use `pairings` for a single material and `colours.palette()` when the
-     * scheme is COLOURS rather than materials. Check `unresolved` before presenting.
-     *
-     * Coordinate a palette of already-chosen materials (POST
-     * `/api/v1/pairings/coordinate`). Returns demand-lift-ranked companions with
-     * colour swatches and an annotate-only `colourFit` (never reorders in v1).
-     */
+    /** What completes a scheme already part-chosen. See {@link coordinateCall}. */
     coordinate(input: CoordinateInput, signal?: AbortSignal): Promise<CoordinateResponse>;
     /**
      * THE QUESTION: "how much is this material actually specified, and what gets
@@ -553,14 +563,10 @@ export declare class MaterialGraphClient {
      * Poll {@link MaterialGraphClient.run} for the terminal state.
      */
     cancelRun(runId: RunId, signal?: AbortSignal): Promise<PublicRunResponse>;
-    /**
-     * Derive an "option B" scheme from a succeeded compose Run along one
-     * constraint axis (POST `/api/v1/schemes/vary`). Deterministic and
-     * synchronous — the response IS the hydrated scheme (no Run envelope), stamped
-     * with axis + source provenance whose `notes` are the variation's receipts.
-     * Requires the `mg:read` scope.
-     */
+    /** Option B from a composed Run, along one axis. See {@link varySchemeCall}. */
     varyScheme(body: VarySchemesRequest, signal?: AbortSignal): Promise<VarySchemesResponse>;
+    /** Ranked candidate pools for up to 24 slots. See {@link slotPoolsCall}. */
+    slotPools(body: SlotPoolsRequest, signal?: AbortSignal): Promise<SlotPoolsResponse>;
     /**
      * Stream ordered Run events as an async iterator (GET
      * `/api/v1/runs/{runId}/events`, SSE). Iterates until the stream ends or the

package/client.js

@@ -7,10 +7,14 @@ import { cancelRun, capabilities as capabilitiesRun, createRun, drainRunEvents,
 // 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 { createExplorationNamespace, } from "./client-exploration.js";
+import { createSourceMaterialCommentsNamespace, } from "./client-source-material-comments.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 { slotPools as slotPoolsCall, varyScheme as varySchemeCall, } from "./composition-client.js";
+import { coordinate as coordinateCall } from "./coordinate-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";
@@ -55,14 +59,21 @@ import { suggestQuery } from "./suggest-types.js";
 export class MaterialGraphClient {
     baseUrl;
     /**
-     * THE QUESTION: "show me everything, ordered lightest / most vivid / most
-     * muted." Pure colour scalars — no query, no relevance. `browse({ sort })` is
-     * one page; `browse.pages({ sort })` walks them all, and only the walk can
-     * support a corpus claim.
+     * THE QUESTION: "show me everything in this category / this brand, in a plain
+     * order." No query, no relevance, no ranking. `browse(params)` is one page;
+     * `browse.pages(params)` walks them all.
+     *
+     * `sort` is optional (`name` A→Z by default, `recent` for newest first, plus
+     * the five colour ramps), `types`/`brands`/`corpusScope` narrow it, and
+     * `count: true` returns the total so a listing can say how many things it is
+     * listing without walking every page. `results.length` remains a PAGE.
      *
      * Instead use {@link MaterialGraphClient.byColour} for materials NEAR a colour,
      * {@link MaterialGraphClient.search} when there is anything to rank against,
      * and `colours.profiles()` for a category's palette rather than its members.
+     *
+     * @example A category listing that can state its own size
+     * const page = await client.browse({ types: "tile_surfaces", count: true });
      */
     browse;
     /**
@@ -88,6 +99,14 @@ export class MaterialGraphClient {
      * likeness, never a declared colour specification.
      */
     colours;
+    /** Discover honest graph questions, then traverse one explicit operator. */
+    exploration;
+    /**
+     * THE QUESTION: "what did people say about this uploaded file, and record what
+     * they said." Names on these remarks are REPORTED, never verified — see
+     * {@link SourceMaterialCommentsNamespace}.
+     */
+    sourceMaterialComments;
     #transport;
     constructor(options) {
         if (!options.apiKey) {
@@ -108,6 +127,8 @@ export class MaterialGraphClient {
             get: (operationId, query, signal) => this.#get(operationId, query, signal),
             post: (operationId, body, signal) => this.#post(operationId, body, signal),
         });
+        this.exploration = createExplorationNamespace(this.#transport);
+        this.sourceMaterialComments = createSourceMaterialCommentsNamespace(this.#transport);
     }
     get lastRateLimit() {
         return this.#transport.lastRateLimit;
@@ -452,19 +473,9 @@ export class MaterialGraphClient {
         return this.#get("whoami", undefined, signal);
     }
     // ── Pairings / demand ────────────────────────────────────────────────────────
-    /**
-     * THE QUESTION: "here is my whole scheme so far — what completes it?" The
-     * multi-seed form of {@link MaterialGraphClient.pairings}: lift is summed across
-     * seeds, so a companion suiting one pick ranks below one suiting several.
-     * Instead use `pairings` for a single material and `colours.palette()` when the
-     * scheme is COLOURS rather than materials. Check `unresolved` before presenting.
-     *
-     * Coordinate a palette of already-chosen materials (POST
-     * `/api/v1/pairings/coordinate`). Returns demand-lift-ranked companions with
-     * colour swatches and an annotate-only `colourFit` (never reorders in v1).
-     */
+    /** What completes a scheme already part-chosen. See {@link coordinateCall}. */
     coordinate(input, signal) {
-        return this.#post("coordinate_materials", input, signal);
+        return coordinateCall(this.#transport, input, signal);
     }
     /**
      * THE QUESTION: "how much is this material actually specified, and what gets
@@ -690,15 +701,13 @@ export class MaterialGraphClient {
     cancelRun(runId, signal) {
         return cancelRun(this.#transport, runId, signal);
     }
-    /**
-     * Derive an "option B" scheme from a succeeded compose Run along one
-     * constraint axis (POST `/api/v1/schemes/vary`). Deterministic and
-     * synchronous — the response IS the hydrated scheme (no Run envelope), stamped
-     * with axis + source provenance whose `notes` are the variation's receipts.
-     * Requires the `mg:read` scope.
-     */
+    /** Option B from a composed Run, along one axis. See {@link varySchemeCall}. */
     varyScheme(body, signal) {
-        return this.#post("vary_schemes", body, signal);
+        return varySchemeCall(this.#transport, body, signal);
+    }
+    /** Ranked candidate pools for up to 24 slots. See {@link slotPoolsCall}. */
+    slotPools(body, signal) {
+        return slotPoolsCall(this.#transport, body, signal);
     }
     /**
      * Stream ordered Run events as an async iterator (GET