@instruments/materialgraph 0.26.0 → 0.27.1

package/fan-deck-types.d.ts

@@ -1,42 +0,0 @@
-/**
- * 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 type 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 type FanDeckFamily = {
-    family: string;
-    /** Count over the WHOLE range, computed before any truncation. */
-    count: number;
-};
-export type BrandFanDeck = {
-    /**
-     * The brand SLUGS the deck resolved to — round-trippable identifiers, not
-     * display names. The maker's name as it should be shown is on every swatch.
-     */
-    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

@@ -1,9 +0,0 @@
-/**
- * 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 {};

package/match-rejection-types.d.ts

@@ -1,43 +0,0 @@
-/**
- * "Not this" on a photo match result (MG-1859). A rejection is feedback on the
- * match ranking, recorded against the response that showed the result. It is
- * never a catalogue correction; wrong facts about a product go through
- * `createCorrection`.
- */
-export type RejectMatchResultInput = {
-    /**
-     * The surface the result was shown under - `surfaces[].surface.id` on a scene
-     * match. Omit it for a result from the run-level `results` list.
-     */
-    surfaceId?: string;
-    /** The rejected result's `variantId`, verbatim. */
-    variantId: string;
-    /** Optional free text, up to 500 characters. Stored as given. */
-    reason?: string;
-};
-/** The receipt for one rejection. A repeat of the same rejection returns the original. */
-export type MatchRejection = {
-    rejectionId: string;
-    /** The match response's `attribution.responseId`. */
-    responseId: string;
-    /** Null when the result came from the run-level list. */
-    surfaceId: string | null;
-    variantId: string;
-    /** The 1-based position the match response showed this result at, within its surface. */
-    rank: number;
-    reason: string | null;
-    /** ISO-8601. */
-    rejectedAt: string;
-};
-/** One match response and every rejection recorded against it. */
-export type MatchRejectionList = {
-    responseId: string;
-    /** `stream` for a scene match, `buffered` for the single-image JSON response. */
-    lane: "buffered" | "stream";
-    /** ISO-8601 time the match response was issued. */
-    issuedAt: string;
-    /** Ranked results the response showed, across every surface - a rejection rate's denominator. */
-    resultCount: number;
-    /** Oldest first. Empty means nothing was rejected. */
-    rejections: MatchRejection[];
-};

package/match-rejection-types.js

@@ -1,7 +0,0 @@
-/**
- * "Not this" on a photo match result (MG-1859). A rejection is feedback on the
- * match ranking, recorded against the response that showed the result. It is
- * never a catalogue correction; wrong facts about a product go through
- * `createCorrection`.
- */
-export {};

package/palette-completion-types.d.ts

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

package/palette-completion-types.js

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

package/render-assets-types.d.ts

@@ -1,65 +0,0 @@
-import type { VariantId } from "./identifiers.js";
-export type RenderAssetChannelRole = "base-color" | "normal" | "roughness" | "metalness" | "height" | "ambient-occlusion";
-export type RenderAssetSourceBasis = "catalog_feed" | "declared" | "derived";
-export type RenderAssetUnavailableReason = "no_accepted_appearance" | "pending" | "withheld" | "rejected" | "superseded" | "variant_inactive" | "delivery_unverified" | "integrity_error";
-export type RenderAssetFreshness = {
-    revision: string;
-    updatedAt: string | null;
-    checkedAt: string | null;
-};
-export type RenderAssetChannel = {
-    role: RenderAssetChannelRole;
-    url: string;
-    sha256: string;
-    byteSize: number;
-    mimeType: "image/png";
-    width: number;
-    height: number;
-    bitDepth: 8 | 16;
-    colorSpace: "srgb" | "linear";
-};
-export type MaterialRenderAssetsAvailable = {
-    schemaVersion: "pbr-render-assets/v1";
-    variantId: VariantId;
-    status: "available";
-    setId: string;
-    state: "accepted";
-    sourceBasis: "derived";
-    fidelity: "unassessed";
-    acceptance: {
-        id: string;
-        verificationDecisionId: string;
-        acceptedAt: string;
-        checkVersion: string;
-        qa: {
-            status: "passed";
-            checkCount: number;
-        };
-        checkCount: number;
-    };
-    physicalRepeat: {
-        uMm: number;
-        vMm: number;
-        basis: "declared" | "measured";
-    };
-    tiling: {
-        u: boolean;
-        v: boolean;
-    };
-    normalConvention: "opengl" | "directx";
-    heightAmplitudeMm?: number;
-    channels: RenderAssetChannel[];
-    supersedesSetIds: string[];
-    freshness: RenderAssetFreshness;
-};
-export type MaterialRenderAssetsUnavailable = {
-    schemaVersion: "pbr-render-assets/v1";
-    variantId: VariantId;
-    status: "unavailable";
-    setId: string | null;
-    state: "pending" | "withheld" | "rejected" | "superseded" | "accepted" | null;
-    sourceBasis: RenderAssetSourceBasis | null;
-    reasonCodes: RenderAssetUnavailableReason[];
-    freshness: RenderAssetFreshness;
-};
-export type MaterialRenderAssets = MaterialRenderAssetsAvailable | MaterialRenderAssetsUnavailable;

package/render-assets-types.js

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

package/search-collapse-types.d.ts

@@ -1,69 +0,0 @@
-/**
- * The product-collapsed view of a search result — what `collapse: "product"`
- * hands back beside each card. Kept out of `types.ts` for the same reason
- * `palette-search-types.ts` and `by-colour-types.ts` are: that file is at its
- * source-size ceiling, and this is a self-contained corner of the contract.
- *
- * READ THIS FIRST, because the default is the opposite of what "duplicates"
- * intuition suggests. MaterialGraph search is VARIANT-based: without `collapse`,
- * every matching variant comes back as its own result, and that is correct —
- * twelve SKUs of one tile are twelve separately orderable products, not twelve
- * copies of one. Product grouping is an optional VIEW over that, not a fix for
- * it.
- *
- * When you do ask for the view, the product arrives CARRYING its variants
- * (`SearchResultItem.variants`) rather than a bare count, so a colourway strip
- * renders from the same response as the card. That array is CAPPED at 12, while
- * `SearchResultItem.siblingCount` stays the complete tally — so a truncated list
- * is decidable from the response alone: `(siblingCount ?? 0) + 1 >
- * variants.length`. A full-length array is never on its own evidence that the
- * product holds no further variants.
- */
-import type { VariantId } from "./identifiers.js";
-import type { SearchResultSignals } from "./types.js";
-/**
- * One variant of a product-collapsed result.
- *
- * A slim shape, deliberately: the fields a colourway strip renders, projected
- * from the row the engine already held in memory, so the array costs no extra
- * query. It is NOT a nested search result — no `attributes`, `palette`,
- * `verdict` or `productType` — because those come from per-result reads the
- * engine issues for the card only. Fetch the variant by `variantId` when you
- * need its full record.
- */
-export type CollapsedVariant = {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    /** The variant's own label; for paint, the colourway name. Null when unnamed. */
-    variantName: string | null;
-    /** The variant's coarse colour family. */
-    color: string | null;
-    /**
-     * `#rrggbb` dominant colour EXTRACTED FROM the variant's image — a visual
-     * likeness, never a manufacturer-declared colour specification. ABSENT means
-     * no palette is on record: unknown, never "this variant has no colour".
-     */
-    hex?: string;
-    imageUrl: string | null;
-    /**
-     * The variant's Material Bank SKU, on the same contract as the result item's:
-     * ABSENT means no MB identity is on record, never that it cannot be ordered.
-     */
-    materialBankId?: string;
-    /** This variant's own mode-primary score — the value the array is ordered by. */
-    score: number;
-};
-/**
- * One member of a collapsed result's `SearchResultItem.anatomy` — the
- * EXPLAIN-only readout of the same grouping {@link CollapsedVariant} publishes.
- * Where a collapsed variant is what a surface renders, this is what an operator
- * inspects: it carries the per-arm `signals` that made the variant a candidate.
- */
-export type SearchAnatomyMember = {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    variantName: string | null;
-    color: string | null;
-    score: number;
-    signals: SearchResultSignals;
-};

package/search-collapse-types.js

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

package/search-mood-types.d.ts

@@ -1,6 +0,0 @@
-/** What a standard search did, and did not, recognize as a governed mood. */
-export type MoodInterpretation = {
-    query: string | null;
-    moodId: string | null;
-    supersededMoodId: string | null;
-};

package/search-mood-types.js

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

package/search-window-types.d.ts

@@ -1,25 +0,0 @@
-/** The bounded candidate window that produced a search page. */
-export type SearchWindowReceipt = {
-    /** Versioned budget profile; interpret the remaining fields under this version. */
-    profile: "interactive-r1" | (string & {});
-    /** Candidate depth used by the final retrieval. */
-    candidateTier: number;
-    /** Candidate retrieval count; `searchMaterials` reports exactly one selected retrieval. */
-    retrievalRounds: number;
-    /** Candidate-retrieval wall time only, in milliseconds. */
-    retrievalMs: number;
-    /** True when the serving source proved there were no more candidates. */
-    exhaustive: boolean;
-    /**
-     * Candidate attrition through the selected retrieval source. Absent when the
-     * response path did not perform ordinary retrieval (for example typeahead).
-     */
-    candidateCounts?: {
-        /** Provider-returned matches before bounded selection; null for SQL/exact arms. */
-        rawProviderMatches: number | null;
-        /** Matches selected from that provider response; null for SQL/exact arms. */
-        selectedMatches: number | null;
-        /** Canonical candidates returned by the selected retrieval arm. */
-        hydratedCanonicalCandidates: number;
-    };
-};

package/search-window-types.js

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