@vectoriox/iox-ui 5.49.0 → 5.50.0

package/generation-core/index.d.ts

@@ -2815,5 +2815,195 @@ interface PageData {
 /** One entry per page of the plan, in plan order. */
 declare function describePlanData(plan: SitePlan): PageData[];
 
-export { BAR_ITEMS_MAX, BAR_ITEMS_MIN, BASELINE_ROLES, BaselineRole, BindScope, CardBindTarget, ComposeError, ComposeIssueCode, DANGLING_LINK_CODES, DEFAULT_PHONE_MENU_BREAKPOINT, ENTRANCE_EASING, ENTRANCE_ORIGIN_LOOK, ENTRANCE_TRIGGER, EntrancePart, FACT_KEYS, GlobalSlot, 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, 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, SitePlanError, SitePlanIssueCode, SitePlanSourceKind, SiteTemplateError, SiteTemplateId, addBarItem, altSourceScopes, assertStyleSlots, assertValidSitePlan, barIconForRoute, blocksPublish, composeNavHeader, composeSection, composeSite, createSerializedNode, describePlanData, entranceAction, entranceInteraction, findNavRoot, 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, CmsDataSourcePlan, ComposeContext, ComposeIssue, ComposedDataSource, ComposedItem, ComposedNavHeader, ComposedPage, ComposedPlaceholder, ComposedRoute, ComposedSection, ComposedSite, ContentFieldPlan, ContentSeedPlan, ContentTypePlan, CreateNodeOptions, DataSourcePlan, EntranceAction, EntranceInteraction, EntranceSpec, FactKey, NavHeaderInput, NavHeaderOptions, NavPage, NavShapeOptions, NavShapeResult, NodeBaseline, PageData, PageDataLine, PagePlan, PageSectionPlan, PathIssue, PatternNode, PlainObject, RelativeDataSourcePlan, SectionEntrances, SectionInput, SectionOptions, SerializedBinding, SerializedNode, SerializedResponsive, ShapeEntry, ShapeIssueCodes, SiteBusiness, SitePageRef, SitePattern, SitePlan, SitePlanIssue, SitePlanSource, SitePlanValidation, SiteTemplate, TemplatePlanInput };
+/**
+ * A site build's WIRE vocabulary (AI plan §3b, W2): what iox-cms's `site-builds` API answers and what every
+ * client of it reads — the run's statuses and steps, what it created, why Undo kept something, the preflight's
+ * refusals, and the one spelling of each document's `buildKey`. ONE definition: iox-cms stores and answers it,
+ * the website wizard (W3) polls it. Pure types, enums and helpers; no transport.
+ */
+declare enum SiteBuildKind {
+    Build = "build"
+}
+declare enum SiteBuildStatus {
+    Running = "running",
+    Done = "done",
+    Failed = "failed",
+    Undoing = "undoing",
+    Undone = "undone"
+}
+/** The statuses a runner advances — and the ones that hold the org's single-run slot. */
+declare const ACTIVE_BUILD_STATUSES: ReadonlyArray<SiteBuildStatus>;
+/** The steps of a build, in the order they run. */
+declare enum BuildStep {
+    Preflight = "preflight",
+    ContentTypes = "content-types",
+    SampleImages = "sample-images",
+    Items = "items",
+    DataSources = "data-sources",
+    Pages = "pages",
+    Globals = "globals",
+    Look = "look"
+}
+declare const BUILD_STEPS: ReadonlyArray<BuildStep>;
+declare enum StepState {
+    Wait = "wait",
+    Run = "run",
+    Done = "done",
+    Failed = "failed"
+}
+/** What a build creates, as Undo walks it. */
+declare enum CreatedKind {
+    ContentType = "content-type",
+    SampleImage = "sample-image",
+    Item = "item",
+    DataSource = "data-source",
+    Page = "page",
+    Global = "global",
+    Look = "look"
+}
+/** Why Undo left something in place. */
+declare enum KeptReason {
+    Edited = "edited",
+    Published = "published",
+    InUse = "in-use"
+}
+interface BuildStepError {
+    code: string;
+    detail: string;
+}
+interface BuildStepRecord {
+    key: BuildStep;
+    state: StepState;
+    attempts: number;
+    startedAt?: Date | string;
+    finishedAt?: Date | string;
+    error?: BuildStepError;
+}
+interface CreatedRecord {
+    kind: CreatedKind;
+    /** The document id — a page / item / content-type `_id`, a data-source alias, a global node id, a storage key. */
+    id: string;
+    buildKey: string;
+    /** sha256 of the document as the build left it. */
+    fingerprint: string;
+    /** An item's content type. */
+    contentType?: string;
+    /** A sample image's public URL — what items and pages reference. */
+    url?: string;
+}
+interface UndoKept {
+    kind: CreatedKind;
+    id: string;
+    reason: KeptReason;
+    /** In plain words, for the screen ("About", "Sample project 2"). */
+    label?: string;
+}
+interface UndoRecord {
+    at: Date | string;
+    removed: number;
+    kept: UndoKept[];
+    /** The undo steps already done (kinds), so a resumed undo does not redo them. */
+    done: CreatedKind[];
+    finishedAt?: Date | string;
+    /** What stopped the undo — DELETE again carries on from the kind it stopped at. */
+    error?: BuildStepError;
+}
+declare enum BuildNoticeCode {
+    /** Storage is not configured: sample items get the empty image box, and the run says so. */
+    NoStorage = "no-storage"
+}
+interface BuildNotice {
+    code: string;
+    detail: string;
+}
+/** The run as `GET …/site-builds/:id` (and `?latest=1`) answers it. */
+interface SiteBuildRun {
+    _id: string;
+    organization: string;
+    kind: SiteBuildKind;
+    source: SitePlanSource;
+    plan: SitePlan;
+    year: number;
+    status: SiteBuildStatus;
+    active?: boolean;
+    steps: BuildStepRecord[];
+    created: CreatedRecord[];
+    placeholders: ComposedPlaceholder[];
+    issues: ComposeIssue[];
+    notices?: BuildNotice[];
+    requestedBy: string;
+    startedAt: Date | string;
+    finishedAt?: Date | string;
+    undo?: UndoRecord;
+}
+/** `GET …/site-builds/:id/undo`: what an Undo would remove and keep — never guessed in the browser. */
+interface UndoPreview {
+    removes: Partial<Record<CreatedKind, number>>;
+    kept: UndoKept[];
+    restoresGlobals: string[];
+    revertsLook: boolean;
+}
+declare enum PreflightRefusalCode {
+    /** The Site Plan itself is invalid (`validateSitePlan`); `issue` is the validator's code. */
+    InvalidPlan = "invalid-plan",
+    /** A route the plan wants is already a page of this organization. */
+    RouteTaken = "route-taken",
+    /** A content type of that name exists in this instance (content types are instance-wide). */
+    ContentTypeTaken = "content-type-taken",
+    /** The name may not be a content type (a platform collection, or not a valid name). */
+    ContentTypeName = "content-type-name",
+    /** Content types act on the whole instance: only the instance owner may create them (SEC1). */
+    ContentTypesNeedInstanceOwner = "content-types-need-instance-owner",
+    /** The org library holds the alias with a different definition. */
+    DataSourceConflict = "data-source-conflict",
+    /** The studio has pages AND a header/footer: replace or keep them is the caller's choice (D7). */
+    GlobalsNeedDecision = "globals-need-decision",
+    /** A global the plan adds has the id of one the studio keeps. */
+    GlobalTaken = "global-taken"
+}
+interface PreflightRefusal {
+    code: PreflightRefusalCode;
+    /** Where, as a dotted path into the plan. */
+    path: string;
+    detail: string;
+    /** For `invalid-plan`: the validator's issue code. */
+    issue?: SitePlanIssueCode;
+}
+/**
+ * The stable key each written document carries beside `siteBuildId`: a step that runs twice looks it up first and
+ * skips what exists (so a restart or a Retry continues without duplicates), and a reader finds what the run made
+ * by it — the wizard opens the HOME page by `page(<its key>)`. One builder per kind.
+ */
+declare const buildKeys: {
+    readonly contentType: (name: string) => string;
+    readonly item: (contentType: string, n: number) => string;
+    readonly sampleImage: (n: number) => string;
+    readonly dataSource: (alias: string) => string;
+    readonly page: (key: string) => string;
+    readonly global: (nodeId: string) => string;
+    readonly look: () => string;
+};
+/** The id of the page a run made for the plan's home page, or null (not made yet, or no home page). */
+declare function builtHomePageId(run: Pick<SiteBuildRun, 'plan' | 'created'> | null | undefined): string | null;
+/** The step a run stopped at, or null. */
+declare function failedBuildStep(run: Pick<SiteBuildRun, 'steps'> | null | undefined): BuildStepRecord | null;
+/** A run still holding the org's slot (building or undoing) — a page that left it comes back to its progress. */
+declare function isActiveBuild(run: Pick<SiteBuildRun, 'status'> | null | undefined): boolean;
+/** What each step of a build of `plan` will make — the progress rows' words, from the plan alone. */
+interface BuildStepFacts {
+    /** Content types to create: their labels. */
+    contentTypes: string[];
+    /** Sample items, all types together. */
+    items: number;
+    /** Pages (template pages included) and their routes. */
+    pages: number;
+    routes: string[];
+    /** Links in the menu (pages `inNav`). */
+    navLinks: number;
+    /** The look's flavor. */
+    flavorId: string;
+}
+declare function buildStepFacts(plan: SitePlan): BuildStepFacts;
+
+export { ACTIVE_BUILD_STATUSES, BAR_ITEMS_MAX, BAR_ITEMS_MIN, BASELINE_ROLES, BUILD_STEPS, BaselineRole, BindScope, BuildNoticeCode, BuildStep, CardBindTarget, ComposeError, ComposeIssueCode, 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 };

package/harness-core/index.d.ts

@@ -1,5 +1,5 @@
 import { MotionId, MoodId, TintId, DensityId, DesignMotion, DesignChoices, DesignMode, StylePreset, AnimateId, ShapeId } from '@vectoriox/iox-ui/design-core';
-import { FactKey, PathIssue } from '@vectoriox/iox-ui/generation-core';
+import { FactKey, PathIssue, SiteTemplate } from '@vectoriox/iox-ui/generation-core';
 
 declare const SPEC_HARNESS_SOURCE: {
     readonly repo: "nextlevelbuilder/ui-ux-pro-max-skill";
@@ -2513,5 +2513,20 @@ declare function addressesIn(text: string): string[];
 /** The words without one address (removing its chip): every spelling of it, and the space it leaves. */
 declare function withoutAddress(text: string, address: string): string;
 
-export { ANIMATE_ADVICE_STEPS, AnalysisIssueCode, AnalysisLocale, AvoidCheck, BUSINESS_TYPES, BUSINESS_TYPE_IDS, BookingNeed, COPY_LENGTH_ORDER, CopyLength, HARNESS_SOURCE, LITTLE_MOVEMENT_AVOID, LITTLE_MOVEMENT_CAP, LintKind, MAX_ANALYSIS_MOODS, NEEDS, NEED_IDS, NeedSource, PresetFit, RANK_WEIGHTS, READ_ANIMATE, READ_WEIGHTS, RankReason, SPEC_ANALYSIS_SHAPE, SPEC_BUSINESS_TYPES, SPEC_HARNESS_EXAMPLES, SPEC_HARNESS_SOURCE, SPEC_NEEDS, SPEC_STRUCTURES, SPEC_USER_AVOIDS, STRUCTURES, StyleReadGround, StyleReadHeadings, StyleReadMotion, StyleReadSourceKind, USER_AVOID_IDS, VoiceFormality, VoicePerson, addressesIn, analysisPromptContext, businessTypeById, calmerChoice, inferNeeds, isLookRule, lintDesign, lookMatches, mapStyleRead, matchBusinessType, matchBusinessTypes, motionAdvice, motionFor, normalizeAddress, oklchHue, presetHasSerifHeadings, presetLook, rankStylePresets, rankWithReferences, userAvoidRule, validateSiteAnalysis, withoutAddress };
-export type { AnalysisContext, AnalysisIssue, AnalysisValidation, AvoidRule, BusinessType, BusinessTypeMatch, CheckRule, FactRead, GoodFit, LintFinding, LintSite, LookCondition, LookDesign, LookRule, MotionBasis, MotionInput, MotionStart, NeedDef, NeedId, PromptContext, PromptContextOptions, PromptSection, RankInput, RankedPreset, SiteAnalysis, SiteNeed, StructureId, StyleHints, StyleRead, UserAvoidId };
+/** The structure a kind of business is built from, and the template the wizard can build TODAY. */
+interface StructureChoice {
+    /** The business type's own structure (Studio · Practice · Place). */
+    structure: StructureId;
+    /** The template that will be built. */
+    template: SiteTemplate;
+    /** The type's structure has no template yet (L0-4), so the Studio template stands in. */
+    fallback: boolean;
+}
+/**
+ * Which template the template path (and the plan stage) builds a kind of business from (AI plan rev 3 §3d,
+ * N-D3): its structure's template when that one has shipped, else Studio — said, never silent. No type → Studio.
+ */
+declare function structureFor(typeId: string | null | undefined): StructureChoice;
+
+export { ANIMATE_ADVICE_STEPS, AnalysisIssueCode, AnalysisLocale, AvoidCheck, BUSINESS_TYPES, BUSINESS_TYPE_IDS, BookingNeed, COPY_LENGTH_ORDER, CopyLength, HARNESS_SOURCE, LITTLE_MOVEMENT_AVOID, LITTLE_MOVEMENT_CAP, LintKind, MAX_ANALYSIS_MOODS, NEEDS, NEED_IDS, NeedSource, PresetFit, RANK_WEIGHTS, READ_ANIMATE, READ_WEIGHTS, RankReason, SPEC_ANALYSIS_SHAPE, SPEC_BUSINESS_TYPES, SPEC_HARNESS_EXAMPLES, SPEC_HARNESS_SOURCE, SPEC_NEEDS, SPEC_STRUCTURES, SPEC_USER_AVOIDS, STRUCTURES, StyleReadGround, StyleReadHeadings, StyleReadMotion, StyleReadSourceKind, USER_AVOID_IDS, VoiceFormality, VoicePerson, addressesIn, analysisPromptContext, businessTypeById, calmerChoice, inferNeeds, isLookRule, lintDesign, lookMatches, mapStyleRead, matchBusinessType, matchBusinessTypes, motionAdvice, motionFor, normalizeAddress, oklchHue, presetHasSerifHeadings, presetLook, rankStylePresets, rankWithReferences, structureFor, userAvoidRule, validateSiteAnalysis, withoutAddress };
+export type { AnalysisContext, AnalysisIssue, AnalysisValidation, AvoidRule, BusinessType, BusinessTypeMatch, CheckRule, FactRead, GoodFit, LintFinding, LintSite, LookCondition, LookDesign, LookRule, MotionBasis, MotionInput, MotionStart, NeedDef, NeedId, PromptContext, PromptContextOptions, PromptSection, RankInput, RankedPreset, SiteAnalysis, SiteNeed, StructureChoice, StructureId, StyleHints, StyleRead, UserAvoidId };

package/package.json

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

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

@@ -23,3 +23,4 @@ export * from './compose-site';
 export * from './nav-shape';
 export * from './entrances';
 export * from './plan-data';
+export * from './site-build-run';

package/src/generation-core/site-build-run.ts

@@ -0,0 +1,236 @@
+import { ComposedPlaceholder, ComposeIssue } from './compose-site';
+import { SitePlan, SitePlanSource } from './site-plan.model';
+import { SitePlanIssueCode } from './validate-site-plan';
+
+/**
+ * A site build's WIRE vocabulary (AI plan §3b, W2): what iox-cms's `site-builds` API answers and what every
+ * client of it reads — the run's statuses and steps, what it created, why Undo kept something, the preflight's
+ * refusals, and the one spelling of each document's `buildKey`. ONE definition: iox-cms stores and answers it,
+ * the website wizard (W3) polls it. Pure types, enums and helpers; no transport.
+ */
+
+export enum SiteBuildKind {
+    Build = 'build',
+}
+
+export enum SiteBuildStatus {
+    Running = 'running',
+    Done = 'done',
+    Failed = 'failed',
+    Undoing = 'undoing',
+    Undone = 'undone',
+}
+
+/** The statuses a runner advances — and the ones that hold the org's single-run slot. */
+export const ACTIVE_BUILD_STATUSES: ReadonlyArray<SiteBuildStatus> = [SiteBuildStatus.Running, SiteBuildStatus.Undoing];
+
+/** The steps of a build, in the order they run. */
+export enum BuildStep {
+    Preflight = 'preflight',
+    ContentTypes = 'content-types',
+    SampleImages = 'sample-images',
+    Items = 'items',
+    DataSources = 'data-sources',
+    Pages = 'pages',
+    Globals = 'globals',
+    Look = 'look',
+}
+
+export const BUILD_STEPS: ReadonlyArray<BuildStep> = Object.values(BuildStep);
+
+export enum StepState {
+    Wait = 'wait',
+    Run = 'run',
+    Done = 'done',
+    Failed = 'failed',
+}
+
+/** What a build creates, as Undo walks it. */
+export enum CreatedKind {
+    ContentType = 'content-type',
+    SampleImage = 'sample-image',
+    Item = 'item',
+    DataSource = 'data-source',
+    Page = 'page',
+    Global = 'global',
+    Look = 'look',
+}
+
+/** Why Undo left something in place. */
+export enum KeptReason {
+    Edited = 'edited',
+    Published = 'published',
+    InUse = 'in-use',
+}
+
+export interface BuildStepError {
+    code: string;
+    detail: string;
+}
+
+export interface BuildStepRecord {
+    key: BuildStep;
+    state: StepState;
+    attempts: number;
+    startedAt?: Date | string;
+    finishedAt?: Date | string;
+    error?: BuildStepError;
+}
+
+export interface CreatedRecord {
+    kind: CreatedKind;
+    /** The document id — a page / item / content-type `_id`, a data-source alias, a global node id, a storage key. */
+    id: string;
+    buildKey: string;
+    /** sha256 of the document as the build left it. */
+    fingerprint: string;
+    /** An item's content type. */
+    contentType?: string;
+    /** A sample image's public URL — what items and pages reference. */
+    url?: string;
+}
+
+export interface UndoKept {
+    kind: CreatedKind;
+    id: string;
+    reason: KeptReason;
+    /** In plain words, for the screen ("About", "Sample project 2"). */
+    label?: string;
+}
+
+export interface UndoRecord {
+    at: Date | string;
+    removed: number;
+    kept: UndoKept[];
+    /** The undo steps already done (kinds), so a resumed undo does not redo them. */
+    done: CreatedKind[];
+    finishedAt?: Date | string;
+    /** What stopped the undo — DELETE again carries on from the kind it stopped at. */
+    error?: BuildStepError;
+}
+
+export enum BuildNoticeCode {
+    /** Storage is not configured: sample items get the empty image box, and the run says so. */
+    NoStorage = 'no-storage',
+}
+
+export interface BuildNotice {
+    code: string;
+    detail: string;
+}
+
+/** The run as `GET …/site-builds/:id` (and `?latest=1`) answers it. */
+export interface SiteBuildRun {
+    _id: string;
+    organization: string;
+    kind: SiteBuildKind;
+    source: SitePlanSource;
+    plan: SitePlan;
+    year: number;
+    status: SiteBuildStatus;
+    active?: boolean;
+    steps: BuildStepRecord[];
+    created: CreatedRecord[];
+    placeholders: ComposedPlaceholder[];
+    issues: ComposeIssue[];
+    notices?: BuildNotice[];
+    requestedBy: string;
+    startedAt: Date | string;
+    finishedAt?: Date | string;
+    undo?: UndoRecord;
+}
+
+/** `GET …/site-builds/:id/undo`: what an Undo would remove and keep — never guessed in the browser. */
+export interface UndoPreview {
+    removes: Partial<Record<CreatedKind, number>>;
+    kept: UndoKept[];
+    restoresGlobals: string[];
+    revertsLook: boolean;
+}
+
+export enum PreflightRefusalCode {
+    /** The Site Plan itself is invalid (`validateSitePlan`); `issue` is the validator's code. */
+    InvalidPlan = 'invalid-plan',
+    /** A route the plan wants is already a page of this organization. */
+    RouteTaken = 'route-taken',
+    /** A content type of that name exists in this instance (content types are instance-wide). */
+    ContentTypeTaken = 'content-type-taken',
+    /** The name may not be a content type (a platform collection, or not a valid name). */
+    ContentTypeName = 'content-type-name',
+    /** Content types act on the whole instance: only the instance owner may create them (SEC1). */
+    ContentTypesNeedInstanceOwner = 'content-types-need-instance-owner',
+    /** The org library holds the alias with a different definition. */
+    DataSourceConflict = 'data-source-conflict',
+    /** The studio has pages AND a header/footer: replace or keep them is the caller's choice (D7). */
+    GlobalsNeedDecision = 'globals-need-decision',
+    /** A global the plan adds has the id of one the studio keeps. */
+    GlobalTaken = 'global-taken',
+}
+
+export interface PreflightRefusal {
+    code: PreflightRefusalCode;
+    /** Where, as a dotted path into the plan. */
+    path: string;
+    detail: string;
+    /** For `invalid-plan`: the validator's issue code. */
+    issue?: SitePlanIssueCode;
+}
+
+/**
+ * The stable key each written document carries beside `siteBuildId`: a step that runs twice looks it up first and
+ * skips what exists (so a restart or a Retry continues without duplicates), and a reader finds what the run made
+ * by it — the wizard opens the HOME page by `page(<its key>)`. One builder per kind.
+ */
+export const buildKeys = {
+    contentType: (name: string) => `schema:${name}`,
+    item: (contentType: string, n: number) => `item:${contentType}:${n}`,
+    sampleImage: (n: number) => `sample-image:${n}`,
+    dataSource: (alias: string) => `data-source:${alias}`,
+    page: (key: string) => `page:${key}`,
+    global: (nodeId: string) => `global:${nodeId}`,
+    look: () => 'look',
+} as const;
+
+/** The id of the page a run made for the plan's home page, or null (not made yet, or no home page). */
+export function builtHomePageId(run: Pick<SiteBuildRun, 'plan' | 'created'> | null | undefined): string | null {
+    const home = run?.plan?.pages?.find(p => p.isHome) ?? run?.plan?.pages?.[0];
+    if (!home) return null;
+    const key = buildKeys.page(home.key);
+    return run!.created?.find(c => c.kind === CreatedKind.Page && c.buildKey === key)?.id ?? null;
+}
+
+/** The step a run stopped at, or null. */
+export function failedBuildStep(run: Pick<SiteBuildRun, 'steps'> | null | undefined): BuildStepRecord | null {
+    return run?.steps?.find(s => s.state === StepState.Failed) ?? null;
+}
+
+/** A run still holding the org's slot (building or undoing) — a page that left it comes back to its progress. */
+export function isActiveBuild(run: Pick<SiteBuildRun, 'status'> | null | undefined): boolean {
+    return !!run && ACTIVE_BUILD_STATUSES.includes(run.status);
+}
+
+/** What each step of a build of `plan` will make — the progress rows' words, from the plan alone. */
+export interface BuildStepFacts {
+    /** Content types to create: their labels. */
+    contentTypes: string[];
+    /** Sample items, all types together. */
+    items: number;
+    /** Pages (template pages included) and their routes. */
+    pages: number;
+    routes: string[];
+    /** Links in the menu (pages `inNav`). */
+    navLinks: number;
+    /** The look's flavor. */
+    flavorId: string;
+}
+
+export function buildStepFacts(plan: SitePlan): BuildStepFacts {
+    return {
+        contentTypes: plan.contentTypes.map(t => t.label),
+        items: plan.contentTypes.reduce((n, t) => n + (t.seed?.count ?? 0), 0),
+        pages: plan.pages.length,
+        routes: plan.pages.map(p => p.route),
+        navLinks: plan.pages.filter(p => p.inNav).length,
+        flavorId: plan.design.flavorId,
+    };
+}

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

@@ -17,3 +17,4 @@ export * from './lint';
 export * from './site-analysis';
 export * from './prompt-context';
 export * from './intake';
+export * from './structure';

package/src/harness-core/structure.ts

@@ -0,0 +1,23 @@
+import { SITE_TEMPLATES, SiteTemplate, STUDIO_TEMPLATE } from '@vectoriox/iox-ui/generation-core';
+
+import { businessTypeById, STRUCTURES, StructureId } from './business-types';
+
+/** The structure a kind of business is built from, and the template the wizard can build TODAY. */
+export interface StructureChoice {
+    /** The business type's own structure (Studio · Practice · Place). */
+    structure: StructureId;
+    /** The template that will be built. */
+    template: SiteTemplate;
+    /** The type's structure has no template yet (L0-4), so the Studio template stands in. */
+    fallback: boolean;
+}
+
+/**
+ * Which template the template path (and the plan stage) builds a kind of business from (AI plan rev 3 §3d,
+ * N-D3): its structure's template when that one has shipped, else Studio — said, never silent. No type → Studio.
+ */
+export function structureFor(typeId: string | null | undefined): StructureChoice {
+    const structure = (businessTypeById(typeId)?.structure ?? 'studio') as StructureId;
+    const own = STRUCTURES[structure]?.shipped ? SITE_TEMPLATES[structure] : undefined;
+    return { structure, template: own ?? STUDIO_TEMPLATE, fallback: !own };
+}