@tryvitris/website-harness 0.0.0-stage → 0.1.0-beta.5

package/bin/types/src/agent/artifacts.d.ts

@@ -0,0 +1,602 @@
+export type ReplacementJournal = {
+    schemaVersion: 1;
+    stage: "staged" | "committed" | "rolled_back";
+    from: string;
+    to: string;
+    backup?: string;
+    pid: number;
+    createdAt: string;
+    isDirectory: boolean;
+};
+export declare function isPidDead(pid: number): boolean;
+/** Acquire exclusive writer lock for target path. */
+export declare function acquirePathLock(targetPath: string, timeoutMs?: number): () => void;
+/**
+ * Recoverable file/directory replacement with transaction journal.
+ * Preserves target backup and transaction metadata so failures can roll back cleanly
+ * or be recovered on startup.
+ */
+export declare function recoverableReplace(from: string, to: string): void;
+/** Backwards-compatible alias for recoverableReplace. */
+export declare function replacePath(from: string, to: string): void;
+/** Recover pending transaction journals in a directory after a crash or interruption. */
+export declare function recoverPendingTransactions(dir: string): void;
+export declare function cleanStaleTmp(path: string, maxAgeMs?: number): void;
+export declare function within(root: string, path: string): string;
+export declare function files(root: string): string[];
+export declare function json<T = Record<string, unknown>>(path: string): T;
+export declare function save(path: string, data: unknown): void;
+export declare function sha256(text: string): string;
+export declare function fingerprint(root: string, paths: string[], sources?: Record<string, string>): string;
+export declare const SOURCE_PATHS: string[];
+export declare const sourceHash: (root: string) => string;
+export declare const STUDY_CAPTURE_VIEWPORTS: readonly [375, 1080];
+export declare const STUDY_CAPTURE_HEIGHT = 900;
+export type Evidence = {
+    id: string;
+    source: string;
+    excerpt: string;
+};
+export type Business = {
+    version: 2;
+    offer: string;
+    audience: string;
+    trigger: string;
+    outcome: string;
+    includes: string[];
+    engagement: string;
+    positioning: string;
+    facts: {
+        id: string;
+        claim: string;
+        evidence: string[];
+    }[];
+    evidence: Evidence[];
+    uncertainties: {
+        question: string;
+        blocking: boolean;
+        resolution?: string;
+    }[];
+};
+export type MediaInventory = {
+    version: 2;
+    harvestHash: string;
+    unavailable?: {
+        source: string;
+        reason: string;
+        resolution: "unresolved" | "unavailable" | "excluded";
+        evidence: string;
+    }[];
+    assets: {
+        id: string;
+        path: string;
+        sources: string[];
+        description: string;
+        role: string;
+        disposition: "use" | "retain" | "duplicate" | "exclude" | "unresolved";
+        reason: string;
+        inspected: boolean;
+        placements: string[];
+        duplicateOf?: string;
+        origin?: "customer" | "stock" | "authored" | "unknown";
+        provenance?: {
+            sourceUrl: string;
+            termsUrl: string;
+            credit: string;
+            acquiredAt?: string;
+            query?: string;
+            originalSha256: string;
+        };
+        production?: {
+            method: "generated-raster" | "authored-vector" | "derived";
+            operationId: string;
+            requestId: string;
+            sourcePath: string;
+            sourceSha256: string;
+            prompt?: string;
+            tool: string;
+            model?: string;
+            parents: {
+                assetId: string;
+                path: string;
+                sha256: string;
+                origin: "customer" | "stock" | "authored" | "unknown";
+            }[];
+            rights: string;
+            forbiddenImplications: string[];
+        };
+        identity?: "logo" | "founder" | "team" | "product" | "premises" | "project" | "brand-art" | "none" | "uncertain";
+        identityEvidence?: string[];
+        identityDecision?: string;
+        sha256?: string;
+        stockId?: string;
+        kind?: "image" | "video";
+        width?: number;
+        height?: number;
+        duration?: number;
+        poster?: string;
+        posterSha256?: string;
+        inspection?: import("../stock/types.ts").MediaInspection;
+    }[];
+};
+export type MotionPlan = {
+    version: 1 | 2;
+    purpose: string;
+    quiet: string[];
+    /** V2 covers authored routes, including expansion and short/contact pages. */
+    routes?: {
+        route: string;
+        task: string;
+        character: string;
+        normal: string;
+        mobile: string;
+        reduced: string;
+        ending: string;
+        available: string[];
+        beats: {
+            sectionId: string;
+            role: "opening" | "development" | "closing" | "whole";
+            change: string;
+            scenes: string[];
+            connects?: [string, string];
+            transition: string;
+        }[];
+    }[];
+    character?: string;
+    decision?: "motion" | "static";
+    revisionReason?: string;
+    scenes: {
+        route: string;
+        targetId: string;
+        triggerId: string;
+        effect: import("../compile/scroll-motion.ts").MotionEffect;
+        timing: {
+            duration?: number;
+            delay?: number;
+            stagger?: number;
+        };
+        mobile: "same" | "static";
+        reduced: "static";
+        reason: string;
+        factRef?: string;
+        sourceFact?: string;
+        finalText?: string;
+        treatment?: "phrase" | "mask";
+    }[];
+};
+export type DirectionDecisionKind = "typography" | "composition" | "media" | "navigation" | "interaction" | "density" | "surface";
+export type DirectionDecision = {
+    id: string;
+    kind: DirectionDecisionKind;
+    choice: string;
+    rationale: string;
+    scope: string;
+    tradeoff: string;
+};
+export type Direction = {
+    motionPlan?: MotionPlan;
+    version: 2;
+    businessHash: string;
+    request: string;
+    candidates: {
+        id: string;
+        rationale: string;
+        typography: string;
+        composition: string;
+        mediaTreatment: string;
+    }[];
+    selected: string;
+    rationale: string;
+    system: {
+        personality: string;
+        typography: string;
+        colorRoles: string;
+        density: string;
+        rhythm: string;
+        mediaTreatment: string;
+        surfaces: string;
+        navigation: string;
+        motifs: string;
+        interiors: string;
+        avoid: string[];
+    };
+    studies: {
+        candidate: string;
+        path: string;
+        screenshot?: string;
+    }[];
+    /** Version 1 design-decision trail. Absent on legacy directions, which stay readable and fail current gates. */
+    designContractVersion?: 1;
+    centralIdea?: string;
+    opportunityIds?: string[];
+    decisions?: DirectionDecision[];
+    rejectedAlternatives?: {
+        id: string;
+        summary: string;
+    }[];
+    identityInvariants?: string[];
+    flexibleDecisions?: string[];
+};
+export type StoryboardSection = {
+    id: string;
+    question: string;
+    message: string;
+    facts: string[];
+    media: string[];
+    action: {
+        label: string;
+        destination: string;
+        behavior: string;
+    } | null;
+    composition: string;
+    emphasis: string;
+    transition: string;
+    role?: string;
+    purpose?: string;
+    opportunityIds?: string[];
+    decisionIds?: string[];
+    emphasisReason?: string;
+    layoutFamily?: string;
+    density?: string;
+    mediaProminence?: string;
+    interaction?: string;
+    repetitionRationale?: string;
+    mobileTransformation?: string;
+    elementPlan?: PlannedElement[];
+    relationships?: ElementRelationship[];
+    lessonApplications?: LessonApplication[];
+    renderObservations?: RenderObservation[];
+};
+export type ContentRef = {
+    kind: "fact" | "media" | "copy";
+    id: string;
+} | {
+    kind: "section-message" | "section-action";
+    sectionId: string;
+};
+export type PlannedElement = {
+    id: string;
+    role: string;
+    contentRefs: ContentRef[];
+};
+export type ElementRelationship = {
+    from: string;
+    to: string;
+    kind: "groups-with" | "supports" | "compares-with" | "annotates" | "precedes" | "aligns-with" | "other";
+    intent: string;
+};
+export type LessonApplication = {
+    id: string;
+    version: number;
+    contentHash: string;
+    decision: "apply" | "adapt" | "decline";
+    reason: string;
+    elementIds: string[];
+};
+export type RenderObservation = {
+    id: string;
+    elementIds: string[];
+    viewportClass: "all" | "narrow" | "wide";
+    state: string;
+    expectation: string;
+    verification: "visual" | "browser" | "content";
+};
+export type Storyboard = {
+    motionPlan?: MotionPlan;
+    version: 2 | 3;
+    businessHash: string;
+    directionHash: string;
+    /** Version 3 explicitly locates brand media shared across routes. */
+    globalMedia?: {
+        assetId: string;
+        placement: "header" | "footer";
+        routes: string[];
+        reason: string;
+    }[];
+    designContractVersion?: 1;
+    compositionContractVersion?: 1;
+    compositionLessonRelease?: string;
+    routes: {
+        source: string;
+        disposition: "preserve" | "redirect" | "consolidate" | "retire";
+        target?: string;
+        reason: string;
+    }[];
+    pages: {
+        path: string;
+        purpose: string;
+        representative: boolean;
+        role?: string;
+        visitorOutcome?: string;
+        compositionIntent?: {
+            organizingRelationship: string;
+            readingSequence: string[];
+            crossSectionRelationships?: ElementRelationship[];
+        };
+        sections: StoryboardSection[];
+    }[];
+};
+export type Finding = {
+    id: string;
+    page: string;
+    section: string;
+    evidence: string;
+    severity: "blocker" | "major" | "minor";
+    problem: string;
+    repair: string;
+    target: string;
+    verify: string;
+    viewport?: string;
+    consequence?: string;
+    preservation?: string;
+};
+export type Review = {
+    motionJourneys?: {
+        route: string;
+        checks: {
+            criterion: string;
+            verdict: "pass" | "fail" | "unknown";
+            evidence: string;
+            checkpoints: string[];
+        }[];
+    }[];
+    version: 2;
+    subjectHash: string;
+    verdict: "pass" | "fail" | "unknown";
+    reviewer: string;
+    evidence: string[];
+    checks: {
+        criterion: string;
+        verdict: "pass" | "fail" | "unknown";
+        evidence: string;
+    }[];
+    findings: Finding[];
+    partitions?: string[];
+    dispositions?: CriticDisposition[];
+};
+export type CriticDisposition = {
+    findingId: string;
+    subjectHash: string;
+    disposition: "fixed" | "disagree_with_evidence" | "accepted_risk";
+    rationale: string;
+    evidence: string;
+};
+export type ParentDiversityIdentities = {
+    directions: string;
+    studies: string;
+    assets: string;
+    renders: string;
+    viewports: string;
+    refs: string;
+};
+export type ParentDiversityReview = {
+    schemaVersion: 1;
+    kind: "direction-diversity";
+    runId: string;
+    verdict: "pass" | "fail" | "unknown";
+    subjectHash: string;
+    reviewer: string;
+    identities: ParentDiversityIdentities;
+    evidence: string[];
+    axes: {
+        name: string;
+        evidence: string;
+    }[];
+    candidates: {
+        id: string;
+        observation: string;
+        findings: Finding[];
+    }[];
+    findings: Finding[];
+    repair?: {
+        directionId: string;
+        reason: string;
+        targets: string[];
+    };
+    unresolvedSimilarity?: string;
+    selected?: string;
+};
+export type DesignOpportunityBasis = "evidence-backed" | "design-hypothesis";
+export type DesignOpportunity = {
+    id: string;
+    visitorNeed: string;
+    businessRelevance: string;
+    evidenceIds: string[];
+    mediaIds: string[];
+    presentationOpportunity: string;
+    constraints: string[];
+    basis: DesignOpportunityBasis;
+    uncertainty?: string;
+};
+export type NarrativeBrief = {
+    /** 1 is legacy and inspectable. 2 is the current business-to-design contract. */
+    schemaVersion: 1 | 2;
+    businessHash: string;
+    mediaHash: string;
+    customer: string;
+    problem: string;
+    offer: string;
+    serviceScope: string;
+    proof: {
+        statement: string;
+        evidenceIds: string[];
+        status?: "strong" | "limited" | "missing";
+    };
+    conversion: string;
+    objections: {
+        claim: string;
+        evidenceIds: string[];
+    }[];
+    unsupportedClaims: string[];
+    facts: {
+        id: string;
+        claim: string;
+        evidenceIds: string[];
+    }[];
+    visitorQuestions?: {
+        id: string;
+        question: string;
+        relationshipToConversion: string;
+        priority: number;
+    }[];
+    assetNotes?: {
+        mediaId?: string;
+        strength: string;
+        limitation?: string;
+    }[];
+    toneConstraints?: string[];
+    recordedUserGoals?: string[];
+    designOpportunities?: DesignOpportunity[];
+};
+export type TeachingPrincipleRef = {
+    id: string;
+    version: number;
+    contentHash: string;
+    reason: string;
+};
+export type ReferenceAnalysis = {
+    /** Opt-in inspiration corpus; delivery and actual visual inspection remain separate. */
+    referenceSelection?: {
+        release: string;
+        manifestHash: string;
+        catalogHash: string;
+        inputSignalHash: string;
+        selectorVersion?: string;
+        acceptedAt?: string;
+        selected: {
+            id: string;
+            revision: number;
+            reason: string;
+        }[];
+        teachingManifestHash?: string;
+        teachingSelected?: {
+            id: string;
+            revision: number;
+            reason: string;
+        }[];
+        inspectedEvidence: {
+            id: string;
+            revision: number;
+            route: string;
+            viewport: {
+                width: number;
+                height: number;
+            };
+            evidencePointer: string;
+            observed: string;
+            kind?: "retained-capture" | "live-only" | "accessible-session";
+            inspectedAt?: string;
+            sourceRevision?: number;
+            sessionId?: string;
+            capture?: {
+                path: string;
+                sha256: string;
+            };
+        }[];
+        plannedRelationships: {
+            homepage: string;
+            interior: string;
+            mobile: string;
+            action: string;
+        };
+    };
+    schemaVersion: 1;
+    packVersion: string;
+    packHash: string;
+    narrativeHash: string;
+    applicable: {
+        principle: string;
+        why: string;
+        evidencePaths: string[];
+    }[];
+    avoided: {
+        principle: string;
+        why: string;
+    }[];
+    plannedApplication: {
+        homepage: string;
+        interior: string;
+    };
+    /** Inspected calibration-pack paths. Not teaching-lesson files. */
+    evidencePaths: string[];
+    /** Selected built-in lessons. Distinct from inspected visual evidence. */
+    teachingPrinciples?: TeachingPrincipleRef[];
+};
+export declare const QUALITY_DIMENSIONS: readonly ["business-specificity", "composition", "typography", "media-integration", "brand-coherence", "copy-design-integration", "responsive-craft"];
+export type QualityDimension = (typeof QUALITY_DIMENSIONS)[number];
+export type QualityReview = {
+    schemaVersion: 1;
+    kind: "design-quality";
+    subjectHash: string;
+    identities: Record<string, string>;
+    verdict: "pass" | "fail" | "unknown";
+    reviewer: string;
+    visualInspection: {
+        available: boolean;
+        probeHash: string;
+        observedToken: string;
+        captureHashes: string[];
+        toolReads: {
+            path: string;
+            hash: string;
+            dataBlobId?: string;
+        }[];
+    };
+    dimensions: {
+        name: QualityDimension;
+        score: 0 | 1 | 2 | 3 | 4;
+        page: string;
+        viewport: string;
+        section: string;
+        evidence: string;
+    }[];
+    findings: Finding[];
+    compositionReviewVersion?: 1;
+    artObservations?: {
+        criterion: "content-fit" | "visual-concept" | "asset-craft" | "sequence-coherence" | "responsive-treatment" | "explanatory-clarity";
+        outcome: "satisfied" | "problem" | "unknown" | "not-applicable";
+        page: string;
+        section: string;
+        viewport: string;
+        capturePath: string;
+        captureSha256: string;
+        observation: string;
+    }[];
+    compositionObservations?: {
+        observationId: string;
+        page: string;
+        sectionIds: string[];
+        elementIds: string[];
+        viewport: string;
+        state: string;
+        captureHashes: string[];
+        observed: string;
+        outcome: "satisfied" | "problem" | "unknown" | "not-applicable";
+        consequence?: string;
+        findingId?: string;
+    }[];
+    repair?: {
+        reason: string;
+        targets: string[];
+    };
+};
+export type UsageReceipt = {
+    schemaVersion: 1;
+    adapter: string;
+    model?: string;
+    role: "author" | "reviewer" | "tool" | "unknown";
+    nodeId: string;
+    startedAt: string;
+    durationMs: number;
+    status: "ok" | "failed" | "interrupted" | "unknown";
+    usage: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+        cache?: Record<string, unknown>;
+        unknown: boolean;
+        lowerBound?: boolean;
+    };
+    providerRaw?: Record<string, unknown>;
+};
+export type ThemeScope = "one" | "all";

package/bin/types/src/agent/browser-motion-journey.d.ts

@@ -0,0 +1,59 @@
+import type { Browser } from 'playwright';
+import { type MotionPlan } from './artifacts.ts';
+export declare const JOURNEY_SCENARIO: {
+    version: number;
+    fontSettlementMs: number;
+    arrivalSettlementMs: number;
+    openingObservationMs: number;
+    openingMs: number;
+    stepPx: number;
+    readingMs: number;
+    firstSampleMs: number;
+    settleMs: number;
+    maxHeight: number;
+    modes: string[];
+    traversal: string;
+};
+export declare const JOURNEY_SCENARIO_HASH: string;
+export type MotionJourney = {
+    path: string;
+    width: number;
+    mode: 'normal' | 'reduce' | 'static';
+    sourceHash: string;
+    outputHash: string;
+    planHash: string;
+    scenarioHash: string;
+    engineAssetHash: string;
+    sections: {
+        id: string;
+        top: number;
+        bottom: number;
+    }[];
+    scenes: {
+        id: string;
+        sectionId: string | null;
+        top: number;
+        bottom: number;
+        active: boolean;
+    }[];
+    checkpoints: {
+        y: number;
+        timeMs: number;
+        states: {
+            id: string;
+            signature: string;
+            phase: string | null;
+            static: boolean | null;
+            stickyTop?: number | null;
+        }[];
+        screenshot?: string;
+        screenshotHash?: string;
+    }[];
+    video?: string;
+    videoHash?: string;
+    failures: string[];
+};
+export declare function captureMotionJourney(browser: Browser, root: string, url: string, route: string, width: number, mode: MotionJourney['mode'], directory: string, plan: MotionPlan, operatorOff?: boolean): Promise<MotionJourney>;
+export declare function journeyEvidenceFailures(root: string, evidence: MotionJourney, plan: MotionPlan): string[];
+export declare const MOTION_CRITIQUE_CRITERIA: readonly ["whole-journey", "distribution-connections", "business-rhythm", "competition-stillness", "route-differences", "immediate-use"];
+export declare function motionCritiqueFailures(root: string, review: any, routes: string[], report: any): string[];

package/bin/types/src/agent/browser-motion.d.ts

@@ -0,0 +1,40 @@
+import type { Page } from 'playwright';
+export declare const MOTION_SCENARIO: {
+    version: number;
+    states: string[];
+    triggerViewport: number;
+    duringMs: number;
+    settleMs: number;
+    progress: number[];
+    modes: string[];
+    scrolling: string;
+    expressive: string;
+};
+export declare const MOTION_SCENARIO_HASH: string;
+export type TemporalMotionEvidence = {
+    path: string;
+    width: number;
+    motion: 'normal' | 'reduce';
+    scenarioHash: string;
+    engineAssetHash: string;
+    targets: {
+        id: string;
+        effect: string;
+        samples: {
+            state: string;
+            opacity: number;
+            transform: string;
+            progress: number | null;
+            canonical?: string;
+            visual?: string | null;
+            stroke?: string;
+            screenshot: string;
+            screenshotHash: string;
+        }[];
+    }[];
+    failures: string[];
+};
+/** Before static sweep/focus checks consume entrances, capture the actual sequence. */
+export declare function observeMotion(page: Page, root: string, route: string, width: number, mode: 'normal' | 'reduce', directory: string): Promise<TemporalMotionEvidence>;
+/** Pure evidence checks used by current-source browser acceptance. */
+export declare function temporalMotionFailures(root: string, evidence: TemporalMotionEvidence, expectedAssetHash: string): string[];

package/bin/types/src/agent/browser-timeout.d.ts

@@ -0,0 +1,4 @@
+/** Keep the outer release processes alive for the full, unchanged browser suite. */
+export declare function browserVerificationTimeoutMs(env?: NodeJS.ProcessEnv): number;
+/** Allow the child browser process to finish and seal its evidence first. */
+export declare function productionPreflightTimeoutMs(env?: NodeJS.ProcessEnv): number;