/*! Pixonaut SDK type declarations. Licensed under the MIT licence: see LICENSE-TYPES. */
import { paths } from './schema.js';

/** What `POST /v1/proofs` answers with its 201, as the API's reference
 *  declares it. Derived rather than restated, so a field the route adds or
 *  renames reaches every caller of `approve()` without a hand edit. */
export declare type ApproveResult = paths["/v1/proofs"]["post"]["responses"][201]["content"]["application/json"];

/** Derive the customer form schema from the artwork's groups. A template is
 *  ONE artwork (ADR 018), so each of its groups becomes one step. */
export declare function buildFormSchema(template: FormSchemaSource): FormSchema_2;

/**
 * The default picker: a labelled `<select>` over the consumer's own photos.
 *
 * Thin on purpose, and the same shape as `buildSizePicker` so a storefront
 * meets one control idiom: a host that wants its own swatches with colour
 * names beside them ignores this and reads `choices()`.
 *
 * No entry is ever `disabled`. The size picker disables what the rule refuses;
 * there is no rule here, so every photo the consumer listed is selectable — and
 * one whose rect cannot be drawn simply composites nothing rather than being
 * taken off the menu, so the consumer can see their own misconfiguration.
 */
export declare function buildMockupPicker(choices: readonly MockupChoiceEntry[], msg: MockupMessages, onPick: (index: number) => void, 
/** hands the drawn `<select>` back, so a programmatic pick can move it */
mirror?: (el: MockupMirror) => void): HTMLElement;

/** A template color: RGB, CMYK, or a spot color with an RGB/CMYK fallback. */
declare interface ColorValue {
    rgb?: [number, number, number];
    cmyk?: [number, number, number, number];
    spot?: {
        fallback: ColorValue;
    };
}

/** What `commit()` resolves: the committed design's id. */
export declare type CommitResult = paths["/v1/designs"]["post"]["responses"][201]["content"]["application/json"];

/** A correction link's token (#1084), which a store's server hands out for
 *  one design (`POST /v1/designs/{id}/correction-links`) for a short while.
 *  It reaches that design and nothing else the tenant holds, from the
 *  store's own pages. */
declare interface CorrectionLinkCredential {
    correctionLink: string;
    publishableKey?: never;
    shareLink?: never;
    studioSession?: never;
}

/** Mounted by a store on a design its customer made, to correct it: the
 *  correction link and the design's id. The design opens as it is now, at the
 *  size it was bought at, so there is no size menu and no placement to name.
 *  `approve()` resolves a proof of the correction and writes nothing; the
 *  store's server makes it the design's next revision with
 *  `PATCH /v1/designs/{id}` and the proof's token. `commit()` is refused. */
declare type CorrectionLinkMount = MountOptionsBase & CorrectionLinkCredential & {
    /** The design's id. */
    design: string;
    templateId?: never;
    template?: never;
    printSizes?: never;
    selectedPrintSizeIndex?: never;
    blankId?: never;
    placementId?: never;
};

export declare const DEFAULT_MESSAGES: SdkMessages;

export declare interface DesignerState {
    templateId: string;
    values: Record<string, Record<string, unknown>>;
    /** The print size the customer chose, when the host offers a size menu
     *  (ADR 051). It is NOT in `values` — that is keyed by layer id and reaches a
     *  Rust model with `deny_unknown_fields` — so without it here a host
     *  persisting `onChange` state would lose the size and have no way to
     *  restore it. Absent when there is no menu, or when the selected entry is
     *  one the rule refuses. */
    printSize?: {
        widthMm: number;
        heightMm: number;
    };
    /** The step the form shows, when it lays out as steps (ADR 196). Absent on
     *  a page, so a page's state is what it always was. */
    step?: FormStepPosition;
}

/** Constraints attached to a form field / editable layer prop. */
declare interface FieldConstraints {
    maxLines?: number;
    maxLength?: number;
    min?: number;
    max?: number;
    step?: number;
    oneOf?: string[];
    /** image `src` only: may the customer upload their own file? Independent of
     *  `oneOf`, which lists the presets offered (ADR 016). */
    allowUpload?: boolean;
    /** The offered palette: its NAME in the resolved document a canvas or the
     *  SDK draws, its id only in an authored one (#525). */
    palette?: string;
    /** A colour of the customer's own is offered, alone or beside `palette`
     *  (ADR 114, ADR 180). */
    anyColor?: true;
    options?: Array<string | {
        value: string;
        label?: string;
    }>;
    [key: string]: unknown;
}

/** `field`'s heading: its authored label, or the message for its prop while
 *  the label is blank or the prop's own key. A prop the form has no word for
 *  keeps the label it came with. */
export declare function fieldLabel(field: Pick<FormField_2, "prop" | "label">, msg: (key: FieldWordKey) => string): string;

/** A message that names an unlabelled field. */
export declare type FieldWordKey = (typeof WORD_KEY_BY_PROP)[keyof typeof WORD_KEY_BY_PROP];

/** What a host styles in fill mode. The defaults leave the stage and the form
 *  unpainted and give the form the width it asks for embedded. */
export declare const FILL_PROPERTIES: {
    /** The stage behind the preview. */
    readonly stageBackground: {
        readonly name: "--pixonaut-stage-background";
        readonly fallback: "transparent";
    };
    /** Space kept clear around the preview on a desktop's stage, as CSS
     *  `padding`: a host that draws something of its own over the stage
     *  reserves its room here, so the preview is fitted beside it rather than
     *  under it. A phone's stage is a band above the form, padded by
     *  `PHONE_STAGE_PADDING`. */
    readonly stagePadding: {
        readonly name: "--pixonaut-stage-padding";
        readonly fallback: "24px";
    };
    /** The form column's width beside the stage. */
    readonly formWidth: {
        readonly name: "--pixonaut-form-width";
        readonly fallback: "260px";
    };
    /** The form column's background. */
    readonly formBackground: {
        readonly name: "--pixonaut-form-background";
        readonly fallback: "transparent";
    };
};

/** A custom property a host may set on its element, and the value used when
 *  it sets none. */
export declare interface FillProperty {
    name: `--pixonaut-${string}`;
    fallback: string;
}

/** One face of a family: the weight it draws and its TTF's sha256. */
declare interface FontFaceRef {
    weight: number;
    hash: string;
}

/** Families by name, each with its faces: what a document is resolved
 *  against (the tenant's rows, or a version's snapshot) and what the core
 *  reads under `fonts`. */
declare type FontSource = Readonly<Record<string, readonly FontFaceRef[]>>;

/** Every widget hint a field can carry: the host renders one control per
 *  type. A consumer that draws each (the builder's "renders as" preview) keys
 *  a record on `FormFieldType`, so a type added here fails to compile there
 *  until it is drawn. */
declare const FORM_FIELD_TYPES: readonly ["text", "select", "number", "color", "image", "percent", "crop"];

/** How the customer form lays out its steps (ADR 196): every step on one
 *  page, or one step at a time.
 *
 *  A template's author may choose one as `form.layout`, and the form schema
 *  carries that choice as `layout` so a headless host sees it too. The SDK's
 *  mount option `layout` outranks it, and with neither the form is a page —
 *  which is what every embed showed before the choice existed.
 *
 *  A zero-dependency leaf for `artwork-step-label.ts`'s reason: the SDK reads
 *  it, and importing zod would pull it into the widget. */
declare const FORM_LAYOUTS: readonly ["page", "steps"];

/** replace {name} tokens with vars[name]; unknown tokens are left as-is */
export declare function formatMessage(template: string, vars?: Record<string, string>): string;

/** A generated form field descriptor. `layerId` is the write key the widget
 *  sets values through, and what distinguishes two member layers that expose
 *  the same prop.
 *
 *  An `image` field's `prop` also says how a chosen picture is written:
 *  `pictureValueOf(prop, id)` (`asset-ids.ts`) — the bare id for an image's
 *  `src` and the artwork's `imageAssetId`, `{imageAssetId}` for a shape's
 *  picture `fill` — and its `default` is the prop's value in that same
 *  spelling, read back with `pictureIdOf`.
 *
 *  Generic in the constraints type, which is not ceremony: this package cannot
 *  import canvas-kit's `FieldConstraints` (that is the dependency cycle), but
 *  the SDK's field renderers read `oneOf`, `maxLines`, `min`, `max`, `step`,
 *  `maxLength` and `palette` off it by name. A bare `Record<string, unknown>`
 *  would make every one of those `unknown`. So the api takes the default and
 *  the SDK re-exports this instantiated with its own constraint type — one
 *  declaration, two typings, no cycle. */
declare interface FormField<C = Record<string, unknown>> {
    layerId: string;
    prop: string;
    type: FormFieldType;
    label: string;
    /** The author's help text, shown under the control as text (ADR 192);
     *  absent when they wrote none. */
    description?: string;
    /** What the control offers. A `fontWeight` field's values are numbers, and
     *  its `faces` maps each font the customer may pick to the weights it
     *  offers (see `offeredWeightConstraints`). */
    constraints: C;
    default: unknown;
    /** The fit the customer must have chosen for this field to apply — a
     *  crop's `cover`, a tile size's `tile` — on a site whose fit the customer
     *  chooses (#805). A form shows the field only while the site's fit is
     *  that one. Absent where the fit is the author's alone, so the field
     *  always applies. */
    requiresFit?: PictureFitValue;
}

/** A generated form field descriptor. */
declare type FormField_2 = FormField<FieldConstraints>;

declare type FormFieldType = (typeof FORM_FIELD_TYPES)[number];

declare type FormLayout = (typeof FORM_LAYOUTS)[number];

/** The generated form: its steps, and its author's layout when they chose
 *  one (ADR 196). */
declare type FormSchema = FormSchema_2<FieldConstraints>;

/** The customer form: its steps, and the layout its author chose, when they
 *  chose one (ADR 196). `layout` is absent rather than defaulted, so a
 *  template that never chose serves the schema it always did. */
declare interface FormSchema_2<C = Record<string, unknown>> {
    steps: FormStep<C>[];
    layout?: FormLayout;
}

/** A group of layers forming one customer-facing form step. `layerIds` is
 *  optional for the same reason `layers` is below: the SDK derives from an
 *  integrator's in-memory template that no schema gates, and a group missing
 *  its members should yield a step with no fields rather than throw "not
 *  iterable" out of the widget's mount. */
declare interface FormSchemaGroup {
    id: string;
    label: string;
    order: number;
    layerIds?: string[];
}

/** What the derivation reads off a layer — deliberately narrower than any
 *  caller's model. The api passes its `ValidatedDoc`, the SDK a canvas-kit
 *  `LayerSpec`, and this package can see neither (canvas-kit depends on it,
 *  not the reverse). Declaring what is actually read means a change to either
 *  caller's model that breaks the derivation fails at the call site — which
 *  only holds if both call sites assign WITHOUT a cast, so the shapes here are
 *  the widest the derivation can honestly accept rather than the narrowest
 *  that would typecheck against one caller.
 *
 *  `transform` maps to `unknown` rather than to an axis type, and the body
 *  narrows before reading. That is not laziness: canvas-kit's `LayerTransform`
 *  declares `[key: string]: unknown` (it holds `xMm`/`yMm`/`rotationDeg`
 *  numbers and a `value` object beside the four axis flags), and an index
 *  signature of `unknown` is assignable to no narrower one. Any tighter
 *  declaration here would force the SDK's call site to cast — and a cast is
 *  exactly what this type exists to avoid, since it would swallow the next
 *  change to either caller's model instead of failing on it. */
declare interface FormSchemaLayer {
    id: string;
    type?: string;
    props?: Record<string, FormSchemaProp | undefined>;
    /** Beside `props` rather than in it, because it belongs to no one layer
     *  kind (#427); read through `LAYER_LEVEL_PROPS`. */
    opacity?: FormSchemaProp;
    transform?: Record<string, unknown>;
    /** `false` for a guide layer, which offers nothing (ADR 183). */
    print?: boolean;
    /** `true` for a locked layer, which offers no transform axis and no crop
     *  (ADR 184). */
    locked?: boolean;
}

/** What the derivation reads off one editable prop. Mirrors the api's
 *  `LayerProp` and canvas-kit's, both of which satisfy it structurally. */
declare interface FormSchemaProp {
    editable?: boolean;
    label?: string;
    /** Help text for the customer (ADR 192). `unknown`, because the SDK derives
     *  from an in-memory template no schema gates: only text is carried. */
    description?: unknown;
    constraints?: Record<string, unknown>;
    value?: unknown;
    [key: string]: unknown;
}

/** The minimum an artwork must expose to derive a form from it. `layers` is
 *  optional because the api's `ValidatedDoc` declares it so, and the body
 *  already guards it — encoding the optionality in the body while denying it
 *  in the signature is what would force a cast. */
declare interface FormSchemaSource {
    layers?: FormSchemaLayer[];
    groups?: FormSchemaGroup[];
    /** The artwork's own background (ADR 038): its colour, or its picture —
     *  both props a customer may be offered. Typed the same way
     *  `FormSchemaLayer.props` is, and for the same reason: both callers must be
     *  able to assign their own document WITHOUT a cast, or this type stops
     *  catching the day their model drifts from what the derivation reads. */
    background?: {
        /** The discriminant a TEMPLATE carries since ADR 046. Optional because a
         *  RESOLVED document reaches this type too and deliberately has none — it
         *  freezes into the design's revisions (`design_revisions.doc_json`) and
         *  must keep parsing as approved. The index signature below swallowed this
         *  field when it arrived, which is exactly the drift the comment above
         *  promises this type catches, so it is named explicitly rather than left
         *  to the catch-all. */
        kind?: "color" | "image";
        color?: FormSchemaProp;
        /** The image arm's picture: a prop on a template, offered as an image
         *  layer's `src` is; a bare id on a resolved document, which offers
         *  nothing. `unknown`, and narrowed in the body, because the api's
         *  `ValidatedDoc` spans both. */
        imageAssetId?: unknown;
        /** The image arm's crop (ADR 181): a prop on a template; on a resolved
         *  document a bare crop, which offers nothing. `unknown` for the reason
         *  `imageAssetId` is. */
        crop?: unknown;
        [key: string]: unknown;
    };
    /** The artwork's die-cut (#183, ADR 047), the artwork's second editable
     *  value. Its `constraints.oneOf` is the offered set, as shape ids. */
    shape?: FormSchemaProp;
    /** How the author laid the form out (ADR 196). `unknown` inside, because
     *  the SDK derives from an in-memory template no schema gates: a value that
     *  is not a layout is not carried. */
    form?: {
        layout?: unknown;
    };
    /** The families a resolved document may draw, with their faces (ADR 219
     *  §6). `unknown`, as the SDK's in-memory template is ungated: anything
     *  but a map of families offers none. */
    fonts?: unknown;
}

/** A generated form step, derived from one of the artwork's groups. No step
 *  carries a surface id: the surface it once named is gone, and a two-sided
 *  product is now two templates (ADR 018). */
declare interface FormStep<C = Record<string, unknown>> {
    index: number;
    groupId: string;
    label: string;
    layerIds: string[];
    fields: FormField<C>[];
    /** The members a customer may place: one entry per layer with at least one
     *  editable axis, in `layerIds` order. */
    transforms: FormStepTransform[];
}

/** One step a form laid out as steps shows: its group, and the name its
 *  heading shows. */
export declare interface FormStepName {
    groupId: string;
    label: string;
}

/** Where a form laid out as steps stands: the step it shows, as an index
 *  into the steps it shows (a step that offers nothing is not one of them),
 *  how many those are, the shown step's group, and every shown step in
 *  order, so a host can draw its own stepper beside the form's. */
export declare interface FormStepPosition {
    index: number;
    count: number;
    groupId: string;
    steps: FormStepName[];
}

/** One member layer's editable transform axes, as its step offers them.
 *
 *  Per layer rather than merged across the group, because an axis moves the
 *  layer it belongs to and a merged record cannot say which layer that is
 *  (#390).
 *
 *  The SDK reads an entry only for its existence and its `layerId`: whether a
 *  place control exists and which layer it selects. The controls themselves
 *  are drawn from the layer's own spec (`panel.ts`, the canvas gestures), and
 *  named by the `translate` axis's `label` when the author gave one. The
 *  axes in `transform`, each with the author's `label` and `description`
 *  (ADR 192), are for headless hosts that render their own controls. */
declare interface FormStepTransform {
    layerId: string;
    transform: Record<string, unknown>;
}

/** A group of layers forming one customer-facing form step. */
declare interface GroupSpec {
    id: string;
    label: string;
    order: number;
    layerIds: string[];
}

/** An improvement that came back. */
export declare interface Improved {
    /** The improved picture's asset id. */
    assetId: string;
    /** Whether it was put on the site: false when the site no longer held the
     *  upload it improves, because the customer chose another picture while
     *  it ran. The improved picture is then left unused. */
    applied: boolean;
}

/** The nine points a layer is anchored by. The name means BOTH reference
 *  points at once: the layer's own `top-right` sits against the reference's
 *  `top-right`, coinciding at offset `0,0` (ADR 024). */
declare type LayerAnchor = "top-left" | "top-center" | "top-right" | "center-left" | "center" | "center-right" | "bottom-left" | "bottom-center" | "bottom-right";

/** An editable property descriptor on a layer (label/constraints/value). */
declare interface LayerProp {
    editable?: boolean;
    label?: string;
    constraints?: FieldConstraints;
    value?: unknown;
    [key: string]: unknown;
}

/** A single layer of a template/resolved doc (ADR 018: one artwork).
 *
 *  The placement fields are DECLARED rather than left to the index signature
 *  below, and that is not tidiness. They used to be `sizeMm`, and when ADR 024
 *  replaced it this interface still typechecked clean against a percentage
 *  layer — the index signature admitted the new fields and the old ones read as
 *  `unknown` rather than as missing, so `spec.sizeMm.w` compiled and threw at
 *  runtime, and `spec?.sizeMm ?? {w:0,h:0}` silently rendered a zero-size
 *  layer. Declaring them is what makes the next such change a compile error.
 *
 *  A RESOLVED doc carries `sizeMm` and flat transform millimetres instead. That
 *  half is `ResolvedLayerSpec` below rather than more optional fields here:
 *  one interface describing both shapes is what let `spec.sizeMm.w` compile
 *  against a percentage layer in the first place, and widening this one to
 *  cover the resolved doc too would rebuild exactly that hazard. */
declare interface LayerSpec {
    id: string;
    type?: string;
    z?: number;
    transform: LayerTransform;
    /** One of the nine anchors (`ANCHORS` in `@pixonaut/schema/src/layer-box`).
     *  Typed as the union rather than `string` so a misspelling is caught here
     *  and not by a fallback at render. */
    anchor: LayerAnchor;
    /** Another layer's id, when the layer is anchored to that layer's declared
     *  box rather than to the plate. A MISSING target falls back to the plate at
     *  render rather than failing (ADR 024). */
    anchorTo?: string;
    /** Fractions of the reference, always measured toward its centre. */
    offsetFrac: {
        x: number;
        y: number;
    };
    /** The layer's box, as fractions of the reference's width and height. */
    wFrac: number;
    hFrac: number;
    props?: Record<string, LayerProp | undefined>;
    /** resolved-doc only: the image layer's asset id (ADR 016). */
    kind?: {
        src?: unknown;
    };
    /** The layer's own backdrop (ADR 033), a sibling of `props`. Declared rather
     *  than left to the index signature for the reason the header gives: nothing
     *  here reads it — `buildGestureDoc`'s `structuredClone` carries it through
     *  untouched, which is what ADR 033 relies on — but an undeclared field is
     *  exactly the state `sizeMm` was in when it read as `unknown` instead of as
     *  missing. `unknown` rather than the schema's `LayerMat`: that union lives
     *  in the zod schema module, and importing it would land zod in the SDK's
     *  browser bundle for a field this package never inspects — the same reason
     *  the imports in `doc/index.ts` reach for zod-free leaf modules by path. */
    mat?: unknown;
    /** The layer's opacity (#427), a sibling of `props` like `mat`: a prop an
     *  author may offer, which the customer form reads beside `props`. */
    opacity?: LayerProp;
    [key: string]: unknown;
}

/** A layer transform. Template layers carry the current values under `value`
 *  plus per-axis editability flags; a resolved (author) doc carries the flat
 *  numeric fields directly. Both shapes flow through here.
 *
 *  `value` no longer carries a position: a layer is placed by `anchor` +
 *  `offsetFrac` on the LAYER (ADR 024), and rotation stays here because a layer
 *  is anchored by its unrotated box. The flat `xMm`/`yMm` below survive because
 *  they are the RESOLVED doc's, which is millimetres and stays so. */
declare interface LayerTransform {
    value: {
        rotationDeg: number;
        scale: number;
    };
    translate?: TransformAxis;
    rotate?: TransformAxis;
    scale?: TransformAxis;
    resize?: TransformAxis;
    xMm?: number;
    yMm?: number;
    rotationDeg?: number;
    [key: string]: unknown;
}

/**
 * The consumer's menu with the rule's verdict attached to each entry.
 *
 * MARKS, never filters. A size the consumer put in its own menu that comes
 * back `wrong_ratio` is a misconfiguration on their side — they have paired an
 * artwork with a size it cannot print at — and silently dropping the option
 * means they never find out. This is the stance the validation endpoint
 * already takes by answering `200 {legal: false, reason}` rather than a 4xx.
 *
 * Order and labels are passed through untouched, for the reason on
 * {@link PrintSizeOption}.
 */
export declare function markPrintSizes(template: SizeConstrainedTemplate, options: readonly PrintSizeOption[], selectedIndex: number): PrintSizeChoice[];

/** One entry with its selection state. There is no `MockupChoice` carrying a
 *  verdict, for the reason in the module header. */
export declare interface MockupChoiceEntry extends MockupOption {
    selected: boolean;
}

/** Message keys this control renders, so the host's overrides reach it. One
 *  key where the size picker needs three: nothing here is ever refused, so
 *  there is no suffix vocabulary to translate. */
declare type MockupMessages = (key: "mockup.legend") => string;

/** The live `<select>` the default picker drew, so a programmatic `select()`
 *  moves it too — without this the widget shows one colourway while
 *  `chosen()` composites another. */
declare type MockupMirror = {
    value: string;
} | null;

/** One entry in the consumer's own colourway menu.
 *
 *  The consumer owns ALL of this: which photos exist, what they are called,
 *  and what order they appear in. Pixonaut never learns that a colourway
 *  exists — a storefront that sells a green tee passes the green photo, and
 *  nothing here records that "green" was a thing (ADR 027). */
export declare interface MockupOption {
    /** Fetched by the CUSTOMER'S browser, never by Pixonaut's server. That is
     *  what keeps this field free of SSRF, and it is why the composite is
     *  client-side rather than a server-rendered PNG (ADR 027). */
    url: string;
    /** rendered verbatim — the SDK never composes or translates this */
    label: string;
    /** Travels with the url rather than being inherited from a blank: the
     *  browser has no blank to read one from, and a rect measured against one
     *  photo is meaningless against another. */
    placementRectPx: RectPx;
    /** The size of the photo the rect is measured in, when that is not the size
     *  of the image the url serves — a downscaled preview of a larger original,
     *  say. Absent: the rect is in the loaded image's own pixels, as before. */
    photoSizePx?: {
        w: number;
        h: number;
    };
    /** How strongly the photo's light and shade carry onto the design shown on
     *  it, from 0 (flat) to 1. Absent means the default the stored blank uses
     *  too. */
    shadingStrength?: number;
    /** How the design wraps round the product in this photo — a mug or a
     *  bottle — as `{ kind: "cylinder", curvature, edgeFalloff? }`, curvature
     *  in (0, 1]. Absent or null draws the design flat, as an author's mockup
     *  without a wrap. */
    warp?: MockupWarp | null;
    /** How far the photo's folds move the design shown on it — a t-shirt or a
     *  bag — in (0, 1]. Absent or null leaves the design where it is, as an
     *  author's mockup without it. A value outside that range (0 included) is
     *  read as none: the entry is still drawn, undisplaced, as Pixonaut's own
     *  mockup image draws it, and the console says so once. */
    displacementStrength?: number | null;
}

/** A mockup's wrap, as stored on `BlankMockup.warp` and as a storefront
 *  passes it. */
export declare interface MockupWarp {
    kind: typeof WARP_KIND_CYLINDER;
    /** in (WARP_CURVATURE_MIN, WARP_CURVATURE_MAX] */
    curvature: number;
    /** in [EDGE_FALLOFF_MIN, EDGE_FALLOFF_MAX]; absent is DEFAULT_EDGE_FALLOFF */
    edgeFalloff?: number;
}

/** Mount the preview and the form into one element (a selector or the
 *  element), replacing its content. */
export declare function mount(target: MountTarget, opts: MountOptions): Promise<PixonautDesigner>;

/** Mount the preview into `previewTarget` and the form, with its pickers,
 *  into `formTarget`, replacing each one's content. Both are required, and
 *  must be two elements, neither inside the other. `fill` is not accepted:
 *  the host sizes both elements. */
export declare function mount(opts: SplitMountOptions): Promise<PixonautDesigner>;

/** The one credential a mount holds. Both, or neither, does not compile: the
 *  api would have to guess which of two credentials the designer acts as. */
export declare type MountCredential = {
    /** A publishable key, for a storefront that embeds the designer. */
    publishableKey: string;
    shareLink?: never;
    studioSession?: never;
    correctionLink?: never;
} | {
    /** A designer share link's token (#557), for a page hosted on the
     *  link's own address. It reaches the one template the link was made
     *  for, by `templateId`, and nothing else the tenant holds. */
    shareLink: string;
    publishableKey?: never;
    studioSession?: never;
    correctionLink?: never;
};

export declare type MountOptions = (MountOptionsBase & MountCredential & MountPlacement & {
    design?: never;
}) | StoredDesignMount | CorrectionLinkMount;

/** Every option but the credential. */
declare interface MountOptionsBase {
    templateId?: string;
    /** mount an in-memory template (builder/preview mode) instead of
     *  fetching by templateId; approve() requires a saved templateId */
    template?: TemplateDoc;
    /** The geometry of each shape id an in-memory `template` offers, so
     *  a customer's pick of one previews and validates (#402). The fetch path
     *  takes it from the template route instead; without it here, a pick is
     *  refused locally as `unresolved_shape`. */
    offeredShapes?: ShapeSource;
    /** The tenant's default bleed and safe area for an in-memory `template`,
     *  which it prints with when no placement is named. The fetch path takes
     *  them from the template route instead; without them here, the designer
     *  judges with the product's default margins. */
    printMargins?: PrintMargins;
    /** The shape id of the die the author chose for an in-memory `template`,
     *  which the die picker preselects (#402). Its die arrives resolved to
     *  geometry, so the host that holds the authored reference says which row
     *  it was; the fetch path takes it from the template route instead. */
    dieShapeId?: string;
    /** The shape id each offering shape layer of an in-memory `template`
     *  starts on, by layer id, which its picker preselects (ADR 187): the
     *  layer's outline arrives resolved too. The fetch path takes it from the
     *  template route instead. */
    layerShapeIds?: Readonly<Record<string, string>>;
    apiBase?: string;
    /** Where a template's font files are fetched (`<fontBase>/f/<hash>.ttf`,
     *  public and keyless), when that is not `apiBase`: for a host mounting
     *  an in-memory `template` with no `apiBase` of its own. Omitted, they
     *  are fetched under `apiBase`. */
    fontBase?: string;
    /** Read asset bytes through the HOST instead of the key-bearing client.
     *
     *  Called with canvas-kit's `/v1/assets/<id>/content` path and nothing else:
     *  approve, commit, sessions and validate keep going through `apiBase` +
     *  the mount's credential regardless. It exists for a host whose credential this
     *  client cannot attach — e.g. studio, which mounts a preview with an empty
     *  key and serves asset bytes over its own cookie-authed proxy. Omitted,
     *  the built-in client answers asset reads exactly as before. */
    fetchAsset?: (path: string) => Promise<Response>;
    /** The URL of the wasm glue (`pixonaut_wasm.js`); its binary
     *  (`pixonaut_wasm_bg.wasm`) is fetched from beside it, under the same
     *  query. Omitted, the pair is looked for beside the SDK's own script,
     *  keeping the script's query (`?ver=1.4.0`). Pass it when the pair is
     *  served from somewhere else (another host, a CDN), or when a bundler
     *  re-bundles the SDK, which moves the script away from the pair: copy
     *  both files to your public assets and name the glue here. */
    wasmUrl?: string;
    previewDpi?: number;
    /** cap on the preview raster's longest edge; keeps big products cheap
     *  to render in the browser (default 1100, interactive gestures 75%) */
    previewMaxEdgePx?: number;
    /** click a rendered layer on the canvas to select it (default true) */
    selectOnClick?: boolean;
    /** `false` turns off the template's snap targets for this mount: a
     *  customer's drag then snaps to nothing (ADR 195) */
    snapping?: boolean;
    /** hide the generated customer form (builder canvas mode) */
    showForm?: boolean;
    /** How the customer form lays out (ADR 196): `"page"`, every step under a
     *  numbered heading, or `"steps"`, one step at a time with Back and Next.
     *  Omitted, the template's own `form.layout` decides, and a page when it
     *  has none — so an embed that never passes it shows what it always did. */
    layout?: FormLayout;
    /** Fill the element mounted into, for a host that gives the designer a
     *  page or window of its own: the preview centred on a stage, as large as
     *  fits, and the form in a column beside it that scrolls by itself; on a
     *  phone the preview stays at the top and the form scrolls under it. The
     *  element needs a height. The stage and the form column are styled
     *  through the custom properties in `FILL_PROPERTIES`, set on the element.
     *  Omitted, the designer flows in the page as it always has. */
    fill?: boolean;
    /** author-mode build guides: canvas center/edges/other layers (default on) */
    authorSnap?: boolean;
    /** template-author mode: every layer is selectable and movable/resizable/
     *  rotatable regardless of customer flags; gestures call onAuthorChange
     *  instead of writing customer payload values */
    authorMode?: boolean;
    /** an author-mode gesture, committed: a layer's patch under its id, or
     *  the image background's crop under the artwork's reserved key (`$artwork`,
     *  the key its customer values travel under), whose patch holds `crop`
     *  alone — the one change the canvas makes to the background */
    onAuthorChange?: (layerId: string, patch: {
        xMm?: number;
        yMm?: number;
        rotationDeg?: number;
        wMm?: number;
        hMm?: number;
        /** the picture's crop, in fractions of its frame (ADR 181) */
        crop?: {
            xFrac: number;
            yFrac: number;
            zoom: number;
        };
    }) => void;
    onChange?: (state: DesignerState) => void;
    /** The customer picked entry `index` of `mockups` in the designer's own
     *  picker. Not called for `setMockup`, which the host made itself. */
    onMockupChange?: (index: number) => void;
    /** The values the design starts from, as `getState().values` holds them:
     *  a remount passes back the values it kept, and they are in place, on the
     *  form and in `getState()`, once `mount()` resolves. A key naming no layer
     *  of the template is ignored, with a console line. `onChange` is not
     *  called for them. */
    initialValues?: DesignerState["values"];
    onValidation?: (violations: RemoteViolation[]) => void;
    /** BCP-47 locale tag picking the SDK's bundled words: `sv` for Swedish,
     *  `en` for English, matched by the whole tag and then its language
     *  (`sv-SE` is `sv`). Any other tag, or none, is English. */
    locale?: string;
    /** override any subset of the SDK's user-visible strings */
    messages?: Partial<SdkMessages>;
    /** The sizes this storefront sells this design at, in its OWN order and with
     *  its OWN labels (ADR 051). Pixonaut never learns the catalogue: it marks
     *  which entries its rule refuses and renders the rest verbatim. Omitted, no
     *  picker is drawn and the size is whatever the placement or the template's
     *  nominal plate says — exactly as before. */
    printSizes?: PrintSizeOption[];
    /** Which entry starts selected, as an index into `printSizes`. Defaults to
     *  the first. Preselection is merchandising — the launch storefront marks
     *  50×70 POPULÄRT and puts it in the middle — so it is the consumer's to say
     *  rather than "the first legal one". */
    selectedPrintSizeIndex?: number;
    /** The colourway photos this storefront sells this design on, in its OWN
     *  order and with its OWN labels (ADR 027). Pixonaut never learns that a
     *  colourway exists: it composites the chosen photo in the customer's
     *  browser and records nothing about it — no variant, no availability, and
     *  nothing on the Design, the proof or the job ticket.
     *
     *  Each entry carries its own `placementRectPx`, saying where the print sits
     *  IN THAT PHOTO. It travels with the url because the browser has no blank
     *  to inherit a rect from, and a rect measured against one photo is
     *  meaningless against another.
     *
     *  Nothing here is judged against the artwork: unlike a print size, a photo
     *  cannot affect what gets cut. Only an entry that cannot be drawn is
     *  skipped — an empty url, an unusable rect, a `shadingStrength` outside
     *  0 to 1, or a `warp` the stored blank would refuse (`isUsableMockup`). A
     *  `displacementStrength` the stored blank would refuse is read as none,
     *  with a console line, and the entry is still drawn. Omitted, no picker is
     *  drawn and no backdrop is composited — exactly as before. */
    mockups?: MockupOption[];
    /** Which entry starts selected, as an index into `mockups`. Defaults to the
     *  first. Preselection is merchandising, so it is the consumer's to say. */
    selectedMockupIndex?: number;
}

/** The blank and placement this design is for: both, or neither (a
 *  placement id is unique only within its blank). Named, every proof and
 *  commit the designer makes is fitted to that placement, so the proof a
 *  customer approves is the print they get (ADR 022); a pair that does not
 *  resolve is refused as `unknown_placement` (ADR 231). The designer's
 *  `setPlacement()` switches to another pair without remounting. */
declare type MountPlacement = {
    blankId: string;
    placementId: string;
} | {
    blankId?: never;
    placementId?: never;
};

/** An element, or a CSS selector naming one. */
export declare type MountTarget = string | HTMLElement;

/** A named color entry within a palette, as the resolved document carries
 *  it. */
declare interface PaletteEntry {
    name: string;
    color: ColorValue;
}

/** The words, spelled once in TypeScript so the type is a closed union. The
 *  fixture is the shared list; `checkedAgainstFixture` refuses to load when
 *  the two disagree, rather than a test noticing later. */
declare const PICTURE_FIT_WORDS: readonly ["contain", "cover", "fill", "tile"];

declare type PictureFitValue = (typeof PICTURE_FIT_WORDS)[number];

/** What the IIFE build puts on `window.Pixonaut`: everything a page with no
 *  module system calls or checks a rejection against. */
declare const Pixonaut: {
    mount: typeof mount;
    version: string;
    PlacementChangedError: typeof PlacementChangedError;
    WasmBootError: typeof WasmBootError;
    WasmIntegrityError: typeof WasmIntegrityError;
    WasmVersionMismatchError: typeof WasmVersionMismatchError;
};
export { Pixonaut }
export default Pixonaut;

export declare class PixonautDesigner {
    private readonly opts;
    /** resolved UI strings: the locale's bundle (`messagesFor`) <- opts.messages */
    private readonly messages;
    private root;
    /** holds the form apart from the preview (`dom/split.ts`); null: `root` */
    private readonly formRoot;
    private template;
    private formSchema;
    private printMargins;
    /** The template read's floor; none for an in-memory template. */
    private printFloorDpi;
    private values;
    /** the chosen print size, held BESIDE `values` — see `form/size.ts` */
    private size;
    /** the chosen colourway photo. Held beside `values` for the same reason the
     *  size is, and kept OUT of `DesignerState`: unlike a print size it reaches
     *  no Design, proof or job ticket, so surfacing it as persistable state would
     *  imply it is part of the artefact (ADR 027). */
    private mockup;
    /** DOM/canvas layer: preview img and overlay host (owns those live nodes;
     *  exposes them via getters) */
    private dom;
    /** generated-form machinery: field renderers, upload flow, headless
     *  schema/value API (deps: schema/template/values + the place control) */
    private form;
    /** server seam: session id, authenticated fetch, clearSession, approve */
    private apiClient;
    /** The blank and placement requests carry, switched by `setPlacement`. */
    private placement;
    /** What the proof waits for: an upload being improved (#1092). */
    private work;
    /** the stored design a correction mount opens, and what its requests carry */
    private stored;
    private pipeline;
    private gestures;
    /** live-preview render loop: rAF coalescing, settle re-render, dpi/edge caps */
    private preview;
    /** render orchestration: worker pump, queues, asset + gesture caches, sprite */
    private render;
    /** doc-model helpers: templateJson/authorDoc/violations state, validation,
     *  transform/size resolution, gesture plate/sprite split, author patch */
    private doc;
    /** init built the designer into `root`; until then root is the embedder's */
    private built;
    constructor(root: HTMLElement, opts: MountOptions, formRoot?: HTMLElement | null);
    private msg;
    /** tenant words for what a template offers (#238/#254) and its die offer (#402) */
    private pickerSources;
    getSessionId(): string;
    /** "clear my design": wipes this session's unordered uploads server-side */
    clearSession(): Promise<void>;
    init(): Promise<void>;
    /** 'worker' when preview rendering runs off the main thread */
    get previewEngine(): "worker" | "sync";
    /** Telemetry seam fired for every dispatched render job with its target and
     *  the length of its assets json: the refs a job names its pictures by,
     *  and their base64 only where a picture goes inline. The bytes a picture
     *  is registered with once per instance are not counted. A no-op by default; it lives
     *  on the prototype so a host can wrap it once and observe every mount's jobs
     *  (used by the studio progressive-asset e2e). Not part of the headless API.
     *  @internal */
    protected onRenderJob(_target: string, _assetsLen: number): void;
    private api;
    selectLayer(layerId: string | null): void;
    getSelectedLayer(): string | null;
    /** the steps JSON a headless host renders its own UI from: groupId/label/
     *  layerIds, typed fields (an image field: feed its file to uploadAsset) and
     *  `transforms`, one per placeable layer, whose `layerId` selectLayer takes.
     *  Same schema the API serves for the template. */
    getFormSchema(): FormSchema;
    /** The mounted template document, whole — including every prop's
     *  `constraints` and an image layer's `oneOf` preset ids.
     *
     *  That is the contract rather than an oversight (ADR 048): the document is
     *  this widget's copy of the validation and layout rules, which is why
     *  `validateLocal` and the preview can run at all without a round-trip. The
     *  API serves it unprojected to the `pk` this widget holds for the same
     *  reason, so an embedder reading it sees what the renderer sees.
     *
     *  For the customer-facing subset — editable props of grouped layers, with
     *  their labels and field types — use {@link PixonautDesigner.getFormSchema} instead. */
    getTemplate(): TemplateDoc;
    /** The consumer's own size menu with the rule's verdict on each entry — the
     *  headless seam a storefront drawing its own radio buttons reads instead of
     *  the default picker, the same way `getFormSchema()` serves the JSON behind
     *  `buildForm()` (ADR 051). */
    getPrintSizes(): PrintSizeChoice[];
    /** The size the customer chose, as an index into `opts.printSizes`. */
    setPrintSize(index: number): void;
    /** Show entry `index` of `opts.mockups` without remounting; an index that
     *  names no entry is ignored. Not reported to `onMockupChange`. */
    setMockup(index: number): void;
    /** The shown entry of `opts.mockups`; undefined when there are none. */
    getMockup(): number | undefined;
    getState(): DesignerState;
    /** Where a form drawn as steps stands (ADR 196), so a host can show its
     *  own finishing button on the last step. Undefined on a page and while the
     *  generated form is not shown (`showForm: false`). */
    getStep(): FormStepPosition | undefined;
    /** Show the step at `index`, from 0 among the steps the form shows.
     *  Ignored unless the form is shown as steps, and for an index that names
     *  no shown step. */
    setStep(index: number): void;
    setValue(layerId: string, prop: string, value: unknown): void;
    setTransform(layerId: string, patch: Partial<{
        xMm: number;
        yMm: number;
        rotationDeg: number;
        scale: number;
        wMm: number;
        hMm: number;
    }>): void;
    /** The drag hint's Reset: the layers go back where the author put them. */
    private resetTransforms;
    private notifyChange;
    private afterChange;
    private templateIdOf;
    /** Local WASM validation for instant feedback; the server re-validates. */
    validateLocal(): {
        ok: boolean;
        doc?: TemplateDoc;
        violations: Violation[];
    };
    /** upload a customer image for an image layer and set its `src`.
     *  Returns the assetId plus any print-quality warning from the API
     *  (machine `warningKey` + `warningParams`, and the English `warning`). */
    uploadAsset(file: File, layerId: string): Promise<UploadResult>;
    /** Improve an upload whose result offered `improveResolution`; the
     *  improved picture replaces it on the layer, and `approve()` waits. */
    improveResolution(assetId: string, layerId: string): Promise<Improved>;
    /** Server-side proof; resolves the proofUrl the customer approves. Rejects
     *  with an `SdkRequestError` (its `violations`, or `status` and `code`), or
     *  a `PlacementChangedError` when `setPlacement()` switched the pair while
     *  the proof was being made. */
    approve(): Promise<ApproveResult>;
    /** Switch the blank and placement the design is for (both, or neither)
     *  without remounting: the customer's values stay, and the next proof and
     *  commit are fitted to the new pair. Resolves once the pair is in effect.
     *  A pair that does not resolve rejects with an `SdkRequestError` whose
     *  `code` is `unknown_placement`, and the previous pair stays. */
    setPlacement(blankId: string, placementId: string): Promise<void>;
    /** Name no blank or placement: the template's own shape, with no product. */
    setPlacement(): Promise<void>;
    /** Server-side commit with no proof first; rejects as `approve()` does. */
    commit(): Promise<CommitResult>;
    destroy(): void;
    /** move a layer's center to a named anchor (author tooling) */
    positionLayer(layerId: string, anchor: string): void;
    /** author build-guide snapping (canvas center/edges/other layers) */
    get authorSnapEnabled(): boolean;
    set authorSnapEnabled(on: boolean);
    setAuthorSnap(on: boolean): void;
    /** Lock the designer, or unlock it: locked, it takes no input — no gesture
     *  on the preview, one under way included, and no field on the form — so
     *  nothing changes the design while the host makes a proof of it. */
    setLocked(locked: boolean): void;
}

/** What `approve()` rejects with when `setPlacement()` switched the pair
 *  while its proof was being made: the proof is fitted to the pair before
 *  the switch, so it is not the print the customer would now get. Also what
 *  a `setPlacement()` rejects with when a later one superseded it. */
export declare class PlacementChangedError extends Error {
    constructor(message?: string);
}

/** The resolved print geometry an artwork is drawn into: the box and its
 *  margins. Mirrors the Rust `PrintBox` (`crates/pixonaut-render/src/
 *  validate.rs`), which the resolved doc carries and the template does not —
 *  ADR 018 moved the size to the order and the margins to the blank's
 *  placement. */
declare interface PrintBoxSpec {
    widthMm: number;
    heightMm: number;
    bleedMm?: number;
    safeAreaMm?: number;
    printMethod?: string;
    anchor?: unknown;
    [key: string]: unknown;
}

/** How far a print runs past its trim, and how far inside it important
 *  artwork stays, in millimetres. */
declare interface PrintMargins {
    bleedMm: number;
    safeAreaMm: number;
}

/** One entry, with the rule's verdict attached. */
export declare interface PrintSizeChoice extends PrintSizeOption {
    /** False when a check that RAN refused this size. Read it together with the
     *  two `checked*` flags below: `true` means "nothing that ran said no", not
     *  "checked completely". */
    legal: boolean;
    /** The rule's own code when illegal, verbatim — the same vocabulary
     *  `POST /v1/templates/:id/print-size` answers with, so a host can branch on
     *  one set of strings whichever side told it (ADR 019). */
    reason?: "wrong_ratio" | "too_large";
    /** The shape check ran. Always true: it needs only the template. */
    checkedRatio: boolean;
    /** The ceiling check ran. Always FALSE here, and deliberately visible rather
     *  than implied: bounds live on a blank's placement, and the browser does
     *  not resolve the blank's bounds, even for a mount that names one. A host drawing its own radio buttons must be able to tell "this
     *  size is legal" from "this size has no known ratio problem and I could not
     *  check its ceiling" — different claims, and only one of them is a green
     *  tick. A host that has named a placement and wants a complete answer
     *  before letting a customer invest work calls `POST /print-size`, which
     *  exists for that and is already reachable with a publishable key. */
    checkedBounds: boolean;
    /** Whether this is the currently chosen entry. */
    selected: boolean;
}

/** One entry in the consumer's own size menu.
 *
 *  The consumer owns ALL of this: which sizes exist, what they are called, and
 *  what order they appear in. Their storefront marks 50×70 POPULÄRT and puts
 *  it in the middle; an SDK that sorted by area or relabelled these would have
 *  made a merchandising decision, which is the catalogue's job and never
 *  Pixonaut's (ADR 011/019). */
export declare interface PrintSizeOption {
    widthMm: number;
    heightMm: number;
    /** rendered verbatim — the SDK never composes or translates this */
    label: string;
}

/** The subset of a declared ratio this derivation reads. Structural rather
 *  than `AspectRatioValue` so this leaf stays free of the zod module that
 *  declares it; the two shapes are identical by construction. */
declare interface RatioPair {
    w: number;
    h: number;
}

/** Where the print sits IN one photo, in that photo's own pixels. */
export declare interface RectPx {
    x: number;
    y: number;
    w: number;
    h: number;
}

/** A constraint failure as it arrives from the API, which strips `allowed`
 *  before responding (issue #61, ADR 016 Amendment 3).
 *
 *  Anything fed by BOTH paths — `onValidation`, notably — is typed as this, so
 *  an embedder reading `allowed` off it gets a compile error rather than
 *  `undefined` at runtime from the network path.
 *
 *  Deliberately a plain `Omit` and NOT a branded type, unlike the API's
 *  `PublicViolation`: a WASM `Violation` must remain assignable here, since the
 *  local path really does hand one to the same callback. That means this type
 *  documents intent rather than enforcing absence — it stops a consumer relying
 *  on the field, not a producer including it. The enforcement that matters
 *  happens server-side, where the field is actually removed. */
export declare type RemoteViolation = Omit<Violation, "allowed">;

/** merge order: the locale's bundle (English unless given) <- overrides */
export declare function resolveMessages(overrides?: Partial<SdkMessages>, bundle?: SdkMessages): SdkMessages;

export declare interface SdkMessages {
    /** An integrator's word for ONE offered shape on this embed — a die or a
     *  shape layer's outline (ADR 187); the family keeps its `die` name so
     *  existing keys still apply — keyed by its shape id, as
     *  `form.die.<shape id>` (#402). It outranks the tenant's row name. We
     *  ship none: the words for a shape are the tenant's, which is why
     *  this is an index signature rather than a list of keys, and why a key
     *  may be absent. */
    [dieOption: `form.die.${string}`]: string | undefined;
    /** What a field says of a violation the local check found at it, keyed by
     *  the violation's rule (`form/field-violations.ts`). A rule with no
     *  sentence is not shown at the field. */
    [violation: `form.violation.${string}`]: string | undefined;
    "upload.button": string;
    "upload.uploading": string;
    "upload.error": string;
    /** A file of a format the template does not take (ADR 189); interpolates
     *  {formats}, the ones it does, as a person names a choice ("PNG or JPEG"). */
    "upload.unsupported-format": string;
    /** A file over the template's size limit; interpolates {maxMb}, the limit
     *  in megabytes, rounded down so a file read as under it is under it. */
    "upload.too-large": string;
    /** A moving picture (an animated WebP, a HEIC sequence), which cannot be
     *  used as the still it would be printed as. */
    "upload.animated": string;
    /** Offered under an upload too small for the chosen size, where the store
     *  allows it (#1092): makes a larger copy for the proof. Says what it
     *  does for the customer, never how. */
    "upload.improve": string;
    "upload.improving": string;
    "upload.improved": string;
    "upload.improve-error": string;
    /** low-res print-quality warning; interpolates {actualPx}, {minPx}.
     *  `actualPx` is the image's CONSTRAINING edge — width or height, whichever
     *  falls further short of its own floor — and `minPx` is that same edge's
     *  floor. The wording must therefore stay axis-neutral: naming an axis would
     *  misreport a wide short image, whose reported number is its height. */
    "warning.asset.low-resolution": string;
    /** shown when the stored file is larger than the one the customer chose,
     *  because it was re-encoded into a format the print path can embed (ADR
     *  023). Interpolates {uploadBytes} and {storedBytes}. The wording must not
     *  name the format: they chose a picture, not a codec. Unlike the studio's
     *  version this says nothing about storage cost — an end customer of a
     *  tenant has no quota of their own to spend. */
    "warning.asset.stored-larger": string;
    /** shown when an upload for a tiled picture is smaller than the renderer
     *  tiles (ADR 200): its proof would fail. Interpolates {actualPx}, the
     *  picture's short side, and {minPx}, what it needs. */
    "warning.asset.tile-too-small": string;
    /** The callout ending a step with one layer the customer places on the
     *  preview (#726), unless its author named the move: then the author's
     *  words, verbatim. */
    "form.drag-hint-one": string;
    /** The same callout for a step with several such layers. */
    "form.drag-hint": string;
    /** The callout's button that puts the step's layers back where the
     *  author placed them. */
    "form.drag-reset": string;
    /** A layer's size slider, when the author gave its scale no label. */
    "form.scale": string;
    "form.image-none": string;
    "form.image-current": string;
    /** An offered shape's empty choice: no shape, the plain rectangle. */
    "form.shape-none": string;
    /** Label for one picture in an image picker when the tenant has not named
     *  it; interpolates {index}, 1-based.
     *
     *  Positional because an asset id is meaningless to a customer. Since #254
     *  a named asset reads as the tenant's own word instead, so this is the
     *  FALLBACK rather than the answer — a picker reading "Ros, Bild 2" is
     *  honest about which pictures have a word. */
    "form.image-option": string;
    /** Label for one offered die the tenant has not named — a shape row,
     *  offered by id (#237, #402). Interpolates {index}, 1-based.
     *
     *  The ONLY word we carry for a die. Every die is a row in the tenant's
     *  shape library, and its name is the word a customer reads; this is the
     *  last rung, for a row whose name did not cross the wire. An integrator
     *  can still name one die on one embed as `form.die.<shape id>` in
     *  `mount({ messages })`, which outranks the row's name.
     *
     *  Positional for exactly the reason `form.image-option` above is: a raw
     *  `shp_…` is internal plumbing and must not be put in front of a customer.
     *  Its OWN key rather than `form.image-option` reused: "Picture 1" is wrong
     *  for a die, and a host must be able to translate the two apart. */
    "form.die-option": string;
    /** A text layer's offered alignments, one message per wire name (#317).
     *  Named because `middle` is the renderer's vocabulary and a stable
     *  identity, not the word a customer should read. Three rungs apply --
     *  integrator, tenant, then these -- and an alignment with no
     *  word anywhere falls back to its own name. A font family has no key: its
     *  name IS the word. */
    "form.align.left": string;
    "form.align.center": string;
    "form.align.right": string;
    "form.valign.top": string;
    "form.valign.middle": string;
    "form.valign.bottom": string;
    /** A picture's offered fits (#805), one message per fit, under the same
     *  three rungs as an alignment: `cover` is the renderer's word, not the
     *  one a customer should read. */
    "form.fit.contain": string;
    "form.fit.cover": string;
    "form.fit.fill": string;
    "form.fit.tile": string;
    /** Under a tile size at which the uploaded picture repeats smaller than
     *  the renderer prints a tile (ADR 200): the remedy is a larger size. */
    "form.tile-too-small": string;
    /** A text's weight, by the face it draws (#769). */
    "form.weight.regular": string;
    "form.weight.bold": string;
    "form.weight.one-face": string;
    /** A face of a family the template names in its fonts, other than its
     *  regular (400) or bold (700) one, by its CSS weight (ADR 219 §6). */
    "form.weight.css": string;
    /** The heading above the artwork's own values. The derivation supplies
     *  `ARTWORK_STEP_LABEL` as the default so a non-SDK consumer still gets a
     *  label; this is what lets an integrator say it in their own words, the way
     *  they can for every other string here. */
    "form.artwork-step": string;
    /** A percent field's reading, such as an offered opacity (#427);
     *  interpolates {value}, the whole or fractional percent, never the stored
     *  fraction. */
    "form.percent": string;
    /** An image's crop field (ADR 181): the zoom slider's accessible name. */
    "form.crop-zoom": string;
    /** The zoom's reading; interpolates {value}, the factor over the picture
     *  as the frame first covers it. */
    "form.crop-zoom-value": string;
    /** The control that starts dragging the picture inside its frame on the
     *  preview, and what it says while the drag is on. */
    "form.crop-move": string;
    "form.crop-done": string;
    /** The picture's frame on the preview while it is being moved: its
     *  accessible name, which also says how to move it from the keyboard. */
    "form.crop-surface": string;
    /** The control that puts the picture back where the author placed it. */
    "form.crop-reset": string;
    /** The label of a text layer's offered size when the template leaves it
     *  unlabelled; an authored label is shown instead. */
    "form.font-size": string;
    /** The heading over an offered field its author left unlabelled, one per
     *  attribute it sets (`form/field-label.ts`): the form's word in place of
     *  the attribute's internal name. Each key is `form.label.` and the field's
     *  `prop` as `getFormSchema()` carries it, except a text size's, which is
     *  `form.font-size` above. An authored label is shown instead. */
    "form.label.content": string;
    "form.label.fill": string;
    "form.label.color": string;
    "form.label.imageAssetId": string;
    "form.label.shape": string;
    "form.label.src": string;
    "form.label.crop": string;
    "form.label.fit": string;
    "form.label.tileScale": string;
    "form.label.fontFamily": string;
    "form.label.fontWeight": string;
    "form.label.align": string;
    "form.label.valign": string;
    "form.label.opacity": string;
    /** At the end of a text field's heading when it has a maximum length;
     *  interpolates {count}, the characters typed, and {max}. */
    "form.char-count": string;
    /** Above the step a form laid out as steps shows (ADR 196); interpolates
     *  {index}, counted from 1, and {count}, the steps the form shows. */
    "form.step-counter": string;
    /** The step counter where the form is too narrow for the long one, and
     *  the bars drop their step names (#726); the same variables. */
    "form.step-counter-short": string;
    /** Under a text field with a maximum length whose author gave it no help
     *  text (#726); interpolates {max}. */
    "form.char-limit": string;
    /** The button back to the previous step. */
    "form.step-back": string;
    /** The button on to the next step; interpolates {label}, that step's
     *  heading. The last step has none: finishing is the host's button. */
    "form.step-next": string;
    /** The button after a palette's swatches that opens a free colour picker,
     *  when the author offers any colour beside the palette (ADR 180). */
    "form.palette-custom": string;
    /** What a palette field's heading shows while the colour is the
     *  customer's own rather than one of the swatches. */
    "form.palette-custom-chosen": string;
    /** Under a colour field while the customer's pick cannot be printed
     *  exactly, beside the pick and what it prints as; interpolates {hex}, the
     *  pick's six hex digits without the `#`, and {cmyk}, what it prints as,
     *  `C0 M71 Y59 K30`. The studio picker's sentence. */
    "form.color-cannot-print": string;
    /** heading above the print-size picker. The SIZES themselves are the
     *  consumer's and are rendered verbatim (ADR 051) — only this heading and
     *  the two refusal suffixes below are the SDK's words. */
    "size.legend": string;
    /** appended to an option the rule refuses for its shape */
    "size.illegal.wrong-ratio": string;
    /** appended to an option that exceeds the print area. Unreachable from the
     *  widget's own local check, which has no blank and so no ceiling to test;
     *  it exists because a headless host may attach a server verdict. */
    "size.illegal.too-large": string;
    /** heading above the colourway picker. One key, where the size picker needs
     *  three: the photos are the consumer's and rendered verbatim (ADR 027), and
     *  there are no refusal suffixes because no rule refuses a photo. */
    "mockup.legend": string;
    "preview.alt": string;
    /** Under the preview when the designer fills its element (`fill`), on a
     *  desktop. */
    "preview.caption": string;
}

/** How every call the designer makes on its own behalf rejects when the api
 *  refuses it: the template read, `approve()` and `commit()`. `status` is the
 *  contract a host branches on (an expired link's 401, a paused template's
 *  404, a throttled visitor's 429, an outage's 5xx); `code` is the server's
 *  `error`, when its body names one. */
export declare class SdkRequestError extends Error {
    readonly status: number;
    readonly code?: string;
    /** what the design breaks, on a 422 that is a validation failure; the same
     *  list `onValidation` was handed */
    readonly violations?: RemoteViolation[];
    constructor(message: string, status: number, detail?: {
        code?: string;
        violations?: RemoteViolation[];
    });
}

/** Written out, not inferred, so the SDK's published types carry no zod. */
declare type ShapeGeometryValue = {
    type: "path";
    dFrac: string;
};

/** What an id resolves against: the live rows (a draft) or the frozen
 *  snapshot (a published version), as one argument type. */
declare type ShapeSource = Readonly<Record<string, ShapeGeometryValue>>;

/** The template fields the ratio check reads. Structural, so a mounted
 *  `TemplateDoc`, a parsed template and a test fixture all satisfy it. */
declare interface SizeConstrainedTemplate {
    ratio?: RatioPair;
    ratioTolerance?: number;
}

/** Every target a template or an offered move may name, in the order the
 *  builder lists them:
 *
 *  - `centre` — the plate's vertical and horizontal centre lines;
 *  - `thirds` — the lines at one and two thirds of the plate, each way;
 *  - `safeEdges` — the safe area's four edges, or the plate's when there is
 *    no safe area;
 *  - `layers` — every other layer's sides and centre lines. */
declare const SNAP_TARGETS: readonly ["centre", "thirds", "safeEdges", "layers"];

/** What the artwork's drags snap to: named targets and the author's grid
 *  (ADR 195). */
declare type SnapConfig = SnapSettings;

/** The author's plate grid: a line every `stepFrac` of the plate, each way,
 *  stored as a fraction (`0.05` is a line every 5 %). A customer never snaps
 *  to it. */
declare interface SnapGrid {
    stepFrac: number;
}

/** A template's `snap`: the targets every offered move snaps to, unless the
 *  move names its own, and the author's grid. Absent targets mean a customer's
 *  move does not snap. */
declare interface SnapSettings {
    targets?: SnapTarget[];
    grid?: SnapGrid;
}

declare type SnapTarget = (typeof SNAP_TARGETS)[number];

/** A mount whose preview and form go into two elements the host places.
 *  The preview takes its element's width and follows it when the host
 *  resizes it; the form takes its element's. Fill mode is for one element
 *  given a page of its own, so it is not offered here. */
export declare type SplitMountOptions = MountOptions & {
    /** The element the preview is drawn into. */
    previewTarget: MountTarget;
    /** The element the form, and the size and colourway pickers, are drawn
     *  into. */
    formTarget: MountTarget;
    fill?: never;
};

/** A stored design opened to correct it (#583). Every value is applied over
 *  its resolved document with the core's revise, as the api applies a
 *  correction, so the designer's values are exactly the correction to save.
 *  @internal */
declare interface StoredDesign {
    /** The design's current resolved document, and the box it was resolved
     *  into, whose margins are frozen with it. */
    doc: StoredDoc & {
        printBox?: Partial<PrintMargins>;
    };
    /** Its template version, as the template route answers it: the document,
     *  its form, and the tenant's words for what it offers. */
    read: TemplateRead;
    /** Whether the member may upload a picture of their own. False hides the
     *  upload button; the template's presets are still offered. */
    uploads: boolean;
}

/** Mounted on a stored design: the studio's session, the design, and no
 *  size menu, since a correction keeps the size the design was bought at.
 *  @internal */
declare type StoredDesignMount = MountOptionsBase & StudioSessionCredential & {
    design: StoredDesign;
    printSizes?: never;
    selectedPrintSizeIndex?: never;
    blankId?: never;
    placementId?: never;
};

/** The parts of a stored resolved document this model reads itself; the
 *  rest is handed to the core as it came. */
declare interface StoredDoc {
    layers: Array<{
        id: string;
        xMm: number;
        yMm: number;
        sizeMm: {
            w: number;
            h: number;
        };
        transform: {
            rotationDeg: number;
            scale: number;
        };
        /** an image layer's picture and crop, as the core resolved them */
        kind?: Record<string, unknown>;
    }>;
    /** the resolved background: its picture and crop are read */
    background?: unknown;
}

/** A studio member's own session, for the studio's designer opened on a
 *  stored design to correct it (#583). Requests carry the session's cookie
 *  and the tenant it acts in, which the api checks against the member's
 *  memberships. Only with a `StoredDesign`: a member makes no new
 *  design through this widget. @internal */
declare interface StudioSessionCredential {
    studioSession: {
        tenantId: string;
    };
    publishableKey?: never;
    shareLink?: never;
    correctionLink?: never;
}

/** A resolved/authorable template document: the shape mounted or validated.
 *
 *  `surfaces[]` is retired (ADR 018) — a template is ONE artwork, so its
 *  layers and groups sit here directly. `printBox` is present on a RESOLVED
 *  doc (the validator fills it from the geometry the caller supplied) and
 *  absent on a raw authoring template, which stores no print size at all. */
declare interface TemplateDoc {
    templateId?: string;
    /** Each family the text may be drawn in, with its faces' hashes, as the
     *  api writes them out (ADR 219 §6). Absent on a document from before
     *  fonts were tenant data, which draws the compiled-in families. */
    fonts?: FontSource;
    name?: string;
    dpi?: number;
    printBox?: PrintBoxSpec;
    /** The shape the template DECLARES (ADR 020) — the plate every surface
     *  falls back to when no `printBox` is supplied.
     *
     *  `RatioPair` comes from the same zod-free schema leaf as `nominalPlate`,
     *  which reads this field: the type and the function that consumes it stay
     *  one definition rather than a structural restatement free to drift. No
     *  bundle cost — the leaf has no imports of its own.
     *
     *  Optional because this interface describes JSON that arrives from a host,
     *  including docs written before templates declared a shape;
     *  `TemplateSchema.ratio` is required on the parsed template. */
    ratio?: RatioPair;
    /** How far a requested print size's shape may stray from `ratio`, as a
     *  fraction of it; `0` means that shape only.
     *
     *  Already served — `GET /v1/templates/:id` returns the whole author
     *  document — but untyped here until the SDK needed to run the ratio half of
     *  the print-size rule in the browser (ADR 051). Optional for the same
     *  reason `ratio` is: this interface describes JSON arriving from a host,
     *  including documents written before the field existed. */
    ratioTolerance?: number;
    /** `color` was `unknown`, which is assignable to no narrower type — so once
     *  the form derivation started reading it as a prop (ADR 038), passing this
     *  document to `buildFormSchema` would have needed a cast, and a cast is
     *  what that structural type exists to avoid: it would swallow the next
     *  change to either model rather than failing at the call site.
     *
     *  Declared as what the derivation reads. On a RESOLVED doc the same key
     *  holds a plain colour, which this canvas passes through without reading —
     *  the die-cut and the background are drawn by the Rust core, not here.
     *
     *  `kind` arrived with #166, which made the TEMPLATE's background a tagged
     *  union. It is optional here, and both payload fields stay optional,
     *  because this one interface describes both documents this canvas is handed:
     *  an author document, which now carries the discriminant and exactly one
     *  payload, and a resolved document, which carries neither the discriminant
     *  nor the prop wrapper and never will — it freezes into the design's
     *  revisions (`design_revisions.doc_json`) and must keep parsing as it was
     *  approved. Narrowing this to the union would make the resolved case need
     *  the cast this type exists to avoid. */
    background?: {
        kind?: "color" | "image";
        imageAssetId?: unknown;
        /** The image arm's fit: a bare word, absent for cover (ADR 181 relies on
         *  it — a crop applies after cover only). */
        fit?: unknown;
        /** The image arm's crop: a prop on a template, a bare crop on a resolved
         *  document — `unknown` for the reason `imageAssetId` is, and read
         *  through `isRecord` where it is written. */
        crop?: unknown;
        color?: {
            editable?: boolean;
            label?: string;
            constraints?: Record<string, unknown>;
            value?: unknown;
        };
    };
    /** The die-cut silhouette — the shape the product is cut to, and the cutline
     *  the printshop cuts.
     *
     *  Structural rather than validated, like the rest of this interface: it
     *  describes JSON arriving from a host, including a document written before
     *  a field existed, and `@pixonaut/schema` is what refuses a bad one. Named
     *  here rather than left `unknown` because a field no consumer can read
     *  without a cast is one that fails silently when it stops arriving —
     *  the same story `ratioTolerance` tells about itself above.
     *
     *  A geometry is a path and nothing else (ADR 122). Its `dFrac` is in
     *  fractions of the plate (ADR 028), which is what lets one authored document
     *  keep its silhouette at every size it sells at; the millimetres a printshop
     *  cuts to appear once, at resolve. */
    shape?: {
        value: {
            type: "path";
            dFrac: string;
        } | {
            type: "shape";
            shapeId: string;
        };
        editable: boolean;
        label?: string;
        /** The offered set, as wire names. `oneOf` stays a list of strings, which
         *  is what let this ship without widening a field the publish scan, the
         *  asset scan and the SDK's renderers all read as strings. */
        constraints?: {
            oneOf?: string[];
        };
    };
    cutShape?: unknown;
    snap?: SnapConfig;
    layers: LayerSpec[];
    groups?: GroupSpec[];
    /** The palettes the document offers, by name. Only the RESOLVED document
     *  carries them — what the SDK is served and the studio's canvas draws,
     *  once `resolveReferences` has written each offered palette out. An
     *  authored template holds none: it offers the tenant's palette rows by id
     *  (#525). */
    palettes?: Record<string, PaletteEntry[]>;
    [key: string]: unknown;
}

/** What the template route answers, as far as the mount reads it. */
declare interface TemplateRead {
    template: TemplateDoc;
    formSchema: FormSchema;
    /** The tenant's default bleed and safe area, which the template prints
     *  with when no placement is named. */
    printMargins: PrintMargins;
    /** The minimum print resolution the design's pictures are judged against:
     *  the template's own, else the tenant's, as the server reads it. */
    printFloorDpi: number;
}

/** An editable/animatable axis flag on a layer transform, with its bounds. */
declare interface TransformAxis {
    editable?: boolean;
    bounds?: string;
    min?: number;
    max?: number;
    snapDeg?: number;
    /** a move's own snap targets, in place of the template's (ADR 195) */
    snapTo?: SnapTarget[];
    /** A scale axis's grain (see `scaleBounds`). */
    step?: number;
    minWMm?: number;
    maxWMm?: number;
    minHMm?: number;
    maxHMm?: number;
    [key: string]: unknown;
}

/** Result of an asset upload. `warningKey` + `warningParams` are the machine
 *  contract the host localizes via SdkMessages; `warning` is the API's English
 *  rendering, kept one release for back-compat and used as a fallback. */
export declare interface UploadResult {
    assetId: string;
    warning?: string;
    warningKey?: string;
    warningParams?: UploadWarningParams;
    /** Set when the picture is short of the floor at the chosen size and may
     *  be improved before the proof, to this size (#1092): the template allows
     *  it and the store can pay for it. `improveResolution(assetId, layerId)`
     *  asks for it. */
    improveResolution?: {
        widthPx: number;
        heightPx: number;
    };
}

/** Params interpolated into a localized asset-upload warning (see SdkMessages).
 *
 *  A union keyed by `warningKey`: `asset.low-resolution` carries the
 *  constraining edge in pixels, `asset.stored-larger` the uploaded and stored
 *  byte counts. `renderWarning` is shape-agnostic — it stringifies whatever
 *  `Object.entries` yields — so a new arm needs no code change there, only a
 *  message in `SdkMessages`. */
export declare type UploadWarningParams = {
    actualPx: number;
    minPx?: number;
} | {
    uploadBytes: number;
    storedBytes: number;
};

/** This SDK's release. The wasm it boots must report the same one. */
export declare const version: string;

/** A constraint failure as the WASM core emits it, `allowed` included. Only
 *  the local path produces these: the browser already holds the template, so
 *  restating one of its rules discloses nothing it did not send. */
export declare interface Violation {
    layerId: string;
    prop: string;
    rule: string;
    given: unknown;
    allowed: unknown;
    /** `error` refuses a publish; `warning` never does (ADR 193). */
    severity: "error" | "warning";
}

/** The one kind of wrap today: an upright product photographed square-on. */
declare const WARP_KIND_CYLINDER = "cylinder";

/** The wasm glue at `url` could not be loaded, or could not instantiate its
 *  binary: not served there, or a glue and a binary from two releases (a
 *  LinkError or CompileError, before any version can be asked). The
 *  original failure is the `cause`. */
export declare class WasmBootError extends Error {
    readonly url: string;
    constructor(url: string, message: string, options?: ErrorOptions);
}

/** The Subresource Integrity values (`sha384-<base64>`) of the glue and the
 *  binary a released SDK ships with, which it checks both against before
 *  booting either. */
declare interface WasmIntegrity {
    glue: string;
    binary: string;
}

/** A file of the wasm pair whose bytes are not the ones the SDK was released
 *  with: served from a mirror that changed it, from another release, or
 *  tampered with. Nothing of it was run. */
export declare class WasmIntegrityError extends Error {
    readonly url: string;
    readonly file: keyof WasmIntegrity;
    readonly expected: string;
    readonly found: string;
    constructor(url: string, file: keyof WasmIntegrity, expected: string, found: string);
}

/** A booted wasm built for another release than the code booting it.
 *
 *  The wasm is served by whoever embeds the designer, so a script and a wasm
 *  from two releases is an ordinary deployment mistake, not a build error,
 *  and the two then disagree about exports and their arguments. The mount
 *  refuses at boot, naming both versions and where the wasm came from, rather
 *  than drawing with a renderer whose checks quietly fail call by call.
 *  `found` is null for a wasm from before the binding reported its version. */
export declare class WasmVersionMismatchError extends Error {
    readonly url: string;
    readonly expected: string;
    readonly found: string | null;
    constructor(url: string, expected: string, found: string | null, options?: ErrorOptions);
}

/** The message naming each offered prop when its author gave it no label,
 *  named after the prop as `getFormSchema()` carries it. Typed over every
 *  offered prop, so a prop added to a layer kind fails to compile here until
 *  it has a word, rather than reaching a customer as its key. */
declare const WORD_KEY_BY_PROP: {
    readonly content: "form.label.content";
    readonly fill: "form.label.fill";
    readonly color: "form.label.color";
    readonly imageAssetId: "form.label.imageAssetId";
    readonly shape: "form.label.shape";
    readonly src: "form.label.src";
    readonly crop: "form.label.crop";
    readonly fit: "form.label.fit";
    readonly tileScale: "form.label.tileScale";
    readonly fontFamily: "form.label.fontFamily";
    readonly fontWeight: "form.label.fontWeight";
    readonly fontSizeFrac: "form.font-size";
    readonly align: "form.label.align";
    readonly valign: "form.label.valign";
    readonly opacity: "form.label.opacity";
};

export { }