@vectoriox/iox-ui 5.51.0 → 5.53.0

package/generation-core/index.d.ts

@@ -3025,5 +3025,149 @@ interface BuildStepFacts {
 }
 declare function buildStepFacts(plan: SitePlan, actions?: Readonly<Record<string, `${ContentTypeAction}`>>): BuildStepFacts;
 
-export { ACTIVE_BUILD_STATUSES, BAR_ITEMS_MAX, BAR_ITEMS_MIN, BASELINE_ROLES, BUILD_STEPS, BaselineRole, BindScope, BuildNoticeCode, BuildStep, CardBindTarget, ComposeError, ComposeIssueCode, ContentTypeAction, CreatedKind, DANGLING_LINK_CODES, DEFAULT_PHONE_MENU_BREAKPOINT, ENTRANCE_EASING, ENTRANCE_ORIGIN_LOOK, ENTRANCE_TRIGGER, EntrancePart, FACT_KEYS, GlobalSlot, KeptReason, NAV_PART_LABELS, NAV_SHAPE_COPY, NEUTRAL_STYLE_PROPS, NODE_BASELINES, NavPagesSource, NavRole, NavShape, NavShapeError, PRICING_PATTERN, PUBLISH_BLOCKING_PLACEHOLDERS, PageDataKind, PathIssueCollector, PatternDirective, PatternGlobalPosition, PatternOpens, PatternPlaceholder, PatternRecipe, PhoneMenuBreakpoint, PlaceholderKind, PlanDataSourceMode, PlanDataSourceType, PreflightRefusalCode, RelativeOp, SAMPLE_IMAGE_REF, SITE_FACT_LABELS, SITE_HEADER_PATTERN, SITE_PATTERNS, SITE_PLAN_VERSION, SITE_TEMPLATES, SPEC_SITE_FACTS, SPEC_SITE_LIBRARY, SPEC_SITE_PATTERNS, SPEC_SITE_PLAN_SHAPE, SPEC_SITE_TEMPLATES, STUDIO_TEMPLATE, SiteBuildKind, SiteBuildStatus, SitePlanError, SitePlanIssueCode, SitePlanSourceKind, SiteTemplateError, SiteTemplateId, StepState, addBarItem, altSourceScopes, assertStyleSlots, assertValidSitePlan, barIconForRoute, blocksPublish, buildKeys, buildStepFacts, builtHomePageId, composeNavHeader, composeSection, composeSite, createSerializedNode, describePlanData, entranceAction, entranceInteraction, failedBuildStep, findNavRoot, isActiveBuild, isNonEmptyString, isPlainObject, moveBarItem, navPages, navShapeBreakpoint, navShapeOf, nextSourceOf, nodeBindPaths, parseSampleImageRef, pathAt, patternById, patternNeedsBinding, patternNodes, patternOptionalParts, patternScopes, patternSlots, patternTakesBinding, phoneMenuPages, planFromTemplate, planNavShape, releasedLayoutDefaults, removeBarItem, requiredShapeKeys, routeParams, sampleImageRef, sectionEntrances, setStyleProps, shapeKeys, siteNavPages, staggerDelay, validateSitePlan, walkSerialized };
-export type { AddBarItemResult, BarItemsEditResult, BuildNotice, BuildStepError, BuildStepFacts, BuildStepRecord, CmsDataSourcePlan, ComposeContext, ComposeIssue, ComposedDataSource, ComposedItem, ComposedNavHeader, ComposedPage, ComposedPlaceholder, ComposedRoute, ComposedSection, ComposedSite, ContentFieldPlan, ContentSeedPlan, ContentTypePlan, CreateNodeOptions, CreatedRecord, DataSourcePlan, EntranceAction, EntranceInteraction, EntranceSpec, FactKey, NavHeaderInput, NavHeaderOptions, NavPage, NavShapeOptions, NavShapeResult, NodeBaseline, PageData, PageDataLine, PagePlan, PageSectionPlan, PathIssue, PatternNode, PlainObject, PreflightRefusal, RelativeDataSourcePlan, SectionEntrances, SectionInput, SectionOptions, SerializedBinding, SerializedNode, SerializedResponsive, ShapeEntry, ShapeIssueCodes, SiteBuildRun, SiteBusiness, SitePageRef, SitePattern, SitePlan, SitePlanIssue, SitePlanSource, SitePlanValidation, SiteTemplate, TemplatePlanInput, UndoKept, UndoPreview, UndoRecord };
+/**
+ * The AI pipeline's WIRE vocabulary (AI plan §3c, §3n, M0): what iox-cms's `ai` API answers and what every client
+ * of it reads — the steps a model works on, who pays (IOX credits or the studio's own key), a model of the vetted
+ * list with its price per token class, the one cost → credits rule (1 credit = 1 US cent of what the AI cost, D4),
+ * the refusals (board 11) and a generation's stages. ONE definition: iox-cms meters and refuses with it, the
+ * Settings ▸ AI screen and the wizard show it. Pure types, enums and helpers; no transport, no prices typed here.
+ */
+declare enum AiProviderId {
+    Anthropic = "anthropic",
+    OpenRouter = "openrouter"
+}
+/** Who pays: the platform's credits, or the studio's own provider key (metered for display, never charged). */
+declare enum AiKeyMode {
+    Platform = "platform",
+    Own = "own"
+}
+/** The steps a model works on (board 9's rows), in screen order. */
+declare enum AiStep {
+    ReadMessage = "read",
+    PlanSite = "plan",
+    ChangePlan = "change",
+    MakePictures = "pictures",
+    NameStructures = "scan"
+}
+declare const AI_STEPS: ReadonlyArray<AiStep>;
+/** What a model must be able to do for a step to run on it. */
+declare enum AiCapability {
+    StructuredOutput = "structured-output",
+    ImageInput = "image-input",
+    ImageOutput = "image-output"
+}
+declare const AI_STEP_NEEDS: Readonly<Record<AiStep, ReadonlyArray<AiCapability>>>;
+/** Tokens a typical use of a step reads and writes (plan §3d "Where credits go") — what a shown estimate is made of. */
+declare const AI_STEP_TYPICAL_TOKENS: Readonly<Record<AiStep, AiTokenCounts>>;
+/** Tokens by the class a provider prices them in. */
+interface AiTokenCounts {
+    input: number;
+    output: number;
+    /** Written to the prompt cache (priced above input). */
+    cacheWrite: number;
+    /** Read from the prompt cache (priced well below input). */
+    cacheRead: number;
+}
+/** US dollars per million tokens, per class. A class without a price is priced as input. */
+interface AiTokenPrice {
+    input: number;
+    output: number;
+    cacheWrite?: number;
+    cacheRead?: number;
+}
+/** A model of the vetted list (served by the control plane with the entitlements, §3n) — its price travels with it. */
+interface AiModelEntry {
+    id: string;
+    provider: `${AiProviderId}`;
+    label: string;
+    /** The steps it may be chosen for. */
+    steps: ReadonlyArray<`${AiStep}`>;
+    /** The steps it is the default for (board 9's "recommended"). */
+    recommendedFor?: ReadonlyArray<`${AiStep}`>;
+    capabilities: ReadonlyArray<`${AiCapability}`>;
+    /** Null when the provider reports each call's cost itself and the list carries no price. */
+    price: AiTokenPrice | null;
+    /** Kept so old ledger rows still name it; never offered, and a studio's choice of it falls back to the default. */
+    retired?: boolean;
+}
+/** 1 credit = 1 US cent of what the AI actually cost (decision D4). */
+declare const CREDITS_PER_USD = 100;
+declare const NO_TOKENS: Readonly<AiTokenCounts>;
+/** What `tokens` cost at `price`, in US dollars. */
+declare function costUsd(tokens: AiTokenCounts, price: AiTokenPrice): number;
+/** Dollars → credits, kept to a millionth of a credit (a short read costs a fraction of one). */
+declare function creditsOfUsd(usd: number): number;
+/** The credits a typical use of `step` costs on a model of `price` — never typed, always computed (§3d). */
+declare function estimateStepCredits(step: AiStep, price: AiTokenPrice, tokens?: AiTokenCounts): number;
+/** Can `model` do `step`? The step's needs against the model's capabilities. */
+declare function modelCanDo(model: Pick<AiModelEntry, 'capabilities'>, step: AiStep): boolean;
+/** Why AI did not run (board 11). The server refuses with these BEFORE any model call. */
+declare enum AiRefusalCode {
+    NotInPlan = "ai.notInPlan",
+    OutOfCredits = "ai.outOfCredits",
+    CapReached = "ai.capReached",
+    NotConnected = "ai.notConnected",
+    KeyInvalid = "ai.keyInvalid",
+    PlanUnknown = "ai.planUnknown"
+}
+/** The HTTP status each refusal answers with (board 11). */
+declare const AI_REFUSAL_STATUS: Readonly<Record<AiRefusalCode, number>>;
+/** What a refusal offers next. */
+declare enum AiNextKind {
+    /** Ask IOX (a prefilled email to the operator, until a plan can be bought — D2). */
+    Contact = "contact",
+    /** Open Settings ▸ AI. */
+    Settings = "settings",
+    /** Try again later, or with less. */
+    Retry = "retry"
+}
+declare const AI_REFUSAL_NEXT: Readonly<Record<AiRefusalCode, AiNextKind>>;
+interface AiRefusal {
+    code: AiRefusalCode;
+    planName?: string;
+    /** Credits left this period (platform credits only). */
+    remaining?: number;
+    /** What the refused call would have cost, about. */
+    estimate?: number;
+    next: {
+        kind: AiNextKind;
+        href?: string;
+    };
+}
+/** The studio's AI credits this period (the connector's meter, E4). `allowance: null` = unlimited. */
+interface AiMeter {
+    used: number;
+    allowance: number | null;
+    remaining: number | null;
+    periodStart: string;
+    periodEnd: string;
+}
+/** A generation's stages (§3d). The runner works while `task` is set; otherwise the owner has the next move. */
+declare enum AiGenerationStage {
+    Reading = "reading",
+    Analysis = "analysis",
+    Design = "design",
+    Plan = "plan",
+    Build = "build",
+    Done = "done",
+    Failed = "failed",
+    Cancelled = "cancelled"
+}
+/** The stages nothing advances any more. */
+declare const FINAL_GENERATION_STAGES: ReadonlyArray<AiGenerationStage>;
+/** How one model call ended — a ledger row's status. */
+declare enum AiCallStatus {
+    /** Written before the call: a reservation at the estimate until the call settles. */
+    Started = "started",
+    Ok = "ok",
+    /** The answer came back and the shared validator refused it (with a path). */
+    Invalid = "invalid",
+    /** The model declined (a provider refusal) — charged what the provider reports. */
+    Refused = "refused",
+    Error = "error",
+    /** The process died during the call: charged at the estimate, since what it cost was never reported. */
+    Interrupted = "interrupted"
+}
+
+export { ACTIVE_BUILD_STATUSES, AI_REFUSAL_NEXT, AI_REFUSAL_STATUS, AI_STEPS, AI_STEP_NEEDS, AI_STEP_TYPICAL_TOKENS, AiCallStatus, AiCapability, AiGenerationStage, AiKeyMode, AiNextKind, AiProviderId, AiRefusalCode, AiStep, BAR_ITEMS_MAX, BAR_ITEMS_MIN, BASELINE_ROLES, BUILD_STEPS, BaselineRole, BindScope, BuildNoticeCode, BuildStep, CREDITS_PER_USD, CardBindTarget, ComposeError, ComposeIssueCode, ContentTypeAction, CreatedKind, DANGLING_LINK_CODES, DEFAULT_PHONE_MENU_BREAKPOINT, ENTRANCE_EASING, ENTRANCE_ORIGIN_LOOK, ENTRANCE_TRIGGER, EntrancePart, FACT_KEYS, FINAL_GENERATION_STAGES, GlobalSlot, KeptReason, NAV_PART_LABELS, NAV_SHAPE_COPY, NEUTRAL_STYLE_PROPS, NODE_BASELINES, NO_TOKENS, NavPagesSource, NavRole, NavShape, NavShapeError, PRICING_PATTERN, PUBLISH_BLOCKING_PLACEHOLDERS, PageDataKind, PathIssueCollector, PatternDirective, PatternGlobalPosition, PatternOpens, PatternPlaceholder, PatternRecipe, PhoneMenuBreakpoint, PlaceholderKind, PlanDataSourceMode, PlanDataSourceType, PreflightRefusalCode, RelativeOp, SAMPLE_IMAGE_REF, SITE_FACT_LABELS, SITE_HEADER_PATTERN, SITE_PATTERNS, SITE_PLAN_VERSION, SITE_TEMPLATES, SPEC_SITE_FACTS, SPEC_SITE_LIBRARY, SPEC_SITE_PATTERNS, SPEC_SITE_PLAN_SHAPE, SPEC_SITE_TEMPLATES, STUDIO_TEMPLATE, SiteBuildKind, SiteBuildStatus, SitePlanError, SitePlanIssueCode, SitePlanSourceKind, SiteTemplateError, SiteTemplateId, StepState, addBarItem, altSourceScopes, assertStyleSlots, assertValidSitePlan, barIconForRoute, blocksPublish, buildKeys, buildStepFacts, builtHomePageId, composeNavHeader, composeSection, composeSite, costUsd, createSerializedNode, creditsOfUsd, describePlanData, entranceAction, entranceInteraction, estimateStepCredits, failedBuildStep, findNavRoot, isActiveBuild, isNonEmptyString, isPlainObject, modelCanDo, moveBarItem, navPages, navShapeBreakpoint, navShapeOf, nextSourceOf, nodeBindPaths, parseSampleImageRef, pathAt, patternById, patternNeedsBinding, patternNodes, patternOptionalParts, patternScopes, patternSlots, patternTakesBinding, phoneMenuPages, planFromTemplate, planNavShape, releasedLayoutDefaults, removeBarItem, requiredShapeKeys, routeParams, sampleImageRef, sectionEntrances, setStyleProps, shapeKeys, siteNavPages, staggerDelay, validateSitePlan, walkSerialized };
+export type { AddBarItemResult, AiMeter, AiModelEntry, AiRefusal, AiTokenCounts, AiTokenPrice, BarItemsEditResult, BuildNotice, BuildStepError, BuildStepFacts, BuildStepRecord, CmsDataSourcePlan, ComposeContext, ComposeIssue, ComposedDataSource, ComposedItem, ComposedNavHeader, ComposedPage, ComposedPlaceholder, ComposedRoute, ComposedSection, ComposedSite, ContentFieldPlan, ContentSeedPlan, ContentTypePlan, CreateNodeOptions, CreatedRecord, DataSourcePlan, EntranceAction, EntranceInteraction, EntranceSpec, FactKey, NavHeaderInput, NavHeaderOptions, NavPage, NavShapeOptions, NavShapeResult, NodeBaseline, PageData, PageDataLine, PagePlan, PageSectionPlan, PathIssue, PatternNode, PlainObject, PreflightRefusal, RelativeDataSourcePlan, SectionEntrances, SectionInput, SectionOptions, SerializedBinding, SerializedNode, SerializedResponsive, ShapeEntry, ShapeIssueCodes, SiteBuildRun, SiteBusiness, SitePageRef, SitePattern, SitePlan, SitePlanIssue, SitePlanSource, SitePlanValidation, SiteTemplate, TemplatePlanInput, UndoKept, UndoPreview, UndoRecord };