@vectoriox/iox-ui 5.56.1 → 5.57.0

package/generation-core/index.d.ts

@@ -3205,6 +3205,24 @@ interface AiMeter {
     periodStart: string;
     periodEnd: string;
 }
+/** The plan entitlements AI reads (the control plane's `features` / `limits` keys) — ONE spelling. */
+declare enum AiFeature {
+    SiteGeneration = "aiSiteGeneration"
+}
+declare enum AiLimit {
+    CreditsPerMonth = "aiCreditsPerMonth",
+    CreditsPerGeneration = "aiCreditsPerGeneration"
+}
+/** `GET …/ai/entitlements` — the plan as the studio last heard it (`known: false` = never), its features, the credits. */
+interface AiEntitlementsView {
+    known: boolean;
+    /** Where the answer came from (the control plane, last known, or local development). */
+    source?: string;
+    planName?: string;
+    features?: Record<string, boolean>;
+    limits?: Record<string, number>;
+    meter: AiMeter | null;
+}
 /** A generation's stages (§3d). The runner works while `task` is set; otherwise the owner has the next move. */
 declare enum AiGenerationStage {
     Reading = "reading",
@@ -3597,8 +3615,26 @@ interface SiteAuditOptions {
 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;
+/** Why the server refused a publish (409) — the dialog the client opens from the findings it carries. */
+declare enum PublishRefusalCode {
+    /** A block nothing lifts (a blank fact, a policy placeholder, a dead action). */
+    Blocked = "site.publishBlocked",
+    /** Asks the request must acknowledge, by code (`publishAcknowledged`). */
+    NeedsAck = "site.publishNeedsAck"
+}
+/** The body of a refused publish. */
+interface PublishRefusal {
+    code: `${PublishRefusalCode}`;
+    message: string;
+    /** The findings the refusal is about (blocks, or the asks still unacknowledged). */
+    findings: SiteFinding[];
+    /** For `needsAck`: the codes the request must acknowledge. */
+    missing?: SiteFindingCode[];
+}
 /** What a publish request must acknowledge: every ASK finding's code (a BLOCK cannot be acknowledged). */
 declare function requiredAcknowledgements(audit: SiteAudit): SiteFindingCode[];
+/** The refusal a publish gets for an audit and its acknowledgements — or null: it may go (the server's ONE rule). */
+declare function publishRefusal(audit: SiteAudit, acknowledged?: ReadonlyArray<string>): PublishRefusal | null;
 /** The publish verdict: blocked (never acknowledgeable), needs these acknowledgements, or free to go. */
 declare function publishVerdict(audit: SiteAudit, acknowledged?: ReadonlyArray<string>): {
     ok: boolean;
@@ -3692,5 +3728,5 @@ declare function addStockCredits(footer: SerializedNode, credits: ReadonlyArray<
     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 };
+export { ACTIVE_BUILD_STATUSES, AI_REFUSAL_NEXT, AI_REFUSAL_STATUS, AI_STEPS, AI_STEP_LABELS, AI_STEP_NEEDS, AI_STEP_TYPICAL_TOKENS, AiCallStatus, AiCapability, AiFeature, AiGenerationStage, AiKeyMode, AiLimit, 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, PublishRefusalCode, 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, publishRefusal, 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, AiEntitlementsView, 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, PublishRefusal, 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 };

package/harness-core/index.d.ts

@@ -1,5 +1,5 @@
 import { MotionId, MoodId, TintId, DensityId, DesignMotion, DesignChoices, DesignMode, StylePreset, ShapeId, AnimateId } from '@vectoriox/iox-ui/design-core';
-import { FactKey, PathIssue, JsonSchema, SiteTemplate, ShapeEntry, AiGenerationStage, AiStep, SitePlan, PlanEdit, PlanChange } from '@vectoriox/iox-ui/generation-core';
+import { FactKey, PathIssue, JsonSchema, SiteTemplate, ShapeEntry, AiGenerationStage, AiStep, SitePlan, PlanEdit, PlanChange, SiteAudit } from '@vectoriox/iox-ui/generation-core';
 export { JsonSchema } from '@vectoriox/iox-ui/generation-core';
 
 declare const SPEC_HARNESS_SOURCE: {
@@ -2738,6 +2738,8 @@ interface ReferenceSeed {
     used: boolean;
     /** The modes the reference colour failed in (empty when used, or when there is no reference). */
     failsIn: Array<'light' | 'dark'>;
+    /** Information only: the RAW reference colour against the style's page ground (its first mode); null without one. */
+    rawRatio: number | null;
 }
 /** Every mode `presetId` offers passes the audit with `seed`. */
 declare function seedPassesPreset(presetId: string, seed: string): {
@@ -2961,7 +2963,11 @@ declare const GENERATION_LIMITS: {
  * references — the best-ranked style with the reference colour as its seed when that colour passes AA in every mode
  * the style offers (`referenceSeed`). Pure.
  */
-/** A preset for this business: its choices, Motion from the business (`motionFor`), what the owner already set kept. */
+/**
+ * A preset for this business: its choices, Motion from the business (`motionFor`), the references' colour as its seed
+ * when that colour passes AA in every mode the preset offers (`referenceSeed` — judged as used), and what the owner
+ * already set kept. The ONE rule for a Look pick and for Build with these.
+ */
 declare function presetDesign(presetId: string, input: MotionInput | string | null, kept?: Partial<Pick<DesignChoices, 'scroll' | 'animate' | 'between' | 'motion'>>, read?: StyleRead | null): DesignChoices | null;
 interface StartingDesign {
     presetId: string;
@@ -2972,5 +2978,14 @@ interface StartingDesign {
 /** The look a business starts from: its best-ranked style (with the references' boost), at its defaults. */
 declare function startingDesign(input: (RankInput & MotionInput) | string | null, read?: StyleRead | null): StartingDesign | null;
 
+/**
+ * `GET …/webbuilder/site-audit?page=` (AI plan §3e, M1-7): the eight checks (generation-core `auditSite`) and the design
+ * advice beside them (`lintDesign` — never blocks, "Keep it" dismisses). ONE definition: iox-cms answers it, the Publish
+ * dialog and Needs attention read it.
+ */
+type SiteAuditView = SiteAudit & {
+    advice: LintFinding[];
+};
+
 export { ANIMATE_ADVICE_STEPS, AnalysisIssueCode, AnalysisLocale, AvoidCheck, BUSINESS_TYPES, BUSINESS_TYPE_IDS, BookingNeed, COPY_LENGTH_ORDER, CopyLength, GENERATION_LIMITS, HARNESS_SOURCE, LITTLE_MOVEMENT_AVOID, LITTLE_MOVEMENT_CAP, LintKind, MAX_ANALYSIS_MOODS, MAX_PIXEL_SAMPLES, MAX_READ_PICTURES, NEEDS, NEED_IDS, NeedSource, PALETTE_SIZE, PALETTE_THRESHOLDS, PictureRole, PlanChangeOutcome, PresetFit, RANK_WEIGHTS, READING_SHAPE, READ_ANIMATE, READ_WEIGHTS, RankReason, ReaderState, ReadingIssueCode, SITE_ANALYSIS_SCHEMA_NAME, SITE_READING_SCHEMA_NAME, SPEC_ANALYSIS_SHAPE, SPEC_BUSINESS_TYPES, SPEC_HARNESS_EXAMPLES, SPEC_HARNESS_SOURCE, SPEC_NEEDS, SPEC_STRUCTURES, SPEC_USER_AVOIDS, STRUCTURES, SiteReadRefusal, StyleReadGround, StyleReadHeadings, StyleReadMotion, StyleReadSourceKind, USER_AVOID_IDS, VoiceFormality, VoicePerson, addressesIn, analysisPromptContext, businessTypeById, calmerChoice, decodeSiteReading, inferNeeds, isLookRule, lintDesign, lookMatches, mapStyleRead, matchBusinessType, matchBusinessTypes, measurePalette, mergeStyleReads, motionAdvice, motionFor, normalizeAddress, oklchHue, paletteBrand, paletteGround, paletteSamples, pictureStyleRead, pixelSamples, presetDesign, presetHasSerifHeadings, presetLook, presetReason, rankStylePresets, rankWithReferences, readPalette, referenceSeed, seedPassesPreset, siteAnalysisJsonSchema, siteReadingJsonSchema, startingDesign, structureFor, userAvoidRule, validateSiteAnalysis, validateSiteReading, withoutAddress };
-export type { AiGenerationView, AnalysisContext, AnalysisIssue, AnalysisValidation, AvoidRule, BusinessType, BusinessTypeMatch, CheckRule, ColourSample, FactRead, GenerationFileView, GenerationReadersView, GenerationStartRequest, GoodFit, LintFinding, LintSite, LookCondition, LookDesign, LookRule, MeasuredPicture, MotionBasis, MotionInput, MotionStart, NeedDef, NeedId, PaletteColour, PaletteReading, PictureStyle, PlanRevisionView, PromptContext, PromptContextOptions, PromptSection, RankInput, RankedPreset, ReadingIssue, ReferenceSeed, SiteAnalysis, SiteNeed, SiteReaderView, SiteReading, StartingDesign, StructureChoice, StructureId, StyleHints, StyleRead, UserAvoidId };
+export type { AiGenerationView, AnalysisContext, AnalysisIssue, AnalysisValidation, AvoidRule, BusinessType, BusinessTypeMatch, CheckRule, ColourSample, FactRead, GenerationFileView, GenerationReadersView, GenerationStartRequest, GoodFit, LintFinding, LintSite, LookCondition, LookDesign, LookRule, MeasuredPicture, MotionBasis, MotionInput, MotionStart, NeedDef, NeedId, PaletteColour, PaletteReading, PictureStyle, PlanRevisionView, PromptContext, PromptContextOptions, PromptSection, RankInput, RankedPreset, ReadingIssue, ReferenceSeed, SiteAnalysis, SiteAuditView, SiteNeed, SiteReaderView, SiteReading, StartingDesign, StructureChoice, StructureId, StyleHints, StyleRead, UserAvoidId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.56.1",
+  "version": "5.57.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/generation-core/ai-run.ts

@@ -194,6 +194,27 @@ export interface AiMeter {
     periodEnd: string;
 }
 
+/** The plan entitlements AI reads (the control plane's `features` / `limits` keys) — ONE spelling. */
+export enum AiFeature {
+    SiteGeneration = 'aiSiteGeneration',
+}
+
+export enum AiLimit {
+    CreditsPerMonth = 'aiCreditsPerMonth',
+    CreditsPerGeneration = 'aiCreditsPerGeneration',
+}
+
+/** `GET …/ai/entitlements` — the plan as the studio last heard it (`known: false` = never), its features, the credits. */
+export interface AiEntitlementsView {
+    known: boolean;
+    /** Where the answer came from (the control plane, last known, or local development). */
+    source?: string;
+    planName?: string;
+    features?: Record<string, boolean>;
+    limits?: Record<string, number>;
+    meter: AiMeter | null;
+}
+
 /** A generation's stages (§3d). The runner works while `task` is set; otherwise the owner has the next move. */
 export enum AiGenerationStage {
     Reading = 'reading',

package/src/generation-core/audit-site.ts

@@ -373,11 +373,43 @@ export function auditSite(snapshot: SiteAuditSnapshot, options: SiteAuditOptions
     };
 }
 
+/** Why the server refused a publish (409) — the dialog the client opens from the findings it carries. */
+export enum PublishRefusalCode {
+    /** A block nothing lifts (a blank fact, a policy placeholder, a dead action). */
+    Blocked = 'site.publishBlocked',
+    /** Asks the request must acknowledge, by code (`publishAcknowledged`). */
+    NeedsAck = 'site.publishNeedsAck',
+}
+
+/** The body of a refused publish. */
+export interface PublishRefusal {
+    code: `${PublishRefusalCode}`;
+    message: string;
+    /** The findings the refusal is about (blocks, or the asks still unacknowledged). */
+    findings: SiteFinding[];
+    /** For `needsAck`: the codes the request must acknowledge. */
+    missing?: SiteFindingCode[];
+}
+
 /** What a publish request must acknowledge: every ASK finding's code (a BLOCK cannot be acknowledged). */
 export function requiredAcknowledgements(audit: SiteAudit): SiteFindingCode[] {
     return [...new Set(audit.checks.flatMap(c => c.findings).filter(f => f.severity === CheckSeverity.Ask).map(f => f.code))];
 }
 
+/** The refusal a publish gets for an audit and its acknowledgements — or null: it may go (the server's ONE rule). */
+export function publishRefusal(audit: SiteAudit, acknowledged: ReadonlyArray<string> = []): PublishRefusal | null {
+    const verdict = publishVerdict(audit, acknowledged);
+    if (verdict.ok) return null;
+    const findings = audit.checks.flatMap(c => c.findings);
+    if (verdict.blocked) {
+        return { code: PublishRefusalCode.Blocked, message: 'This page cannot go live yet — fill in what is marked first', findings: findings.filter(f => f.severity === CheckSeverity.Block) };
+    }
+    return {
+        code: PublishRefusalCode.NeedsAck, message: 'Publish anyway? Some parts are still samples or placeholders',
+        findings: findings.filter(f => f.severity === CheckSeverity.Ask && verdict.missing.includes(f.code)), missing: verdict.missing,
+    };
+}
+
 /** The publish verdict: blocked (never acknowledgeable), needs these acknowledgements, or free to go. */
 export function publishVerdict(audit: SiteAudit, acknowledged: ReadonlyArray<string> = []): { ok: boolean; blocked: boolean; missing: SiteFindingCode[] } {
     const missing = requiredAcknowledgements(audit).filter(code => !acknowledged.includes(code));

package/src/harness-core/public-api.ts

@@ -23,3 +23,4 @@ export * from './reference-colour';
 export * from './site-reading';
 export * from './generation-view';
 export * from './starting-design';
+export * from './site-audit-view';

package/src/harness-core/reference-colour.ts

@@ -1,4 +1,4 @@
-import { auditDesignContrast, designTokenRows, parseHexColor, presetChoices, stylePresetById } from '@vectoriox/iox-ui/design-core';
+import { auditDesignContrast, designTokenRows, parseHexColor, presetChoices, resolveTokenValues, stylePresetById, wcagContrastRatio } from '@vectoriox/iox-ui/design-core';
 import type { DesignChoices } from '@vectoriox/iox-ui/design-core';
 
 import { StyleRead } from './rank';
@@ -21,6 +21,17 @@ export interface ReferenceSeed {
     used: boolean;
     /** The modes the reference colour failed in (empty when used, or when there is no reference). */
     failsIn: Array<'light' | 'dark'>;
+    /** Information only: the RAW reference colour against the style's page ground (its first mode); null without one. */
+    rawRatio: number | null;
+}
+
+/** The raw colour's ratio against the preset's own page ground, in its first mode — shown, never decisive. */
+function rawRatioOf(presetId: string, hex: string): number | null {
+    const preset = stylePresetById(presetId);
+    const choices = preset ? presetChoices(preset.id, preset.modes[0]) : null;
+    if (!preset || !choices) return null;
+    const ground = resolveTokenValues(designTokenRows(choices), preset.modes[0])['page-bg'];
+    return ground && parseHexColor(ground) ? Math.round(wcagContrastRatio(hex, ground) * 100) / 100 : null;
 }
 
 /** Every mode `presetId` offers passes the audit with `seed`. */
@@ -39,7 +50,8 @@ export function referenceSeed(read: Pick<StyleRead, 'brand'> | null | undefined,
     const preset = stylePresetById(presetId);
     if (!preset) return null;
     const reference = read?.brand && parseHexColor(read.brand) ? read.brand : null;
-    if (!reference) return { seed: preset.seed, reference: null, used: false, failsIn: [] };
+    if (!reference) return { seed: preset.seed, reference: null, used: false, failsIn: [], rawRatio: null };
     const { passes, failsIn } = seedPassesPreset(preset.id, reference);
-    return passes ? { seed: reference, reference, used: true, failsIn: [] } : { seed: preset.seed, reference, used: false, failsIn };
+    const rawRatio = rawRatioOf(preset.id, reference);
+    return passes ? { seed: reference, reference, used: true, failsIn: [], rawRatio } : { seed: preset.seed, reference, used: false, failsIn, rawRatio };
 }

package/src/harness-core/site-audit-view.ts

@@ -0,0 +1,10 @@
+import type { SiteAudit } from '@vectoriox/iox-ui/generation-core';
+
+import type { LintFinding } from './lint';
+
+/**
+ * `GET …/webbuilder/site-audit?page=` (AI plan §3e, M1-7): the eight checks (generation-core `auditSite`) and the design
+ * advice beside them (`lintDesign` — never blocks, "Keep it" dismisses). ONE definition: iox-cms answers it, the Publish
+ * dialog and Needs attention read it.
+ */
+export type SiteAuditView = SiteAudit & { advice: LintFinding[] };

package/src/harness-core/starting-design.ts

@@ -12,7 +12,11 @@ import { referenceSeed } from './reference-colour';
  * the style offers (`referenceSeed`). Pure.
  */
 
-/** A preset for this business: its choices, Motion from the business (`motionFor`), what the owner already set kept. */
+/**
+ * A preset for this business: its choices, Motion from the business (`motionFor`), the references' colour as its seed
+ * when that colour passes AA in every mode the preset offers (`referenceSeed` — judged as used), and what the owner
+ * already set kept. The ONE rule for a Look pick and for Build with these.
+ */
 export function presetDesign(
     presetId: string,
     input: MotionInput | string | null,
@@ -23,7 +27,8 @@ export function presetDesign(
     if (!base) return null;
     const motionInput: MotionInput = typeof input === 'object' && input !== null ? input : { businessType: input as string | null };
     const start = motionFor(motionInput, presetId, read);
-    return { ...base, scroll: start.scroll, animate: start.animate, between: start.between, ...kept };
+    const seed = referenceSeed(read, presetId);
+    return { ...base, ...(seed?.used ? { seed: seed.seed } : {}), scroll: start.scroll, animate: start.animate, between: start.between, ...kept };
 }
 
 export interface StartingDesign {
@@ -39,6 +44,5 @@ export function startingDesign(input: (RankInput & MotionInput) | string | null,
     const top = rankWithReferences(rankInput, read)[0];
     const design = top ? presetDesign(top.id, rankInput, {}, read) : null;
     if (!top || !design) return null;
-    const seed = referenceSeed(read, top.id);
-    return seed?.used ? { presetId: top.id, design: { ...design, seed: seed.seed }, referenceColour: true } : { presetId: top.id, design, referenceColour: false };
+    return { presetId: top.id, design, referenceColour: !!referenceSeed(read, top.id)?.used };
 }