@anvilkit/contracts 0.1.18

package/dist/ai.d.cts

@@ -0,0 +1,265 @@
+/**
+ * @file AI generation contract — the types `@anvilkit/schema`,
+ * `@anvilkit/validator`, and AI copilot plugins pass between each
+ * other when asking an LLM to generate or validate page content.
+ *
+ * ### Shape of the contract
+ *
+ * - {@link AiComponentSchema} is a describable-to-an-LLM version of a
+ *   Puck component config. `@anvilkit/schema` derives this from a
+ *   Puck `Config` automatically; this package just owns the
+ *   destination shape.
+ * - {@link AiGenerationContext} is the complete input to a single
+ *   LLM call — the available components plus optional environment
+ *   hints (current page data, theme, locale).
+ * - {@link AiValidationResult} is the output of validating an LLM
+ *   response against the expected shape. `@anvilkit/validator` owns
+ *   the runtime check; this package owns the result shape.
+ *
+ * ### Design rules
+ *
+ * 1. **Types only.** No runtime code.
+ * 2. **Closed field-type union.** {@link AiFieldSchema.type} is a
+ *    fixed set — adding a new field type is a breaking change so
+ *    plugin authors are forced to handle every case.
+ * 3. **Type-only Puck import.** `Data` is imported via `import type`
+ *    and erased at compile time — `ai.ts` adds zero runtime
+ *    reference to `@puckeditor/core`.
+ *
+ * @see {@link https://github.com/anvilkit/studio/blob/main/docs/tasks/core-006-types-domain.md | core-006}
+ */
+import type { Data as PuckData } from "@puckeditor/core";
+/**
+ * The finite set of field types an AI schema can describe.
+ *
+ * Mirrors Puck's own field type union closely but is intentionally a
+ * separate, stable enum — the AI contract must not break every time
+ * Puck adds or renames a field type. `@anvilkit/schema` maps Puck
+ * field types to these values during derivation.
+ *
+ * Closed union by design: extending this list is a breaking change
+ * to the AI contract.
+ */
+export type AiFieldType = "text" | "richtext" | "number" | "boolean" | "image" | "url" | "color" | "select" | "array" | "object";
+/**
+ * Theme hint forwarded into AI prompts so the model can pick
+ * appropriate colors, imagery, and tone (review finding TS-4). Named
+ * once here rather than inlining `"light" | "dark"` at each AI context
+ * site. (Kept local to the type-only `ai.ts` layer rather than reusing
+ * the react-layer `ThemeResolved`, which would cross the engine
+ * boundary.)
+ */
+export type AiThemeHint = "light" | "dark";
+/**
+ * Description of a single prop on a component, in a shape an LLM can
+ * reason about.
+ *
+ * `@anvilkit/schema`'s `configToAiContext()` (Phase 3) produces an
+ * array of these from a Puck `Config` field descriptor. The AI
+ * copilot plugin then feeds them into its system prompt so the model
+ * knows which props it can set and what shape each one takes.
+ *
+ * Recursive: `select` fields carry {@link options}, `array` fields
+ * carry {@link itemSchema}, and `object` fields carry their own
+ * nested {@link itemSchema} describing the object shape.
+ *
+ * @remarks
+ * The recursive variants are modeled here with **loose optionals**
+ * (`options?` / `itemSchema?` / `properties?`) rather than a
+ * `type`-discriminated union (review finding TS-d). A discriminated
+ * union keyed on {@link AiFieldType} — following the closed-union
+ * precedents elsewhere in this package
+ * (`StudioAssetUploadEvent`, `StudioPluginCapabilities`) — would let
+ * the compiler enforce that `select` carries `options`, `array` carries
+ * `itemSchema`, etc. That refactor is **breaking** for the `0.1.x` AI
+ * contract, so it is deferred to the next contract major; until then,
+ * `@anvilkit/schema`/`@anvilkit/validator` own the per-type invariants
+ * at runtime (Zod).
+ */
+export interface AiFieldSchema {
+    /**
+     * The prop name on the owning component (e.g. `"title"`,
+     * `"ctaHref"`). Must match the key in the component's
+     * `defaultProps`.
+     */
+    readonly name: string;
+    /**
+     * The field's data type. See {@link AiFieldType}.
+     */
+    readonly type: AiFieldType;
+    /**
+     * Whether the prop must be set for the component to render
+     * correctly. Defaults to `false` when omitted — the LLM will
+     * treat the field as optional.
+     */
+    readonly required?: boolean;
+    /**
+     * Human-readable description of what the prop is for. Forwarded
+     * verbatim into the LLM prompt, so write it in the voice of
+     * instructions to a collaborator ("The headline shown at the
+     * top of the hero section").
+     */
+    readonly description?: string;
+    /**
+     * For `type: "select"` fields, the allowed values. Each option
+     * carries both the machine-readable `value` (written into the
+     * prop) and the human-readable `label` (shown to the LLM so it
+     * picks the right one).
+     */
+    readonly options?: readonly {
+        readonly label: string;
+        readonly value: string;
+    }[];
+    /**
+     * For `type: "array"` fields, the schema of a single item. When the
+     * item is itself an object, the item carries its own
+     * {@link properties} listing the typed sub-fields.
+     *
+     * Absent on scalar field types and on `type: "object"` (which uses
+     * {@link properties} directly).
+     */
+    readonly itemSchema?: AiFieldSchema;
+    /**
+     * For `type: "object"` fields (and `type: "array"` items whose
+     * `itemSchema.type === "object"`), the typed sub-fields of the
+     * object. Each entry is a fully-formed {@link AiFieldSchema} so
+     * the LLM and the validator can reason about nested structure
+     * without parsing free-form descriptions.
+     *
+     * Absent on scalar field types.
+     */
+    readonly properties?: readonly AiFieldSchema[];
+    /**
+     * For slot fields (mapped to `type: "object"`), the list of
+     * component names that may be inserted into the slot. When
+     * omitted, any registered component is allowed.
+     *
+     * Mirrors Puck's `allow` array on slot field definitions.
+     */
+    readonly allow?: readonly string[];
+    /**
+     * For slot fields (mapped to `type: "object"`), the list of
+     * component names that may *not* be inserted into the slot.
+     *
+     * Mirrors Puck's `disallow` array on slot field definitions.
+     */
+    readonly disallow?: readonly string[];
+}
+/**
+ * Description of a single component in a shape an LLM can reason
+ * about — name, purpose, props, and an optional concrete example.
+ *
+ * An array of these is passed to the LLM so it knows what components
+ * are available and how to use them. Produced by
+ * `@anvilkit/schema`'s `configToAiContext()` (Phase 3) from a Puck
+ * `Config`; this package only owns the destination shape.
+ */
+export interface AiComponentSchema {
+    /**
+     * The component name as registered in the Puck config (e.g.
+     * `"Hero"`, `"Button"`, `"Card"`). Matches the `type` used in
+     * Puck's component data.
+     */
+    readonly componentName: string;
+    /**
+     * Human-readable description of what the component does and when
+     * to use it. Forwarded verbatim into the LLM prompt — write it
+     * as guidance to a collaborator.
+     */
+    readonly description: string;
+    /**
+     * The component's props, described field-by-field.
+     */
+    readonly fields: readonly AiFieldSchema[];
+    /**
+     * Optional concrete example of a valid prop bag. The LLM uses
+     * this as a one-shot example of how the fields should look when
+     * populated; leaving it off falls back to zero-shot from the
+     * field descriptions alone.
+     */
+    readonly example?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The full input to a single LLM generation call.
+ *
+ * Constructed by the AI copilot plugin at the moment the user asks
+ * for generation. {@link availableComponents} is derived from the
+ * Puck `Config` once per session and cached; the remaining fields
+ * are per-call hints.
+ */
+export interface AiGenerationContext {
+    /**
+     * Every component the LLM is allowed to emit, described as an
+     * {@link AiComponentSchema}. The LLM cannot use a component that
+     * is not present in this list.
+     */
+    readonly availableComponents: readonly AiComponentSchema[];
+    /**
+     * Optional snapshot of the current Puck page data. Lets the LLM
+     * generate contextual edits (e.g. "add a CTA to the existing
+     * hero") instead of always producing a full page from scratch.
+     */
+    readonly currentData?: PuckData;
+    /**
+     * Optional theme hint (`"light"` or `"dark"`) so the LLM can
+     * pick appropriate colors, imagery, and tone. Host apps
+     * typically forward the current editor theme.
+     */
+    readonly theme?: AiThemeHint;
+    /**
+     * Optional BCP 47 language tag (e.g. `"en-US"`, `"fr-FR"`) so
+     * the LLM generates copy in the right language.
+     */
+    readonly locale?: string;
+}
+/**
+ * A single issue produced by validating an LLM's response against
+ * the expected component/field shape.
+ *
+ * `@anvilkit/validator` owns the runtime check that emits these;
+ * this package just owns the shape so validator output flows through
+ * a stable contract.
+ */
+export interface AiValidationIssue {
+    /**
+     * JSON-pointer-style path to the offending value inside the LLM
+     * response (e.g. `"content.0.props.title"`). Empty string means
+     * the issue applies to the response as a whole.
+     */
+    readonly path: string;
+    /**
+     * Human-readable message describing what went wrong. Suitable
+     * for display in a dev console or a toast.
+     */
+    readonly message: string;
+    /**
+     * Severity of the issue.
+     *
+     * - `"warn"` — the response is usable but suspect (e.g. an
+     *   unexpected extra field).
+     * - `"error"` — the response is unusable (e.g. required field
+     *   missing, wrong type).
+     */
+    readonly severity: "error" | "warn";
+}
+/**
+ * The outcome of validating an LLM response.
+ *
+ * {@link valid} is `true` only when the response contains zero
+ * issues with `severity: "error"` — `"warn"`-level issues may be
+ * present even when the response is considered valid.
+ */
+export interface AiValidationResult {
+    /**
+     * `true` iff the response contains no `severity: "error"`
+     * issues. A valid response may still carry `"warn"` entries in
+     * {@link issues}.
+     */
+    readonly valid: boolean;
+    /**
+     * The full list of issues found. Empty array when the response
+     * passed without complaint.
+     */
+    readonly issues: readonly AiValidationIssue[];
+}
+//# sourceMappingURL=ai.d.cts.map

package/dist/ai.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.cts","sourceRoot":"","sources":["../src/ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GACpB,MAAM,GACN,UAAU,GACV,QAAQ,GACR,SAAS,GACT,OAAO,GACP,KAAK,GACL,OAAO,GACP,QAAQ,GACR,OAAO,GACP,QAAQ,CAAC;AAEZ;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS;QAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;KACvB,EAAE,CAAC;IACJ;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACrD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC9C"}

package/dist/ai.d.ts

@@ -0,0 +1,265 @@
+/**
+ * @file AI generation contract — the types `@anvilkit/schema`,
+ * `@anvilkit/validator`, and AI copilot plugins pass between each
+ * other when asking an LLM to generate or validate page content.
+ *
+ * ### Shape of the contract
+ *
+ * - {@link AiComponentSchema} is a describable-to-an-LLM version of a
+ *   Puck component config. `@anvilkit/schema` derives this from a
+ *   Puck `Config` automatically; this package just owns the
+ *   destination shape.
+ * - {@link AiGenerationContext} is the complete input to a single
+ *   LLM call — the available components plus optional environment
+ *   hints (current page data, theme, locale).
+ * - {@link AiValidationResult} is the output of validating an LLM
+ *   response against the expected shape. `@anvilkit/validator` owns
+ *   the runtime check; this package owns the result shape.
+ *
+ * ### Design rules
+ *
+ * 1. **Types only.** No runtime code.
+ * 2. **Closed field-type union.** {@link AiFieldSchema.type} is a
+ *    fixed set — adding a new field type is a breaking change so
+ *    plugin authors are forced to handle every case.
+ * 3. **Type-only Puck import.** `Data` is imported via `import type`
+ *    and erased at compile time — `ai.ts` adds zero runtime
+ *    reference to `@puckeditor/core`.
+ *
+ * @see {@link https://github.com/anvilkit/studio/blob/main/docs/tasks/core-006-types-domain.md | core-006}
+ */
+import type { Data as PuckData } from "@puckeditor/core";
+/**
+ * The finite set of field types an AI schema can describe.
+ *
+ * Mirrors Puck's own field type union closely but is intentionally a
+ * separate, stable enum — the AI contract must not break every time
+ * Puck adds or renames a field type. `@anvilkit/schema` maps Puck
+ * field types to these values during derivation.
+ *
+ * Closed union by design: extending this list is a breaking change
+ * to the AI contract.
+ */
+export type AiFieldType = "text" | "richtext" | "number" | "boolean" | "image" | "url" | "color" | "select" | "array" | "object";
+/**
+ * Theme hint forwarded into AI prompts so the model can pick
+ * appropriate colors, imagery, and tone (review finding TS-4). Named
+ * once here rather than inlining `"light" | "dark"` at each AI context
+ * site. (Kept local to the type-only `ai.ts` layer rather than reusing
+ * the react-layer `ThemeResolved`, which would cross the engine
+ * boundary.)
+ */
+export type AiThemeHint = "light" | "dark";
+/**
+ * Description of a single prop on a component, in a shape an LLM can
+ * reason about.
+ *
+ * `@anvilkit/schema`'s `configToAiContext()` (Phase 3) produces an
+ * array of these from a Puck `Config` field descriptor. The AI
+ * copilot plugin then feeds them into its system prompt so the model
+ * knows which props it can set and what shape each one takes.
+ *
+ * Recursive: `select` fields carry {@link options}, `array` fields
+ * carry {@link itemSchema}, and `object` fields carry their own
+ * nested {@link itemSchema} describing the object shape.
+ *
+ * @remarks
+ * The recursive variants are modeled here with **loose optionals**
+ * (`options?` / `itemSchema?` / `properties?`) rather than a
+ * `type`-discriminated union (review finding TS-d). A discriminated
+ * union keyed on {@link AiFieldType} — following the closed-union
+ * precedents elsewhere in this package
+ * (`StudioAssetUploadEvent`, `StudioPluginCapabilities`) — would let
+ * the compiler enforce that `select` carries `options`, `array` carries
+ * `itemSchema`, etc. That refactor is **breaking** for the `0.1.x` AI
+ * contract, so it is deferred to the next contract major; until then,
+ * `@anvilkit/schema`/`@anvilkit/validator` own the per-type invariants
+ * at runtime (Zod).
+ */
+export interface AiFieldSchema {
+    /**
+     * The prop name on the owning component (e.g. `"title"`,
+     * `"ctaHref"`). Must match the key in the component's
+     * `defaultProps`.
+     */
+    readonly name: string;
+    /**
+     * The field's data type. See {@link AiFieldType}.
+     */
+    readonly type: AiFieldType;
+    /**
+     * Whether the prop must be set for the component to render
+     * correctly. Defaults to `false` when omitted — the LLM will
+     * treat the field as optional.
+     */
+    readonly required?: boolean;
+    /**
+     * Human-readable description of what the prop is for. Forwarded
+     * verbatim into the LLM prompt, so write it in the voice of
+     * instructions to a collaborator ("The headline shown at the
+     * top of the hero section").
+     */
+    readonly description?: string;
+    /**
+     * For `type: "select"` fields, the allowed values. Each option
+     * carries both the machine-readable `value` (written into the
+     * prop) and the human-readable `label` (shown to the LLM so it
+     * picks the right one).
+     */
+    readonly options?: readonly {
+        readonly label: string;
+        readonly value: string;
+    }[];
+    /**
+     * For `type: "array"` fields, the schema of a single item. When the
+     * item is itself an object, the item carries its own
+     * {@link properties} listing the typed sub-fields.
+     *
+     * Absent on scalar field types and on `type: "object"` (which uses
+     * {@link properties} directly).
+     */
+    readonly itemSchema?: AiFieldSchema;
+    /**
+     * For `type: "object"` fields (and `type: "array"` items whose
+     * `itemSchema.type === "object"`), the typed sub-fields of the
+     * object. Each entry is a fully-formed {@link AiFieldSchema} so
+     * the LLM and the validator can reason about nested structure
+     * without parsing free-form descriptions.
+     *
+     * Absent on scalar field types.
+     */
+    readonly properties?: readonly AiFieldSchema[];
+    /**
+     * For slot fields (mapped to `type: "object"`), the list of
+     * component names that may be inserted into the slot. When
+     * omitted, any registered component is allowed.
+     *
+     * Mirrors Puck's `allow` array on slot field definitions.
+     */
+    readonly allow?: readonly string[];
+    /**
+     * For slot fields (mapped to `type: "object"`), the list of
+     * component names that may *not* be inserted into the slot.
+     *
+     * Mirrors Puck's `disallow` array on slot field definitions.
+     */
+    readonly disallow?: readonly string[];
+}
+/**
+ * Description of a single component in a shape an LLM can reason
+ * about — name, purpose, props, and an optional concrete example.
+ *
+ * An array of these is passed to the LLM so it knows what components
+ * are available and how to use them. Produced by
+ * `@anvilkit/schema`'s `configToAiContext()` (Phase 3) from a Puck
+ * `Config`; this package only owns the destination shape.
+ */
+export interface AiComponentSchema {
+    /**
+     * The component name as registered in the Puck config (e.g.
+     * `"Hero"`, `"Button"`, `"Card"`). Matches the `type` used in
+     * Puck's component data.
+     */
+    readonly componentName: string;
+    /**
+     * Human-readable description of what the component does and when
+     * to use it. Forwarded verbatim into the LLM prompt — write it
+     * as guidance to a collaborator.
+     */
+    readonly description: string;
+    /**
+     * The component's props, described field-by-field.
+     */
+    readonly fields: readonly AiFieldSchema[];
+    /**
+     * Optional concrete example of a valid prop bag. The LLM uses
+     * this as a one-shot example of how the fields should look when
+     * populated; leaving it off falls back to zero-shot from the
+     * field descriptions alone.
+     */
+    readonly example?: Readonly<Record<string, unknown>>;
+}
+/**
+ * The full input to a single LLM generation call.
+ *
+ * Constructed by the AI copilot plugin at the moment the user asks
+ * for generation. {@link availableComponents} is derived from the
+ * Puck `Config` once per session and cached; the remaining fields
+ * are per-call hints.
+ */
+export interface AiGenerationContext {
+    /**
+     * Every component the LLM is allowed to emit, described as an
+     * {@link AiComponentSchema}. The LLM cannot use a component that
+     * is not present in this list.
+     */
+    readonly availableComponents: readonly AiComponentSchema[];
+    /**
+     * Optional snapshot of the current Puck page data. Lets the LLM
+     * generate contextual edits (e.g. "add a CTA to the existing
+     * hero") instead of always producing a full page from scratch.
+     */
+    readonly currentData?: PuckData;
+    /**
+     * Optional theme hint (`"light"` or `"dark"`) so the LLM can
+     * pick appropriate colors, imagery, and tone. Host apps
+     * typically forward the current editor theme.
+     */
+    readonly theme?: AiThemeHint;
+    /**
+     * Optional BCP 47 language tag (e.g. `"en-US"`, `"fr-FR"`) so
+     * the LLM generates copy in the right language.
+     */
+    readonly locale?: string;
+}
+/**
+ * A single issue produced by validating an LLM's response against
+ * the expected component/field shape.
+ *
+ * `@anvilkit/validator` owns the runtime check that emits these;
+ * this package just owns the shape so validator output flows through
+ * a stable contract.
+ */
+export interface AiValidationIssue {
+    /**
+     * JSON-pointer-style path to the offending value inside the LLM
+     * response (e.g. `"content.0.props.title"`). Empty string means
+     * the issue applies to the response as a whole.
+     */
+    readonly path: string;
+    /**
+     * Human-readable message describing what went wrong. Suitable
+     * for display in a dev console or a toast.
+     */
+    readonly message: string;
+    /**
+     * Severity of the issue.
+     *
+     * - `"warn"` — the response is usable but suspect (e.g. an
+     *   unexpected extra field).
+     * - `"error"` — the response is unusable (e.g. required field
+     *   missing, wrong type).
+     */
+    readonly severity: "error" | "warn";
+}
+/**
+ * The outcome of validating an LLM response.
+ *
+ * {@link valid} is `true` only when the response contains zero
+ * issues with `severity: "error"` — `"warn"`-level issues may be
+ * present even when the response is considered valid.
+ */
+export interface AiValidationResult {
+    /**
+     * `true` iff the response contains no `severity: "error"`
+     * issues. A valid response may still carry `"warn"` entries in
+     * {@link issues}.
+     */
+    readonly valid: boolean;
+    /**
+     * The full list of issues found. Empty array when the response
+     * passed without complaint.
+     */
+    readonly issues: readonly AiValidationIssue[];
+}
+//# sourceMappingURL=ai.d.ts.map

package/dist/ai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.d.ts","sourceRoot":"","sources":["../src/ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,IAAI,IAAI,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GACpB,MAAM,GACN,UAAU,GACV,QAAQ,GACR,SAAS,GACT,OAAO,GACP,KAAK,GACL,OAAO,GACP,QAAQ,GACR,OAAO,GACP,QAAQ,CAAC;AAEZ;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS;QAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;KACvB,EAAE,CAAC;IACJ;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACrD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC9C"}

package/dist/ai.js

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

package/dist/assets.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/assets.d.cts

@@ -0,0 +1,32 @@
+/**
+ * Asset resolution types — live in their own module so `plugin.ts` and
+ * `export.ts` can both reference them without a cycle.
+ */
+/**
+ * The outcome of resolving an indirect asset reference (e.g. `asset://…`) to a
+ * concrete, directly-usable location.
+ */
+export interface AssetResolution {
+    /** The resolved asset URL — e.g. an `https:` / `data:` URL or a relative path. */
+    readonly url: string;
+    /**
+     * Optional resolver-supplied metadata (e.g. dimensions, MIME type,
+     * attribution). Opaque to the core — passed through to consumers verbatim.
+     */
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Rewrites an asset reference to its resolved location, or returns `null` when
+ * this resolver does not handle the reference.
+ *
+ * Resolvers are registered via the plugin context's `registerAssetResolver`
+ * seam and collected into `StudioRuntime.assetResolvers` in registration
+ * order. A consuming export format consults each in order and stops at the
+ * first non-null result; how a format treats a reference that no resolver
+ * handles is the format's own policy. May run sync or async — the pipeline
+ * awaits the result.
+ *
+ * @param url - The raw reference to resolve (e.g. an `asset://…` URL).
+ */
+export type IRAssetResolver = (url: string) => Promise<AssetResolution | null> | AssetResolution | null;
+//# sourceMappingURL=assets.d.cts.map

package/dist/assets.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.cts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAClD;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,CAC7B,GAAG,EAAE,MAAM,KACP,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,eAAe,GAAG,IAAI,CAAC"}

package/dist/assets.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Asset resolution types — live in their own module so `plugin.ts` and
+ * `export.ts` can both reference them without a cycle.
+ */
+/**
+ * The outcome of resolving an indirect asset reference (e.g. `asset://…`) to a
+ * concrete, directly-usable location.
+ */
+export interface AssetResolution {
+    /** The resolved asset URL — e.g. an `https:` / `data:` URL or a relative path. */
+    readonly url: string;
+    /**
+     * Optional resolver-supplied metadata (e.g. dimensions, MIME type,
+     * attribution). Opaque to the core — passed through to consumers verbatim.
+     */
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Rewrites an asset reference to its resolved location, or returns `null` when
+ * this resolver does not handle the reference.
+ *
+ * Resolvers are registered via the plugin context's `registerAssetResolver`
+ * seam and collected into `StudioRuntime.assetResolvers` in registration
+ * order. A consuming export format consults each in order and stops at the
+ * first non-null result; how a format treats a reference that no resolver
+ * handles is the format's own policy. May run sync or async — the pipeline
+ * awaits the result.
+ *
+ * @param url - The raw reference to resolve (e.g. an `asset://…` URL).
+ */
+export type IRAssetResolver = (url: string) => Promise<AssetResolution | null> | AssetResolution | null;
+//# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAClD;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,CAC7B,GAAG,EAAE,MAAM,KACP,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,eAAe,GAAG,IAAI,CAAC"}

package/dist/assets.js

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

package/dist/export.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});