@adminiumjs/add-on-contracts 0.2.1

package/dist/product-personalizer.d.ts

@@ -0,0 +1,205 @@
+/**
+ * `product-personalizer@1` (24 §5.5, added 2026-08-05 with `personalizer`) —
+ * the one contract whose implementation spans three surfaces (shopper, staff,
+ * dashboard), which is why it is a contract at all rather than a screen.
+ *
+ * Landed here with wave 4a even though its implementation ships in 4b: the
+ * registry is frozen once, before anything ships, rather than widened after a
+ * release (§1.1's sequencing note).
+ */
+import { z } from 'zod';
+import type { FileRef } from './common.js';
+export type ZoneKind = 'text-line' | 'text-block' | 'image' | 'colour';
+export type ZoneFinish = 'engraved' | 'raised' | 'printed' | 'painted';
+export interface Zone {
+    id: string;
+    name: string;
+    kind: ZoneKind;
+    shape: {
+        type: 'rect' | 'ellipse';
+        xMm: number;
+        yMm: number;
+        wMm: number;
+        hMm: number;
+    };
+    constraints: {
+        maxChars?: number;
+        fonts?: string[];
+        minSizeMm?: number;
+        maxSizeMm?: number;
+        palette?: string[];
+    };
+    finish: ZoneFinish;
+    /** Where the zone lands on each supplied angle; absent ⇒ not visible there. */
+    perAngle: Record<string, {
+        xPct: number;
+        yPct: number;
+        wPct: number;
+        hPct: number;
+        skewDeg?: number;
+    }>;
+}
+export interface Template {
+    productKey: string;
+    angles: {
+        id: string;
+        label: string;
+        fileId: string;
+    }[];
+    zones: Zone[];
+}
+export interface Personalization {
+    templateId: string;
+    values: Record<string, string>;
+    font?: string;
+    sizeMm?: number;
+    finish?: ZoneFinish;
+}
+export interface ProductRef {
+    productKey: string;
+    variant?: string;
+    quantity: number;
+}
+export interface PreviewRef {
+    fileId: string;
+    angle: string;
+    widthPx: number;
+    /** Content hash — equal values + equal angle ⇒ equal digest (determinism). */
+    digest: string;
+}
+/**
+ * An overrun carries BOTH remedies with their numbers — the UI renders them as
+ * buttons. A bare "doesn't fit" is a contract violation, not a UI choice.
+ */
+export type Verdict = {
+    zone: string;
+    ok: true;
+} | {
+    zone: string;
+    ok: false;
+    reason: string;
+    remedies: {
+        setSizeMm?: number;
+        shortenToChars?: number;
+    };
+};
+export interface ProductPersonalizer {
+    readonly key: string;
+    available(product: ProductRef): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    /** The shopper's surface. Resolves to their choices, or null if they backed out. */
+    open(product: ProductRef, initial?: Personalization): Promise<Personalization | null>;
+    /** Deterministic: same values + same angle ⇒ same image. */
+    render(p: Personalization, opts: {
+        angle: string;
+        widthPx: number;
+    }): Promise<PreviewRef>;
+    /** What goes to the machine — outlines, layered. Never drives hardware. */
+    productionFile(p: Personalization): Promise<FileRef>;
+    validate(p: Personalization, t: Template): Verdict[];
+}
+export declare const zoneSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    kind: z.ZodEnum<{
+        "text-line": "text-line";
+        "text-block": "text-block";
+        image: "image";
+        colour: "colour";
+    }>;
+    shape: z.ZodObject<{
+        type: z.ZodEnum<{
+            rect: "rect";
+            ellipse: "ellipse";
+        }>;
+        xMm: z.ZodNumber;
+        yMm: z.ZodNumber;
+        wMm: z.ZodNumber;
+        hMm: z.ZodNumber;
+    }, z.core.$strict>;
+    constraints: z.ZodObject<{
+        maxChars: z.ZodOptional<z.ZodNumber>;
+        fonts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        minSizeMm: z.ZodOptional<z.ZodNumber>;
+        maxSizeMm: z.ZodOptional<z.ZodNumber>;
+        palette: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    finish: z.ZodEnum<{
+        engraved: "engraved";
+        raised: "raised";
+        printed: "printed";
+        painted: "painted";
+    }>;
+    perAngle: z.ZodRecord<z.ZodString, z.ZodObject<{
+        xPct: z.ZodNumber;
+        yPct: z.ZodNumber;
+        wPct: z.ZodNumber;
+        hPct: z.ZodNumber;
+        skewDeg: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const templateSchema: z.ZodObject<{
+    productKey: z.ZodString;
+    angles: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        fileId: z.ZodString;
+    }, z.core.$strict>>;
+    zones: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            "text-line": "text-line";
+            "text-block": "text-block";
+            image: "image";
+            colour: "colour";
+        }>;
+        shape: z.ZodObject<{
+            type: z.ZodEnum<{
+                rect: "rect";
+                ellipse: "ellipse";
+            }>;
+            xMm: z.ZodNumber;
+            yMm: z.ZodNumber;
+            wMm: z.ZodNumber;
+            hMm: z.ZodNumber;
+        }, z.core.$strict>;
+        constraints: z.ZodObject<{
+            maxChars: z.ZodOptional<z.ZodNumber>;
+            fonts: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            minSizeMm: z.ZodOptional<z.ZodNumber>;
+            maxSizeMm: z.ZodOptional<z.ZodNumber>;
+            palette: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+        finish: z.ZodEnum<{
+            engraved: "engraved";
+            raised: "raised";
+            printed: "printed";
+            painted: "painted";
+        }>;
+        perAngle: z.ZodRecord<z.ZodString, z.ZodObject<{
+            xPct: z.ZodNumber;
+            yPct: z.ZodNumber;
+            wPct: z.ZodNumber;
+            hPct: z.ZodNumber;
+            skewDeg: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const personalizationSchema: z.ZodObject<{
+    templateId: z.ZodString;
+    values: z.ZodRecord<z.ZodString, z.ZodString>;
+    font: z.ZodOptional<z.ZodString>;
+    sizeMm: z.ZodOptional<z.ZodNumber>;
+    finish: z.ZodOptional<z.ZodEnum<{
+        engraved: "engraved";
+        raised: "raised";
+        printed: "printed";
+        painted: "painted";
+    }>>;
+}, z.core.$strict>;
+//# sourceMappingURL=product-personalizer.d.ts.map

package/dist/product-personalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-personalizer.d.ts","sourceRoot":"","sources":["../src/product-personalizer.ts"],"names":[],"mappings":"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"}

package/dist/product-personalizer.js

@@ -0,0 +1,64 @@
+/**
+ * `product-personalizer@1` (24 §5.5, added 2026-08-05 with `personalizer`) —
+ * the one contract whose implementation spans three surfaces (shopper, staff,
+ * dashboard), which is why it is a contract at all rather than a screen.
+ *
+ * Landed here with wave 4a even though its implementation ships in 4b: the
+ * registry is frozen once, before anything ships, rather than widened after a
+ * release (§1.1's sequencing note).
+ */
+import { z } from 'zod';
+export const zoneSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    kind: z.enum(['text-line', 'text-block', 'image', 'colour']),
+    shape: z
+        .object({
+        type: z.enum(['rect', 'ellipse']),
+        xMm: z.number(),
+        yMm: z.number(),
+        wMm: z.number().positive(),
+        hMm: z.number().positive(),
+    })
+        .strict(),
+    constraints: z
+        .object({
+        maxChars: z.number().int().positive().optional(),
+        fonts: z.array(z.string().min(1)).optional(),
+        minSizeMm: z.number().positive().optional(),
+        maxSizeMm: z.number().positive().optional(),
+        palette: z.array(z.string().min(1)).optional(),
+    })
+        .strict(),
+    finish: z.enum(['engraved', 'raised', 'printed', 'painted']),
+    perAngle: z.record(z.string(), z
+        .object({
+        xPct: z.number(),
+        yPct: z.number(),
+        wPct: z.number(),
+        hPct: z.number(),
+        skewDeg: z.number().optional(),
+    })
+        .strict()),
+})
+    .strict();
+export const templateSchema = z
+    .object({
+    productKey: z.string().min(1),
+    angles: z
+        .array(z.object({ id: z.string().min(1), label: z.string().min(1), fileId: z.string().min(1) }).strict())
+        .min(1),
+    zones: z.array(zoneSchema),
+})
+    .strict();
+export const personalizationSchema = z
+    .object({
+    templateId: z.string().min(1),
+    values: z.record(z.string(), z.string()),
+    font: z.string().min(1).optional(),
+    sizeMm: z.number().positive().optional(),
+    finish: z.enum(['engraved', 'raised', 'printed', 'painted']).optional(),
+})
+    .strict();
+//# sourceMappingURL=product-personalizer.js.map

package/dist/product-personalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-personalizer.js","sourceRoot":"","sources":["../src/product-personalizer.ts"],"names":[],"mappings":"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"}

package/dist/shipping-carrier.d.ts

@@ -0,0 +1,119 @@
+/**
+ * `shipping-carrier@1` (24 §5.5) — one delivery company, shaped so the second
+ * one is a copy.
+ *
+ * The claim "each shipping company is its own add-on, and the next is this repo
+ * with one file replaced" rests entirely on the conformance suite in
+ * `@adminium/add-on-contracts/testing`, which every transport runs against
+ * itself — the demo one and the real one alike.
+ */
+import { z } from 'zod';
+import type { FileRef } from './common.js';
+export interface Parcel {
+    weightKg: number;
+    lengthCm: number;
+    widthCm: number;
+    heightCm: number;
+    contents: string;
+}
+export interface Address {
+    name: string;
+    lines: string[];
+    city: string;
+    postcode: string;
+    country: string;
+}
+export interface Rate {
+    code: string;
+    service: string;
+    amount: number;
+    currency: string;
+    /** ISO date — when the carrier says it arrives. */
+    estimatedDelivery: string;
+}
+export interface OrderRef {
+    /** The host's own reference, e.g. `MP-4118`. */
+    reference: string;
+}
+export interface Shipment {
+    id: string;
+    tracking: string;
+    labelFileId: string;
+    /** ISO datetime — the collection window the carrier committed to. */
+    collectionFrom: string;
+    collectionTo: string;
+    rate: Rate;
+}
+export interface TrackEvent {
+    at: string;
+    place: string;
+    status: string;
+    description: string;
+}
+/**
+ * A carrier refusal is DATA, never a thrown string: the works needs the
+ * carrier's own message verbatim to act on it, and a rejected postcode is an
+ * ordinary outcome rather than a crash.
+ */
+export declare class CarrierError extends Error {
+    readonly code: string;
+    /** The carrier's own words, rendered in mono and quoted in the UI. */
+    readonly carrierMessage: string;
+    readonly retryable: boolean;
+    constructor(opts: {
+        code: string;
+        carrierMessage: string;
+        retryable?: boolean;
+    });
+}
+export interface ShippingCarrier {
+    readonly key: string;
+    quote(parcel: Parcel, from: Address, to: Address): Promise<Rate[]>;
+    book(rate: Rate, order: OrderRef): Promise<Shipment>;
+    /** An unknown reference returns an empty list — it never throws. */
+    track(tracking: string): Promise<TrackEvent[]>;
+    label(shipmentId: string): Promise<FileRef>;
+    cancel(shipmentId: string): Promise<void>;
+}
+export declare const parcelSchema: z.ZodObject<{
+    weightKg: z.ZodNumber;
+    lengthCm: z.ZodNumber;
+    widthCm: z.ZodNumber;
+    heightCm: z.ZodNumber;
+    contents: z.ZodString;
+}, z.core.$strict>;
+export declare const addressSchema: z.ZodObject<{
+    name: z.ZodString;
+    lines: z.ZodArray<z.ZodString>;
+    city: z.ZodString;
+    postcode: z.ZodString;
+    country: z.ZodString;
+}, z.core.$strict>;
+export declare const rateSchema: z.ZodObject<{
+    code: z.ZodString;
+    service: z.ZodString;
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+    estimatedDelivery: z.ZodString;
+}, z.core.$strict>;
+export declare const shipmentSchema: z.ZodObject<{
+    id: z.ZodString;
+    tracking: z.ZodString;
+    labelFileId: z.ZodString;
+    collectionFrom: z.ZodString;
+    collectionTo: z.ZodString;
+    rate: z.ZodObject<{
+        code: z.ZodString;
+        service: z.ZodString;
+        amount: z.ZodNumber;
+        currency: z.ZodString;
+        estimatedDelivery: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const trackEventSchema: z.ZodObject<{
+    at: z.ZodString;
+    place: z.ZodString;
+    status: z.ZodString;
+    description: z.ZodString;
+}, z.core.$strict>;
+//# sourceMappingURL=shipping-carrier.d.ts.map

package/dist/shipping-carrier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shipping-carrier.d.ts","sourceRoot":"","sources":["../src/shipping-carrier.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,MAAM;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,QAAQ;IACvB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,IAAI,EAAE;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,cAAc,EAAE,MAAM,CAAC;QACvB,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB;CAOF;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACnE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACrD,oEAAoE;IACpE,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAC/C,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED,eAAO,MAAM,YAAY;;;;;;kBAQd,CAAC;AAEZ,eAAO,MAAM,aAAa;;;;;;kBAQf,CAAC;AAEZ,eAAO,MAAM,UAAU;;;;;;kBAQZ,CAAC;AAEZ,eAAO,MAAM,cAAc;;;;;;;;;;;;;kBAShB,CAAC;AAEZ,eAAO,MAAM,gBAAgB;;;;;kBAOlB,CAAC"}

package/dist/shipping-carrier.js

@@ -0,0 +1,74 @@
+/**
+ * `shipping-carrier@1` (24 §5.5) — one delivery company, shaped so the second
+ * one is a copy.
+ *
+ * The claim "each shipping company is its own add-on, and the next is this repo
+ * with one file replaced" rests entirely on the conformance suite in
+ * `@adminium/add-on-contracts/testing`, which every transport runs against
+ * itself — the demo one and the real one alike.
+ */
+import { z } from 'zod';
+/**
+ * A carrier refusal is DATA, never a thrown string: the works needs the
+ * carrier's own message verbatim to act on it, and a rejected postcode is an
+ * ordinary outcome rather than a crash.
+ */
+export class CarrierError extends Error {
+    code;
+    /** The carrier's own words, rendered in mono and quoted in the UI. */
+    carrierMessage;
+    retryable;
+    constructor(opts) {
+        super(opts.carrierMessage);
+        this.name = 'CarrierError';
+        this.code = opts.code;
+        this.carrierMessage = opts.carrierMessage;
+        this.retryable = opts.retryable ?? true;
+    }
+}
+export const parcelSchema = z
+    .object({
+    weightKg: z.number().positive(),
+    lengthCm: z.number().positive(),
+    widthCm: z.number().positive(),
+    heightCm: z.number().positive(),
+    contents: z.string().min(1),
+})
+    .strict();
+export const addressSchema = z
+    .object({
+    name: z.string().min(1),
+    lines: z.array(z.string().min(1)).min(1),
+    city: z.string().min(1),
+    postcode: z.string().min(1),
+    country: z.string().min(1),
+})
+    .strict();
+export const rateSchema = z
+    .object({
+    code: z.string().min(1),
+    service: z.string().min(1),
+    amount: z.number().nonnegative(),
+    currency: z.string().length(3),
+    estimatedDelivery: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'estimatedDelivery must be an ISO date'),
+})
+    .strict();
+export const shipmentSchema = z
+    .object({
+    id: z.string().min(1),
+    tracking: z.string().min(1),
+    labelFileId: z.string().min(1),
+    collectionFrom: z.string().min(1),
+    collectionTo: z.string().min(1),
+    rate: rateSchema,
+})
+    .strict();
+export const trackEventSchema = z
+    .object({
+    at: z.string().min(1),
+    place: z.string().min(1),
+    status: z.string().min(1),
+    description: z.string().min(1),
+})
+    .strict();
+//# sourceMappingURL=shipping-carrier.js.map

package/dist/shipping-carrier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shipping-carrier.js","sourceRoot":"","sources":["../src/shipping-carrier.ts"],"names":[],"mappings":"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"}

package/dist/slots.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Slot registry v1 — CLOSED (24-marketplace-wave-4.md §5.4, eleven slots).
+ *
+ * A slot is a named place in a host surface, its payload, and its fill rule.
+ * The registry is closed for the same reason the widget-id vocabulary is: an
+ * open-ended extension point cannot be reviewed, translated, or kept working
+ * across host versions. Adding a slot is a spec change with a version bump on
+ * this package — never a pull request against an app.
+ *
+ * Every slot here is filled by something built in wave 4. A slot nobody fills
+ * is a guess about a future add-on, which is why an earlier draft's twelfth
+ * (`job.timeline.entries`) is absent.
+ */
+import { z } from 'zod';
+/** Which persona's surface the slot lives in. */
+export declare const SLOT_SURFACES: readonly ["customer", "staff", "admin", "both"];
+export type SlotSurface = (typeof SLOT_SURFACES)[number];
+/**
+ * `multi` renders every enabled fill ordered by `order` then by add-on key, so
+ * the order is stable and does not depend on install sequence. `single` takes
+ * the lowest `order` and records a SLOT_CONFLICT warning naming the add-on that
+ * lost — never a silent override.
+ */
+export declare const SLOT_FILLS: readonly ["multi", "single", "per-add-on"];
+export type SlotFill = (typeof SLOT_FILLS)[number];
+export interface SlotDefinition {
+    readonly id: string;
+    readonly surface: SlotSurface;
+    readonly fill: SlotFill;
+    /** What the host passes into the fill. */
+    readonly payload: string;
+    /** What the add-on renders or resolves to. */
+    readonly renders: string;
+}
+export declare const SLOT_REGISTRY: readonly [{
+    readonly id: "artwork.sources";
+    readonly surface: "customer";
+    readonly fill: "multi";
+    readonly payload: "the configured job: product, trim size mm, bleed mm, sides, quantity";
+    readonly renders: "an action tile, and a flow resolving to an ArtworkRef";
+}, {
+    readonly id: "checkout.delivery.methods";
+    readonly surface: "customer";
+    readonly fill: "multi";
+    readonly payload: "parcel estimate + destination";
+    readonly renders: "selectable rate rows";
+}, {
+    readonly id: "order.dispatch.panel";
+    readonly surface: "customer";
+    readonly fill: "single";
+    readonly payload: "the dispatch record";
+    readonly renders: "a read-only tracking view";
+}, {
+    readonly id: "order.dispatch.actions";
+    readonly surface: "staff";
+    readonly fill: "multi";
+    readonly payload: "the order + its parcel estimate";
+    readonly renders: "an action and its result panel";
+}, {
+    readonly id: "settings.add-on.panel";
+    readonly surface: "admin";
+    readonly fill: "per-add-on";
+    readonly payload: "the add-on's settings values, a patch handle, and sample records";
+    readonly renders: "a settings form, its controls and the sentence under each";
+}, {
+    readonly id: "nav.add-on.routes";
+    readonly surface: "both";
+    readonly fill: "multi";
+    readonly payload: "—";
+    readonly renders: "full-screen routes under /add-ons/<key>/*";
+}, {
+    readonly id: "product.options.personalize";
+    readonly surface: "customer";
+    readonly fill: "single";
+    readonly payload: "the product + its variant and quantity";
+    readonly renders: "a personalization surface resolving to a Personalization";
+}, {
+    readonly id: "cart.line.preview";
+    readonly surface: "customer";
+    readonly fill: "multi";
+    readonly payload: "one basket / order line";
+    readonly renders: "a thumbnail and the values in words";
+}, {
+    readonly id: "product.admin.panel";
+    readonly surface: "staff";
+    readonly fill: "multi";
+    readonly payload: "the product record";
+    readonly renders: "a setup panel (zones, constraints, sample)";
+}, {
+    readonly id: "order.line.actions";
+    readonly surface: "staff";
+    readonly fill: "multi";
+    readonly payload: "one order line";
+    readonly renders: "per-line actions and their output";
+}, {
+    readonly id: "record.editor.panel";
+    readonly surface: "admin";
+    readonly fill: "multi";
+    readonly payload: "the table name, the record, and write handles";
+    readonly renders: "a panel inside the generated dashboard's record editor";
+}];
+export type SlotId = (typeof SLOT_REGISTRY)[number]['id'];
+export declare const SLOT_IDS: readonly SlotId[];
+export declare const slotIdSchema: z.ZodEnum<{
+    "artwork.sources": "artwork.sources";
+    "checkout.delivery.methods": "checkout.delivery.methods";
+    "order.dispatch.panel": "order.dispatch.panel";
+    "order.dispatch.actions": "order.dispatch.actions";
+    "settings.add-on.panel": "settings.add-on.panel";
+    "nav.add-on.routes": "nav.add-on.routes";
+    "product.options.personalize": "product.options.personalize";
+    "cart.line.preview": "cart.line.preview";
+    "product.admin.panel": "product.admin.panel";
+    "order.line.actions": "order.line.actions";
+    "record.editor.panel": "record.editor.panel";
+}>;
+export declare function isSlotId(v: unknown): v is SlotId;
+export declare function slotDefinition(id: SlotId): SlotDefinition;
+//# sourceMappingURL=slots.d.ts.map

package/dist/slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../src/slots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,iDAAiD;AACjD,eAAO,MAAM,aAAa,iDAAkD,CAAC;AAC7E,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,4CAA6C,CAAC;AACrE,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAsFoB,CAAC;AAE/C,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;AAE1D,eAAO,MAAM,QAAQ,EAAqC,SAAS,MAAM,EAAE,CAAC;AAE5E,eAAO,MAAM,YAAY;;;;;;;;;;;;EAAuD,CAAC;AAIjF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,MAAM,CAEhD;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc,CAKzD"}