@vectoriox/iox-ui 5.54.0 → 5.56.0

package/generation-core/index.d.ts

@@ -1,4 +1,4 @@
-import { DesignChoices, AnimateId } from '@vectoriox/iox-ui/design-core';
+import { DesignChoices, AnimateId, DesignTokenLike } from '@vectoriox/iox-ui/design-core';
 
 declare const SPEC_SITE_PLAN_SHAPE: {
     readonly plan: {
@@ -2331,6 +2331,52 @@ declare class PathIssueCollector<C extends string> {
     unique(values: Array<string | null>, path: (i: number) => string, what: string): void;
 }
 
+/**
+ * The ONE set of builders every structured-output format is written with (AI plan §3c, M0-5 / M1-1 / M1-3 / M1-5):
+ * the SiteAnalysis, the reading, the Site Plan and the plan edits. Each object is built FROM a documented shape table
+ * (`shape-check`): its keys are the table's keys, the required ones are the table's required ones, each described in
+ * the table's own words — and a builder handed a key list that disagrees with its table THROWS, so a shape that gains
+ * a key cannot ship a format that silently lacks it. The subset is the strictest both providers' native strict modes
+ * accept (Anthropic `output_config.format`, OpenRouter `json_schema` + `strict`): every object closed
+ * (`additionalProperties: false`), unions as `anyOf`, single values as a one-entry `enum`, no length / count / number
+ * bounds, no `$ref`. The format is a hint the provider enforces; the shared validator stays the gate.
+ */
+type JsonSchema = {
+    [key: string]: unknown;
+};
+declare class JsonSchemaShapeError extends Error {
+}
+declare const jsonText: () => JsonSchema;
+declare const jsonBoolean: () => JsonSchema;
+declare const jsonInteger: () => JsonSchema;
+declare const jsonOneOf: (values: ReadonlyArray<string>) => JsonSchema;
+declare const jsonListOf: (items: JsonSchema) => JsonSchema;
+declare const jsonAnyOf: (options: ReadonlyArray<JsonSchema>) => JsonSchema;
+/** A closed object with exactly these properties. */
+declare function jsonClosedObject(properties: Record<string, JsonSchema>, required: ReadonlyArray<string>, description?: string): JsonSchema;
+/** The table's own words for a key (`key` or `key?`). */
+declare function describeShapeKey(entry: ShapeEntry, key: string): string;
+/** An entry's `[name]` keys (the object's own field names) written as ONE list on the wire — no strict mode can say
+ *  "any key", so the map travels as `[{ name, value }]` under `key` and the decoder turns it back. */
+interface DynamicKeysAsList {
+    /** The wire key holding the list. */
+    key: string;
+    /** The list's schema. */
+    schema: JsonSchema;
+}
+/**
+ * An object of one shape-table entry: exactly its fixed keys, its required keys required, each described by the
+ * table; an entry's `[name]` keys are not object keys — `dynamic` writes them as one list. Throws when the properties
+ * given are not the table's keys.
+ */
+declare function jsonShapedObject(entry: ShapeEntry, properties: Record<string, JsonSchema>, name?: string, dynamic?: DynamicKeysAsList): JsonSchema;
+/** Every keyword a schema uses — what a spec checks against the strict subset. */
+declare function jsonSchemaKeywords(node: unknown, out?: Set<string>): Set<string>;
+/** The keywords the strict subset never uses. */
+declare const JSON_SCHEMA_BANNED_KEYWORDS: ReadonlyArray<string>;
+/** Every object node of a schema (through properties, items and anyOf). */
+declare function jsonSchemaObjects(node: unknown, out?: JsonSchema[]): JsonSchema[];
+
 /**
  * The Site Plan validator — the gate in front of the composer. The wizard's plan and (later) the AI's
  * plan go through the SAME checks: an unknown pattern, a slot the pattern does not declare, a source
@@ -2838,6 +2884,8 @@ declare enum BuildStep {
     Preflight = "preflight",
     ContentTypes = "content-types",
     SampleImages = "sample-images",
+    /** I2: the curated stock photos the plan's empty picture slots take, copied into the studio (never hot-linked). */
+    StockPhotos = "stock-photos",
     Items = "items",
     DataSources = "data-sources",
     Pages = "pages",
@@ -2857,6 +2905,8 @@ declare enum CreatedKind {
     /** Fields the build added to a content type it found (types are shared by every organization of a studio). */
     ContentTypeFields = "content-type-fields",
     SampleImage = "sample-image",
+    /** A stock photo copied into the studio's storage (`media/stock/…`), with its assets row. */
+    StockPhoto = "stock-photo",
     Item = "item",
     DataSource = "data-source",
     Page = "page",
@@ -2918,7 +2968,9 @@ declare enum BuildNoticeCode {
     /** Storage is not configured: sample items get the empty image box, and the run says so. */
     NoStorage = "no-storage",
     /** A content type the build reuses is not public in this studio: the site will not show its items. */
-    ContentTypeNotPublic = "content-type-not-public"
+    ContentTypeNotPublic = "content-type-not-public",
+    /** The stock library could not be read: the picture slots keep the empty box, and the run says so. */
+    StockUnavailable = "stock-unavailable"
 }
 interface BuildNotice {
     code: string;
@@ -2988,6 +3040,7 @@ declare const buildKeys: {
     readonly contentTypeFields: (name: string) => string;
     readonly item: (contentType: string, n: number) => string;
     readonly sampleImage: (n: number) => string;
+    readonly stockPhoto: (libraryKey: string) => string;
     readonly dataSource: (alias: string) => string;
     readonly page: (key: string) => string;
     readonly global: (nodeId: string) => string;
@@ -3052,6 +3105,8 @@ declare enum AiStep {
     NameStructures = "scanNaming"
 }
 declare const AI_STEPS: ReadonlyArray<AiStep>;
+/** Each step's name on the wire (the control plane's `label`, the console) — the screens translate their own. */
+declare const AI_STEP_LABELS: Readonly<Record<AiStep, string>>;
 /** What a model must be able to do for a step to run on it. */
 declare enum AiCapability {
     StructuredOutput = "structuredOutputs",
@@ -3069,6 +3124,8 @@ interface AiTokenCounts {
     cacheWrite: number;
     /** Read from the prompt cache (priced well below input). */
     cacheRead: number;
+    /** Image tokens written (a picture step) — priced at `imageOutput`. */
+    imageOutput?: number;
 }
 /** US dollars per million tokens, per class. A class without a price is priced as input. */
 interface AiTokenPrice {
@@ -3076,6 +3133,8 @@ interface AiTokenPrice {
     output: number;
     cacheWrite?: number;
     cacheRead?: number;
+    /** Image-output tokens; a model without the price is priced at `output`. */
+    imageOutput?: number;
 }
 /** A model of the vetted list (served by the control plane with the entitlements, §3n) — its price travels with it. */
 interface AiModelEntry {
@@ -3173,5 +3232,465 @@ declare enum AiCallStatus {
     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 };
+/**
+ * The structured-output format a model writes a Site Plan in (AI plan §3d step 4, M1-3) — built from the SAME shape
+ * table `validateSitePlan` reads (`SPEC_SITE_PLAN_SHAPE`) and the SAME pattern library, so the plan a model is told
+ * about is the plan the gate refuses. ONE source: a key the table gains breaks this builder until it is written here.
+ *
+ * Two maps of the shape are written as LISTS on the wire, because no strict mode can say "any key": a section's
+ * `slots` (`[{ slot, text }]`, the slot names closed per pattern) and a seed's field values (`values: [{ field,
+ * value }]`). `sitePlanFromWire` turns them back; nothing else differs. Every section is one `anyOf` branch per
+ * pattern — its id, its declared slots, its optional parts, a binding only when it takes one — and the design, the
+ * source and the version are PINNED to the owner's pick and this run (one-value enums), so the provider cannot let
+ * a model change the look. The gate still checks both (`plan.design` deep-equals the pick).
+ */
+declare const SITE_PLAN_SCHEMA_NAME = "site_plan";
+/** The wire keys of the two maps written as lists. */
+declare enum SitePlanWireKey {
+    SlotName = "slot",
+    SlotText = "text",
+    SeedValues = "values",
+    SeedField = "field",
+    SeedValue = "value"
+}
+interface SitePlanSchemaPin {
+    /** The owner's pick, verbatim — every design key becomes a one-value enum. */
+    design: DesignChoices;
+    /** This generation. */
+    source: SitePlanSource;
+}
+/** A content type's field. */
+declare function fieldJsonSchema(): JsonSchema;
+/** A content type, its seed's field values as a list (`values: [{ field, value }]`). */
+declare function contentTypeJsonSchema(): JsonSchema;
+/** A data source: a cms list / single item, or a relative one. */
+declare function dataSourceJsonSchema(): JsonSchema;
+/** The patterns a page section may use (every non-global one), in library order. */
+declare function sectionPatternIds(): string[];
+/** A page section: one branch per pattern. */
+declare function sectionJsonSchema(): JsonSchema;
+/** A page. */
+declare function pageJsonSchema(): JsonSchema;
+/** The Site Plan format, pinned to the owner's pick and this run. */
+declare function sitePlanJsonSchema(pin: SitePlanSchemaPin): JsonSchema;
+/** A section off the wire: its slots back to a map; a key the pattern has nothing for (`{}`) dropped. */
+declare function sectionFromWire(section: unknown): unknown;
+/** A content type off the wire: its seed's `values` list back to field keys. */
+declare function contentTypeFromWire(type: unknown): unknown;
+/**
+ * A model's answer → a Site Plan: the two listed maps back to maps, nothing else touched. Never repairs — whatever the
+ * answer got wrong is still wrong, for `validateSitePlan` to refuse with a path.
+ */
+declare function sitePlanFromWire(wire: unknown): SitePlan | unknown;
+/** The plan → the wire (what a re-ask shows the model, and what the plan edits' prompt carries). */
+declare function sitePlanToWire(plan: SitePlan): PlainObject;
+
+/**
+ * Changing a plan by sentence (AI plan §3d "The Plan prompt box", M1-5; reused by M2 after a build): the CLOSED list
+ * of operations (N-D6) a model may write against the current plan, and the ONE pure `applyPlanEdits` that carries them
+ * out. Nothing is written until Build, so an edit is a plan → plan function; the result goes through
+ * `validateSitePlan` like any plan. Pages are named by `key`, sections by their index on the page. A set of edits is
+ * applied whole or not at all: one edit that cannot apply refuses the set, with a path, and the plan is unchanged.
+ */
+declare enum PlanEditOp {
+    AddPage = "addPage",
+    RemovePage = "removePage",
+    RenamePage = "renamePage",
+    MergePages = "mergePages",
+    /** Its place in the menu (the plan's page order). */
+    MovePage = "movePage",
+    AddSection = "addSection",
+    RemoveSection = "removeSection",
+    MoveSection = "moveSection",
+    SwapPattern = "swapPattern",
+    SetSlot = "setSlot",
+    AddContentType = "addContentType",
+    AddField = "addField",
+    SetSectionData = "setSectionData"
+}
+type PlanEdit = {
+    op: `${PlanEditOp.AddPage}`;
+    page: PagePlan;
+    after?: string;
+} | {
+    op: `${PlanEditOp.RemovePage}`;
+    page: string;
+} | {
+    op: `${PlanEditOp.RenamePage}`;
+    page: string;
+    name?: string;
+    route?: string;
+} | {
+    op: `${PlanEditOp.MergePages}`;
+    into: string;
+    from: string;
+} | {
+    op: `${PlanEditOp.MovePage}`;
+    page: string;
+    to: number;
+} | {
+    op: `${PlanEditOp.AddSection}`;
+    page: string;
+    section: PageSectionPlan;
+    at?: number;
+} | {
+    op: `${PlanEditOp.RemoveSection}`;
+    page: string;
+    index: number;
+} | {
+    op: `${PlanEditOp.MoveSection}`;
+    page: string;
+    from: number;
+    to: number;
+} | {
+    op: `${PlanEditOp.SwapPattern}`;
+    page: string;
+    index: number;
+    pattern: string;
+} | {
+    op: `${PlanEditOp.SetSlot}`;
+    page: string;
+    index: number;
+    slot: string;
+    text: string;
+} | {
+    op: `${PlanEditOp.AddContentType}`;
+    contentType: ContentTypePlan;
+    dataSources?: DataSourcePlan[];
+} | {
+    op: `${PlanEditOp.AddField}`;
+    contentType: string;
+    field: ContentFieldPlan;
+    sample?: string | string[];
+} | {
+    op: `${PlanEditOp.SetSectionData}`;
+    page: string;
+    index: number;
+    binding: string;
+};
+/**
+ * Every op's keys, explained — what the format is built from and what `validatePlanEdits` reads (`key?` optional).
+ * A page is named by its `key`; a section by its 0-based `index` on that page.
+ */
+declare const PLAN_EDIT_SHAPE: Readonly<Record<`${PlanEditOp}`, ShapeEntry>>;
+declare enum PlanChangeKind {
+    Page = "page",
+    Section = "section",
+    ContentType = "contentType",
+    Field = "field",
+    DataSource = "dataSource"
+}
+declare enum PlanChangeAction {
+    Added = "added",
+    Removed = "removed",
+    Changed = "changed",
+    Moved = "moved"
+}
+/** What an edit changed — the Plan map marks it. `index` is the section's index in the RESULT (or before, when removed). */
+interface PlanChange {
+    kind: `${PlanChangeKind}`;
+    action: `${PlanChangeAction}`;
+    page?: string;
+    index?: number;
+    name?: string;
+}
+declare enum PlanEditIssueCode {
+    Shape = "shape",
+    UnknownKey = "unknown-key",
+    Duplicate = "duplicate",
+    UnknownOp = "unknown-op",
+    UnknownPage = "unknown-page",
+    UnknownSection = "unknown-section",
+    UnknownPattern = "unknown-pattern",
+    UnknownSlot = "unknown-slot",
+    UnknownContentType = "unknown-content-type",
+    UnknownDataSource = "unknown-data-source",
+    /** The home page stays (a plan has exactly one). */
+    HomePage = "home-page",
+    /** A template page (one item per route) and a plain page cannot be merged. */
+    MergeTemplate = "merge-template"
+}
+type PlanEditIssue = PathIssue<PlanEditIssueCode>;
+interface PlanEditResult {
+    plan: SitePlan;
+    changed: PlanChange[];
+    /** Non-empty: nothing was applied (`plan` is the input). */
+    issues: PlanEditIssue[];
+}
+/** The edits' structure: a known op, its keys (`PLAN_EDIT_SHAPE`), integers where an index is. Never repairs. */
+declare function validatePlanEdits(edits: unknown): {
+    valid: boolean;
+    issues: PlanEditIssue[];
+};
+/**
+ * Apply a set of edits to a plan — all of them, or none (any issue refuses the set and returns the plan unchanged). The
+ * sources only removed pages and sections read are dropped with them; sources nothing read before are kept.
+ * The result still has to pass `validateSitePlan`.
+ */
+declare function applyPlanEdits(plan: SitePlan, edits: ReadonlyArray<PlanEdit>): PlanEditResult;
+declare const PLAN_EDITS_SCHEMA_NAME = "plan_edits";
+/** A sentence's answer: the edits, or why the ops cannot say it (one line, in the owner's language). */
+declare enum PlanEditsOutcome {
+    Edits = "edits",
+    Cannot = "cannot"
+}
+interface PlanEditsAnswer {
+    outcome: `${PlanEditsOutcome}`;
+    edits: PlanEdit[];
+    /** `cannot`: the one line the owner reads. `edits`: empty. */
+    reason: string;
+}
+/** The answer's own keys, explained. */
+declare const PLAN_EDITS_ANSWER_SHAPE: ShapeEntry;
+/** The format a sentence's answer is written in: the outcome, the edits (one `anyOf` branch per op), the reason. */
+declare function planEditsJsonSchema(): JsonSchema;
+/** A model's answer → edits (sections and content types off the wire); never repaired. */
+declare function planEditsFromWire(answer: unknown): PlanEditsAnswer | unknown;
+
+/**
+ * The plan stage's word checks (AI plan §3d / §3h, M1-3): every text a model WROTE into a plan — the tagline, page
+ * names, section slots, content-type labels, sample values — scanned for the words the owner and their kind of
+ * business must not use (`avoidWords`, the analysis's + the type's `words`), and for a fact the owner never gave
+ * (an email, phone number, price or opening time that is not one of the owner's own facts). A finding is a refusal
+ * with a path — the model rewrites; nothing here repairs a word. Pure.
+ */
+declare enum PlanWordIssueCode {
+    /** A word the owner (or their kind of business) must not use. */
+    AvoidWord = "avoid-word",
+    /** Something that looks like a fact — an email, phone, price or time — that is not one of the owner's facts. */
+    InventedFact = "invented-fact",
+    /** `business.facts` holds a fact the owner did not give, or not in the owner's words. */
+    FactNotTheOwners = "fact-not-the-owners"
+}
+type PlanWordIssue = PathIssue<PlanWordIssueCode>;
+interface PlanWordContext {
+    avoidWords: ReadonlyArray<string>;
+    /** The owner's own facts (the analysis's, as corrected) — the only ones a plan may carry. */
+    facts: Readonly<Partial<Record<FactKey, string>>>;
+}
+/** A text a model wrote, and where. */
+interface WrittenText {
+    path: string;
+    text: string;
+}
+/** Every text in a plan a model writes (never ids, routes, field names or pattern ids). */
+declare function writtenTexts(plan: SitePlan): WrittenText[];
+/** A word (or phrase) as a whole-word pattern; Hebrew allows its one-letter prefixes. */
+declare function wordPattern(word: string): RegExp;
+/** The words to avoid and the facts never given, in every written text of the plan. */
+declare function planWordIssues(plan: SitePlan, ctx: PlanWordContext): PlanWordIssue[];
+
+/**
+ * THE Publishable gate (AI plan §3e, M1-7): ONE pure function over a snapshot of a site — its pages, globals, the
+ * connectors' health, the look's token rows, what a build left to fill — run by the Publish dialog, the builder's
+ * Needs attention and the server on publish (iox-cms refuses with the same findings). Works on any site, generated
+ * or hand-built. Severity is decision D8: an unfilled fact, a policy placeholder or an action that points at nothing
+ * BLOCKS; samples, copy placeholders and stock photos ASK ("Publish anyway"); the rest WARN. Design advice
+ * (harness-core `lintDesign`) is not one of the eight — the caller adds it, and it never blocks.
+ */
+declare enum SiteCheckId {
+    Navigation = "navigation",
+    Forms = "forms",
+    Consent = "consent",
+    Seo = "seo",
+    Facts = "facts",
+    Accessibility = "accessibility",
+    Tokens = "tokens",
+    Actions = "actions"
+}
+/** The eight, in §3e's order. */
+declare const SITE_CHECKS: ReadonlyArray<SiteCheckId>;
+declare enum CheckSeverity {
+    Block = "block",
+    Ask = "ask",
+    Warn = "warn"
+}
+declare enum SiteFindingCode {
+    NoHeader = "no-header",
+    NoPhoneMenu = "no-phone-menu",
+    FormWithoutId = "form-without-id",
+    EmailNeedsMailer = "email-needs-mailer",
+    TrackerWithoutBanner = "tracker-without-banner",
+    NoTitle = "no-title",
+    NoDescription = "no-description",
+    UnfilledFact = "unfilled-fact",
+    CopyPlaceholder = "copy-placeholder",
+    SampleItems = "sample-items",
+    StockPhoto = "stock-photo",
+    NoPrivacyPage = "no-privacy-page",
+    PrivacyPagePlaceholder = "privacy-page-placeholder",
+    LowContrast = "low-contrast",
+    HeadingOrder = "heading-order",
+    ImageWithoutAlt = "image-without-alt",
+    LiteralColour = "literal-colour",
+    DeadLink = "dead-link",
+    DeadDialogTarget = "dead-dialog-target",
+    ActionNeedsConnector = "action-needs-connector"
+}
+/** Each finding's severity — one table (D8), never decided at a call site. */
+declare const FINDING_SEVERITY: Readonly<Record<SiteFindingCode, CheckSeverity>>;
+interface SiteFinding {
+    check: SiteCheckId;
+    severity: CheckSeverity;
+    code: SiteFindingCode;
+    /** In plain words, for the screen. */
+    message: string;
+    pageId?: string;
+    nodeId?: string;
+    /** The global slot (`header` / `footer`) when it is in a global. */
+    owner?: string;
+}
+interface SiteCheck {
+    id: SiteCheckId;
+    passed: boolean;
+    findings: SiteFinding[];
+}
+interface SiteAudit {
+    checks: SiteCheck[];
+    blocking: number;
+    asking: number;
+}
+/** A page as the gate reads it. */
+interface AuditPage {
+    id: string;
+    name: string;
+    route: string;
+    layout: ReadonlyArray<SerializedNode>;
+    seo?: unknown;
+}
+/** A placeholder a build left, and whether the node still shows it (the caller compares the node's text). */
+interface AuditPlaceholder extends ComposedPlaceholder {
+    pageId?: string;
+    filled: boolean;
+}
+interface SiteAuditSnapshot {
+    pages: ReadonlyArray<AuditPage>;
+    globals: ReadonlyArray<SerializedNode>;
+    /** Connector type → usable (configured or provided, and healthy). */
+    connectors: Readonly<Record<string, boolean>>;
+    /** Connector types that set a tracker (a consent category) and are configured. */
+    trackers?: ReadonlyArray<string>;
+    /** The look's token rows and the mode(s) the site wears. */
+    design?: {
+        rows: ReadonlyArray<DesignTokenLike>;
+        modes: ReadonlyArray<'light' | 'dark'>;
+    } | null;
+    placeholders?: ReadonlyArray<AuditPlaceholder>;
+    /** Sample items still in the site (`isSample`). */
+    samples?: ReadonlyArray<{
+        contentType: string;
+        id: string;
+        label?: string;
+    }>;
+    /** Stock photos a build placed that are still on the page. */
+    stock?: ReadonlyArray<{
+        nodeId: string;
+        pageId?: string;
+        owner?: string;
+    }>;
+}
+interface SiteAuditOptions {
+    /** Audit as if only this page were being published (its own page checks + every site-wide one). */
+    pageId?: string;
+}
+/** A route pattern (`/work/:slug`) matches a concrete path (`/work/blue-bowl`). */
+declare function routeMatches(pattern: string, path: string): boolean;
+/** Run the eight checks. `pageId` narrows the page checks to the page being published; site-wide ones always run. */
+declare function auditSite(snapshot: SiteAuditSnapshot, options?: SiteAuditOptions): SiteAudit;
+/** What a publish request must acknowledge: every ASK finding's code (a BLOCK cannot be acknowledged). */
+declare function requiredAcknowledgements(audit: SiteAudit): SiteFindingCode[];
+/** The publish verdict: blocked (never acknowledgeable), needs these acknowledgements, or free to go. */
+declare function publishVerdict(audit: SiteAudit, acknowledged?: ReadonlyArray<string>): {
+    ok: boolean;
+    blocked: boolean;
+    missing: SiteFindingCode[];
+};
+
+/**
+ * Stock photos in a built site (AI plan §3g / §3m, I2): a FREE picture from the platform's curated library, copied
+ * into the studio's own storage (never hot-linked), placed only in an EMPTY picture slot of a section that may show
+ * one — never the owner's work (a collection, a detail page, a gallery: what the nine portfolio types sell is theirs),
+ * never a person (testimonials, the team), never anywhere when the business type says `stock: false`. Its alt text is
+ * the provider's description of what it shows (never a claim), and the credit line its licence requires is placed in
+ * the footer. Pure: the build step does the copying.
+ */
+/** Where a stock photo comes from (the library's provider). */
+declare enum StockProviderId {
+    Magnific = "magnific"
+}
+/** What a picture's licence asks of the site that shows it. */
+interface StockCredit {
+    provider: `${StockProviderId}`;
+    /** The provider's id of the picture. */
+    resourceId: string;
+    /** The provider's page for it. */
+    sourceUrl: string;
+    /** The provider's own title — what the picture shows. */
+    title: string;
+    author: string;
+    /** `freemium` — the free licence (premium pictures never enter the library). */
+    licence: string;
+    licenceUrl: string;
+    /** The words the licence requires, and where they link. */
+    line: string;
+    lineUrl: string;
+}
+/** One picture of the platform library (`iox-stock/<type>/`), as its manifest lists it. */
+interface StockPhoto {
+    /** The library key (`spa/12345.jpg`) — the copy's file name is derived from it. */
+    key: string;
+    /** Where the build downloads it from (the platform bucket). */
+    url: string;
+    /** What it shows, in the provider's words — the alt text. Never a claim. */
+    alt: string;
+    width?: number;
+    height?: number;
+    credit: StockCredit;
+}
+/** The section families a stock photo may stand in for a picture in. */
+declare const STOCK_FAMILIES: ReadonlySet<string>;
+interface StockSlot {
+    /** The Image node the photo goes into. */
+    nodeId: string;
+    /** The page key it lives on. */
+    owner: string;
+    pattern: string;
+}
+/** The empty picture slots of a composed site a stock photo may fill, in page and section order. */
+declare function stockSlots(plan: SitePlan, composed: Pick<ComposedSite, 'pages' | 'placeholders'>): StockSlot[];
+interface StockPlacement extends StockSlot {
+    photo: StockPhoto;
+}
+/** Which photo goes where: the library's photos in order, one per slot, never twice; none when the type says no stock. */
+declare function planStockPhotos(slots: ReadonlyArray<StockSlot>, photos: ReadonlyArray<StockPhoto>, stockAllowed: boolean): StockPlacement[];
+/** A placed photo's copy in the studio's storage: the key the build writes it under. */
+declare function stockCopyKey(photo: Pick<StockPhoto, 'key'>): string;
+/** Put the studio's copy of each photo into its slot (src + the provider's alt). Returns the nodes changed. */
+declare function applyStockPhotos(trees: ReadonlyArray<SerializedNode>, placed: ReadonlyArray<{
+    nodeId: string;
+    url: string;
+    alt: string;
+}>): number;
+/** The credit lines a set of photos needs — one per distinct line (a free Magnific photo: "Designed by Magnific"). */
+declare function stockCreditLines(photos: ReadonlyArray<Pick<StockPhoto, 'credit'>>): Array<{
+    line: string;
+    url: string;
+}>;
+/** The footer node id of a credit line (stable — a build that runs twice finds it). */
+declare const stockCreditNodeId: (index: number) => string;
+/**
+ * The credit line, as the builder would create a Link (a plain node the owner may move or restyle): the licence's words,
+ * linking where it asks, opening in a new tab. Placed at the end of the footer — the place the licence names for a site.
+ */
+declare function stockCreditNode(index: number, credit: {
+    line: string;
+    url: string;
+}): SerializedNode;
+/** Append the credit lines to the footer root (once each). Returns how many it added. */
+declare function addStockCredits(footer: SerializedNode, credits: ReadonlyArray<{
+    line: string;
+    url: string;
+}>): number;
+
+export { ACTIVE_BUILD_STATUSES, AI_REFUSAL_NEXT, AI_REFUSAL_STATUS, AI_STEPS, AI_STEP_LABELS, 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, CheckSeverity, ComposeError, ComposeIssueCode, ContentTypeAction, CreatedKind, DANGLING_LINK_CODES, DEFAULT_PHONE_MENU_BREAKPOINT, ENTRANCE_EASING, ENTRANCE_ORIGIN_LOOK, ENTRANCE_TRIGGER, EntrancePart, FACT_KEYS, FINAL_GENERATION_STAGES, FINDING_SEVERITY, GlobalSlot, JSON_SCHEMA_BANNED_KEYWORDS, JsonSchemaShapeError, KeptReason, NAV_PART_LABELS, NAV_SHAPE_COPY, NEUTRAL_STYLE_PROPS, NODE_BASELINES, NO_TOKENS, NavPagesSource, NavRole, NavShape, NavShapeError, PLAN_EDITS_ANSWER_SHAPE, PLAN_EDITS_SCHEMA_NAME, PLAN_EDIT_SHAPE, PRICING_PATTERN, PUBLISH_BLOCKING_PLACEHOLDERS, PageDataKind, PathIssueCollector, PatternDirective, PatternGlobalPosition, PatternOpens, PatternPlaceholder, PatternRecipe, PhoneMenuBreakpoint, PlaceholderKind, PlanChangeAction, PlanChangeKind, PlanDataSourceMode, PlanDataSourceType, PlanEditIssueCode, PlanEditOp, PlanEditsOutcome, PlanWordIssueCode, PreflightRefusalCode, RelativeOp, SAMPLE_IMAGE_REF, SITE_CHECKS, SITE_FACT_LABELS, SITE_HEADER_PATTERN, SITE_PATTERNS, SITE_PLAN_SCHEMA_NAME, SITE_PLAN_VERSION, SITE_TEMPLATES, SPEC_SITE_FACTS, SPEC_SITE_LIBRARY, SPEC_SITE_PATTERNS, SPEC_SITE_PLAN_SHAPE, SPEC_SITE_TEMPLATES, STOCK_FAMILIES, STUDIO_TEMPLATE, SiteBuildKind, SiteBuildStatus, SiteCheckId, SiteFindingCode, SitePlanError, SitePlanIssueCode, SitePlanSourceKind, SitePlanWireKey, SiteTemplateError, SiteTemplateId, StepState, StockProviderId, addBarItem, addStockCredits, altSourceScopes, applyPlanEdits, applyStockPhotos, assertStyleSlots, assertValidSitePlan, auditSite, barIconForRoute, blocksPublish, buildKeys, buildStepFacts, builtHomePageId, composeNavHeader, composeSection, composeSite, contentTypeFromWire, contentTypeJsonSchema, costUsd, createSerializedNode, creditsOfUsd, dataSourceJsonSchema, describePlanData, describeShapeKey, entranceAction, entranceInteraction, estimateStepCredits, failedBuildStep, fieldJsonSchema, findNavRoot, isActiveBuild, isNonEmptyString, isPlainObject, jsonAnyOf, jsonBoolean, jsonClosedObject, jsonInteger, jsonListOf, jsonOneOf, jsonSchemaKeywords, jsonSchemaObjects, jsonShapedObject, jsonText, modelCanDo, moveBarItem, navPages, navShapeBreakpoint, navShapeOf, nextSourceOf, nodeBindPaths, pageJsonSchema, parseSampleImageRef, pathAt, patternById, patternNeedsBinding, patternNodes, patternOptionalParts, patternScopes, patternSlots, patternTakesBinding, phoneMenuPages, planEditsFromWire, planEditsJsonSchema, planFromTemplate, planNavShape, planStockPhotos, planWordIssues, publishVerdict, releasedLayoutDefaults, removeBarItem, requiredAcknowledgements, requiredShapeKeys, routeMatches, routeParams, sampleImageRef, sectionEntrances, sectionFromWire, sectionJsonSchema, sectionPatternIds, setStyleProps, shapeKeys, siteNavPages, sitePlanFromWire, sitePlanJsonSchema, sitePlanToWire, staggerDelay, stockCopyKey, stockCreditLines, stockCreditNode, stockCreditNodeId, stockSlots, validatePlanEdits, validateSitePlan, walkSerialized, wordPattern, writtenTexts };
+export type { AddBarItemResult, AiMeter, AiModelEntry, AiRefusal, AiTokenCounts, AiTokenPrice, AuditPage, AuditPlaceholder, BarItemsEditResult, BuildNotice, BuildStepError, BuildStepFacts, BuildStepRecord, CmsDataSourcePlan, ComposeContext, ComposeIssue, ComposedDataSource, ComposedItem, ComposedNavHeader, ComposedPage, ComposedPlaceholder, ComposedRoute, ComposedSection, ComposedSite, ContentFieldPlan, ContentSeedPlan, ContentTypePlan, CreateNodeOptions, CreatedRecord, DataSourcePlan, DynamicKeysAsList, EntranceAction, EntranceInteraction, EntranceSpec, FactKey, JsonSchema, NavHeaderInput, NavHeaderOptions, NavPage, NavShapeOptions, NavShapeResult, NodeBaseline, PageData, PageDataLine, PagePlan, PageSectionPlan, PathIssue, PatternNode, PlainObject, PlanChange, PlanEdit, PlanEditIssue, PlanEditResult, PlanEditsAnswer, PlanWordContext, PlanWordIssue, PreflightRefusal, RelativeDataSourcePlan, SectionEntrances, SectionInput, SectionOptions, SerializedBinding, SerializedNode, SerializedResponsive, ShapeEntry, ShapeIssueCodes, SiteAudit, SiteAuditOptions, SiteAuditSnapshot, SiteBuildRun, SiteBusiness, SiteCheck, SiteFinding, SitePageRef, SitePattern, SitePlan, SitePlanIssue, SitePlanSchemaPin, SitePlanSource, SitePlanValidation, SiteTemplate, StockCredit, StockPhoto, StockPlacement, StockSlot, TemplatePlanInput, UndoKept, UndoPreview, UndoRecord, WrittenText };