@ankhorage/contracts 26.5.0 → 26.7.0

package/dist/website.d.ts

@@ -0,0 +1,260 @@
+import type { MediaAssetReference } from './media.js';
+import type { SerializableValue } from './serializable.js';
+import type { UiNode } from './types.js';
+/*** A versioned, portable capture of the observable state of one website. */
+export interface WebsiteObservationDocument {
+    readonly schemaVersion: 1;
+    readonly documentId: string;
+    readonly collectedAt: string;
+    readonly source: WebsiteSource;
+    readonly site: WebsiteSite;
+    readonly pages: readonly WebsitePageObservation[];
+}
+/*** The scraper identity and immutable crawl revision that produced a website document. */
+export interface WebsiteSource {
+    readonly crawlerId: string;
+    readonly crawlerVersion: string;
+    readonly crawlId: string;
+    readonly revision: string | null;
+}
+/*** A site identity and its canonical entry URL. */
+export interface WebsiteSite {
+    readonly id: string;
+    readonly url: string;
+}
+/*** One observed page, including its ordered navigation and captured render states. */
+export interface WebsitePageObservation {
+    readonly id: string;
+    readonly url: string;
+    readonly path: string;
+    readonly navigation: readonly WebsiteNavigationItem[];
+    readonly viewports: readonly WebsiteViewport[];
+    readonly states: readonly WebsiteState[];
+    readonly nodes: readonly WebsiteObservedNode[];
+    readonly assets: readonly WebsiteAsset[];
+}
+/*** One ordered, source-linked navigation target observed on a page. */
+export interface WebsiteNavigationItem {
+    readonly id: string;
+    readonly label: string;
+    readonly url: string;
+    readonly sourceRef: string;
+}
+/*** A rendered viewport used while observing responsive website state. */
+export interface WebsiteViewport {
+    readonly id: string;
+    readonly width: number;
+    readonly height: number;
+    readonly devicePixelRatio: number;
+}
+/*** A named rendered state, such as default, hover, or expanded. */
+export interface WebsiteState {
+    readonly id: string;
+    readonly name: string;
+}
+/*** A stable DOM node and every source-linked observation collected for it. */
+export interface WebsiteObservedNode {
+    readonly sourceRef: string;
+    readonly parentSourceRef: string | null;
+    readonly ancestorSourceRefs: readonly string[];
+    readonly dom: WebsiteDomNode;
+    readonly textRuns: readonly WebsiteTextRun[];
+    readonly links: readonly WebsiteLink[];
+    readonly media: readonly WebsiteMediaReference[];
+    readonly observations: readonly WebsiteNodeObservation[];
+}
+/*** A portable DOM identity with safe semantic attributes only. */
+export interface WebsiteDomNode {
+    readonly tagName: string;
+    readonly childIndex: number;
+    readonly attributes: Readonly<Record<string, string>>;
+}
+/*** A text run retained separately from its DOM node so inline styled spans are not lost. */
+export interface WebsiteTextRun {
+    readonly sourceRef: string;
+    readonly text: string;
+    readonly start: number;
+    readonly end: number;
+}
+/*** A source-linked hyperlink observed on a DOM node. */
+export interface WebsiteLink {
+    readonly sourceRef: string;
+    readonly url: string;
+    readonly label: string | null;
+}
+/*** An image, video, audio, or embedded media reference observed on a DOM node. */
+export interface WebsiteMediaReference {
+    readonly sourceRef: string;
+    readonly assetId: string | null;
+    readonly url: string;
+    readonly kind: 'audio' | 'document' | 'embed' | 'image' | 'video';
+    readonly alt: string | null;
+}
+/*** One viewport/state-specific visual observation of a DOM node. */
+export interface WebsiteNodeObservation {
+    readonly viewportId: string;
+    readonly stateId: string;
+    readonly availability: WebsiteAvailability;
+    readonly rect: WebsiteBoundingRect | null;
+    readonly css: WebsiteComputedCss | null;
+    readonly provenance: WebsiteObservationProvenance;
+}
+/*** Whether a source value was available without fabricating a replacement. */
+export interface WebsiteAvailability {
+    readonly status: 'available' | 'missing';
+    readonly missing: WebsiteMissingValue | null;
+}
+/*** The explicit reason a website source value could not be observed. */
+export interface WebsiteMissingValue {
+    readonly code: string;
+    readonly message: string;
+}
+/*** A bounding rectangle measured in CSS pixels. */
+export interface WebsiteBoundingRect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/*** Computed visual CSS values needed to describe, not assess, a rendered website. */
+export interface WebsiteComputedCss {
+    readonly display: string;
+    readonly position: string;
+    readonly visibility: string;
+    readonly color: string;
+    readonly backgroundColor: string;
+    readonly borderColor: string;
+    readonly borderRadius: string;
+    readonly borderWidth: string;
+    readonly boxShadow: string;
+    readonly fontFamily: string;
+    readonly fontSize: string;
+    readonly fontStyle: string;
+    readonly fontWeight: string;
+    readonly letterSpacing: string;
+    readonly lineHeight: string;
+    readonly textAlign: string;
+    readonly textDecoration: string;
+    readonly opacity: string;
+    readonly overflow: string;
+    readonly overflowX: string;
+    readonly overflowY: string;
+    readonly backgroundImage: string;
+    readonly backgroundPosition: string;
+    readonly backgroundRepeat: string;
+    readonly backgroundSize: string;
+    readonly margin: WebsiteBoxEdges;
+    readonly padding: WebsiteBoxEdges;
+    readonly alignContent: string;
+    readonly alignItems: string;
+    readonly alignSelf: string;
+    readonly gap: string;
+    readonly flexDirection: string;
+    readonly flexBasis: string;
+    readonly flexGrow: string;
+    readonly flexShrink: string;
+    readonly flexWrap: string;
+    readonly justifyContent: string;
+    readonly justifyItems: string;
+    readonly justifySelf: string;
+    readonly order: string;
+    readonly placeContent: string;
+    readonly placeItems: string;
+    readonly placeSelf: string;
+    readonly gridAutoColumns: string;
+    readonly gridAutoFlow: string;
+    readonly gridAutoRows: string;
+    readonly gridColumn: string;
+    readonly gridColumnEnd: string;
+    readonly gridColumnStart: string;
+    readonly gridRow: string;
+    readonly gridRowEnd: string;
+    readonly gridRowStart: string;
+    readonly gridTemplateColumns: string;
+    readonly gridTemplateRows: string;
+}
+/*** The four computed edges of a CSS box value. */
+export interface WebsiteBoxEdges {
+    readonly top: string;
+    readonly right: string;
+    readonly bottom: string;
+    readonly left: string;
+}
+/*** How an observation was obtained from the source page. */
+export interface WebsiteObservationProvenance {
+    readonly sourceUrl: string;
+    readonly capturedAt: string;
+    readonly method: 'browser' | 'html' | 'network';
+}
+/*** A reusable media asset discovered during the crawl. */
+export interface WebsiteAsset {
+    readonly id: string;
+    readonly url: string;
+    readonly kind: WebsiteMediaReference['kind'];
+    readonly contentType: string | null;
+    readonly sourceRefs: readonly string[];
+}
+/*** A versioned canonical component recognition derived from website observations. */
+export interface WebsiteRecognitionDocument {
+    readonly schemaVersion: 1;
+    readonly documentId: string;
+    readonly observedDocumentId: string;
+    readonly recognizedAt: string;
+    readonly source: WebsiteSource;
+    readonly site: WebsiteSite;
+    readonly navigation: readonly WebsiteNavigationItem[];
+    readonly pages: readonly WebsitePageRecognition[];
+    readonly designTokens: readonly WebsiteDesignToken[];
+    readonly media: readonly WebsiteRecognizedMedia[];
+}
+/*** A recognized page with its canonical UiNode tree and retained source mapping. */
+export interface WebsitePageRecognition {
+    readonly id: string;
+    readonly url: string;
+    readonly path: string;
+    readonly root: UiNode;
+    readonly nodes: readonly WebsiteRecognizedNode[];
+}
+/*** A source-linked canonical UiNode mapping; component shape remains owned by UiNode. */
+export interface WebsiteRecognizedNode {
+    readonly id: UiNode['id'];
+    readonly componentType: UiNode['type'];
+    readonly sourceRefs: readonly string[];
+    readonly confidence: number;
+    readonly props: readonly WebsiteRecognizedProp[];
+    readonly responsive: readonly WebsiteResponsiveVariant[];
+    readonly status: 'recognized' | 'unresolved';
+    readonly unresolved: WebsiteUnresolvedNode | null;
+}
+/*** A normalized UiNode property and the exact serializable values observed before normalization. */
+export interface WebsiteRecognizedProp {
+    readonly name: string;
+    readonly value: SerializableValue;
+    readonly originalValues: readonly SerializableValue[];
+}
+/*** A viewport-specific UiNode property override retained by the recognition. */
+export interface WebsiteResponsiveVariant {
+    readonly viewportId: string;
+    readonly props: readonly WebsiteRecognizedProp[];
+}
+/*** A visible source node that could not be mapped without silently discarding it. */
+export interface WebsiteUnresolvedNode {
+    readonly reason: string;
+    readonly sourceRefs: readonly string[];
+}
+/*** A normalized design token with its exact source values retained. */
+export interface WebsiteDesignToken {
+    readonly id: string;
+    readonly kind: 'color' | 'radius' | 'shadow' | 'spacing' | 'typography';
+    readonly value: SerializableValue;
+    readonly originalValues: readonly SerializableValue[];
+    readonly sourceRefs: readonly string[];
+}
+/*** A recognized portable media reference, optionally compatible with an app media asset. */
+export interface WebsiteRecognizedMedia {
+    readonly id: string;
+    readonly sourceRefs: readonly string[];
+    readonly originalUrl: string;
+    readonly asset: MediaAssetReference | null;
+}
+//# sourceMappingURL=website.d.ts.map

package/dist/website.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"website.d.ts","sourceRoot":"","sources":["../src/website.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,6EAA6E;AAC7E,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACnD;AAED,2FAA2F;AAC3F,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,uFAAuF;AACvF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACtD,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;CAC1C;AAED,wEAAwE;AACxE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACjD,QAAQ,CAAC,YAAY,EAAE,SAAS,sBAAsB,EAAE,CAAC;CAC1D;AAED,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACvD;AAED,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IAClE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,qEAAqE;AACrE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,4BAA4B,CAAC;CACnD;AAED,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAC9C;AAED,yEAAyE;AACzE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,sFAAsF;AACtF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,6DAA6D;AAC7D,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;CACjD;AAED,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,sFAAsF;AACtF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACtD,QAAQ,CAAC,KAAK,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAClD,QAAQ,CAAC,YAAY,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACnD;AAED,qFAAqF;AACrF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAClD;AAED,0FAA0F;AAC1F,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACjD,QAAQ,CAAC,UAAU,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACzD,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAAC;CACnD;AAED,qGAAqG;AACrG,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACvD;AAED,iFAAiF;AACjF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAClD;AAED,sFAAsF;AACtF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,wEAAwE;AACxE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,YAAY,CAAC;IACxE,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACtD,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,6FAA6F;AAC7F,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAC5C"}

package/dist/website.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=website.js.map

package/dist/website.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"website.js","sourceRoot":"","sources":["../src/website.ts"],"names":[],"mappings":"","sourcesContent":["import type { MediaAssetReference } from './media.js';\nimport type { SerializableValue } from './serializable.js';\nimport type { UiNode } from './types.js';\n\n/*** A versioned, portable capture of the observable state of one website. */\nexport interface WebsiteObservationDocument {\n  readonly schemaVersion: 1;\n  readonly documentId: string;\n  readonly collectedAt: string;\n  readonly source: WebsiteSource;\n  readonly site: WebsiteSite;\n  readonly pages: readonly WebsitePageObservation[];\n}\n\n/*** The scraper identity and immutable crawl revision that produced a website document. */\nexport interface WebsiteSource {\n  readonly crawlerId: string;\n  readonly crawlerVersion: string;\n  readonly crawlId: string;\n  readonly revision: string | null;\n}\n\n/*** A site identity and its canonical entry URL. */\nexport interface WebsiteSite {\n  readonly id: string;\n  readonly url: string;\n}\n\n/*** One observed page, including its ordered navigation and captured render states. */\nexport interface WebsitePageObservation {\n  readonly id: string;\n  readonly url: string;\n  readonly path: string;\n  readonly navigation: readonly WebsiteNavigationItem[];\n  readonly viewports: readonly WebsiteViewport[];\n  readonly states: readonly WebsiteState[];\n  readonly nodes: readonly WebsiteObservedNode[];\n  readonly assets: readonly WebsiteAsset[];\n}\n\n/*** One ordered, source-linked navigation target observed on a page. */\nexport interface WebsiteNavigationItem {\n  readonly id: string;\n  readonly label: string;\n  readonly url: string;\n  readonly sourceRef: string;\n}\n\n/*** A rendered viewport used while observing responsive website state. */\nexport interface WebsiteViewport {\n  readonly id: string;\n  readonly width: number;\n  readonly height: number;\n  readonly devicePixelRatio: number;\n}\n\n/*** A named rendered state, such as default, hover, or expanded. */\nexport interface WebsiteState {\n  readonly id: string;\n  readonly name: string;\n}\n\n/*** A stable DOM node and every source-linked observation collected for it. */\nexport interface WebsiteObservedNode {\n  readonly sourceRef: string;\n  readonly parentSourceRef: string | null;\n  readonly ancestorSourceRefs: readonly string[];\n  readonly dom: WebsiteDomNode;\n  readonly textRuns: readonly WebsiteTextRun[];\n  readonly links: readonly WebsiteLink[];\n  readonly media: readonly WebsiteMediaReference[];\n  readonly observations: readonly WebsiteNodeObservation[];\n}\n\n/*** A portable DOM identity with safe semantic attributes only. */\nexport interface WebsiteDomNode {\n  readonly tagName: string;\n  readonly childIndex: number;\n  readonly attributes: Readonly<Record<string, string>>;\n}\n\n/*** A text run retained separately from its DOM node so inline styled spans are not lost. */\nexport interface WebsiteTextRun {\n  readonly sourceRef: string;\n  readonly text: string;\n  readonly start: number;\n  readonly end: number;\n}\n\n/*** A source-linked hyperlink observed on a DOM node. */\nexport interface WebsiteLink {\n  readonly sourceRef: string;\n  readonly url: string;\n  readonly label: string | null;\n}\n\n/*** An image, video, audio, or embedded media reference observed on a DOM node. */\nexport interface WebsiteMediaReference {\n  readonly sourceRef: string;\n  readonly assetId: string | null;\n  readonly url: string;\n  readonly kind: 'audio' | 'document' | 'embed' | 'image' | 'video';\n  readonly alt: string | null;\n}\n\n/*** One viewport/state-specific visual observation of a DOM node. */\nexport interface WebsiteNodeObservation {\n  readonly viewportId: string;\n  readonly stateId: string;\n  readonly availability: WebsiteAvailability;\n  readonly rect: WebsiteBoundingRect | null;\n  readonly css: WebsiteComputedCss | null;\n  readonly provenance: WebsiteObservationProvenance;\n}\n\n/*** Whether a source value was available without fabricating a replacement. */\nexport interface WebsiteAvailability {\n  readonly status: 'available' | 'missing';\n  readonly missing: WebsiteMissingValue | null;\n}\n\n/*** The explicit reason a website source value could not be observed. */\nexport interface WebsiteMissingValue {\n  readonly code: string;\n  readonly message: string;\n}\n\n/*** A bounding rectangle measured in CSS pixels. */\nexport interface WebsiteBoundingRect {\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n}\n\n/*** Computed visual CSS values needed to describe, not assess, a rendered website. */\nexport interface WebsiteComputedCss {\n  readonly display: string;\n  readonly position: string;\n  readonly visibility: string;\n  readonly color: string;\n  readonly backgroundColor: string;\n  readonly borderColor: string;\n  readonly borderRadius: string;\n  readonly borderWidth: string;\n  readonly boxShadow: string;\n  readonly fontFamily: string;\n  readonly fontSize: string;\n  readonly fontStyle: string;\n  readonly fontWeight: string;\n  readonly letterSpacing: string;\n  readonly lineHeight: string;\n  readonly textAlign: string;\n  readonly textDecoration: string;\n  readonly opacity: string;\n  readonly overflow: string;\n  readonly overflowX: string;\n  readonly overflowY: string;\n  readonly backgroundImage: string;\n  readonly backgroundPosition: string;\n  readonly backgroundRepeat: string;\n  readonly backgroundSize: string;\n  readonly margin: WebsiteBoxEdges;\n  readonly padding: WebsiteBoxEdges;\n  readonly alignContent: string;\n  readonly alignItems: string;\n  readonly alignSelf: string;\n  readonly gap: string;\n  readonly flexDirection: string;\n  readonly flexBasis: string;\n  readonly flexGrow: string;\n  readonly flexShrink: string;\n  readonly flexWrap: string;\n  readonly justifyContent: string;\n  readonly justifyItems: string;\n  readonly justifySelf: string;\n  readonly order: string;\n  readonly placeContent: string;\n  readonly placeItems: string;\n  readonly placeSelf: string;\n  readonly gridAutoColumns: string;\n  readonly gridAutoFlow: string;\n  readonly gridAutoRows: string;\n  readonly gridColumn: string;\n  readonly gridColumnEnd: string;\n  readonly gridColumnStart: string;\n  readonly gridRow: string;\n  readonly gridRowEnd: string;\n  readonly gridRowStart: string;\n  readonly gridTemplateColumns: string;\n  readonly gridTemplateRows: string;\n}\n\n/*** The four computed edges of a CSS box value. */\nexport interface WebsiteBoxEdges {\n  readonly top: string;\n  readonly right: string;\n  readonly bottom: string;\n  readonly left: string;\n}\n\n/*** How an observation was obtained from the source page. */\nexport interface WebsiteObservationProvenance {\n  readonly sourceUrl: string;\n  readonly capturedAt: string;\n  readonly method: 'browser' | 'html' | 'network';\n}\n\n/*** A reusable media asset discovered during the crawl. */\nexport interface WebsiteAsset {\n  readonly id: string;\n  readonly url: string;\n  readonly kind: WebsiteMediaReference['kind'];\n  readonly contentType: string | null;\n  readonly sourceRefs: readonly string[];\n}\n\n/*** A versioned canonical component recognition derived from website observations. */\nexport interface WebsiteRecognitionDocument {\n  readonly schemaVersion: 1;\n  readonly documentId: string;\n  readonly observedDocumentId: string;\n  readonly recognizedAt: string;\n  readonly source: WebsiteSource;\n  readonly site: WebsiteSite;\n  readonly navigation: readonly WebsiteNavigationItem[];\n  readonly pages: readonly WebsitePageRecognition[];\n  readonly designTokens: readonly WebsiteDesignToken[];\n  readonly media: readonly WebsiteRecognizedMedia[];\n}\n\n/*** A recognized page with its canonical UiNode tree and retained source mapping. */\nexport interface WebsitePageRecognition {\n  readonly id: string;\n  readonly url: string;\n  readonly path: string;\n  readonly root: UiNode;\n  readonly nodes: readonly WebsiteRecognizedNode[];\n}\n\n/*** A source-linked canonical UiNode mapping; component shape remains owned by UiNode. */\nexport interface WebsiteRecognizedNode {\n  readonly id: UiNode['id'];\n  readonly componentType: UiNode['type'];\n  readonly sourceRefs: readonly string[];\n  readonly confidence: number;\n  readonly props: readonly WebsiteRecognizedProp[];\n  readonly responsive: readonly WebsiteResponsiveVariant[];\n  readonly status: 'recognized' | 'unresolved';\n  readonly unresolved: WebsiteUnresolvedNode | null;\n}\n\n/*** A normalized UiNode property and the exact serializable values observed before normalization. */\nexport interface WebsiteRecognizedProp {\n  readonly name: string;\n  readonly value: SerializableValue;\n  readonly originalValues: readonly SerializableValue[];\n}\n\n/*** A viewport-specific UiNode property override retained by the recognition. */\nexport interface WebsiteResponsiveVariant {\n  readonly viewportId: string;\n  readonly props: readonly WebsiteRecognizedProp[];\n}\n\n/*** A visible source node that could not be mapped without silently discarding it. */\nexport interface WebsiteUnresolvedNode {\n  readonly reason: string;\n  readonly sourceRefs: readonly string[];\n}\n\n/*** A normalized design token with its exact source values retained. */\nexport interface WebsiteDesignToken {\n  readonly id: string;\n  readonly kind: 'color' | 'radius' | 'shadow' | 'spacing' | 'typography';\n  readonly value: SerializableValue;\n  readonly originalValues: readonly SerializableValue[];\n  readonly sourceRefs: readonly string[];\n}\n\n/*** A recognized portable media reference, optionally compatible with an app media asset. */\nexport interface WebsiteRecognizedMedia {\n  readonly id: string;\n  readonly sourceRefs: readonly string[];\n  readonly originalUrl: string;\n  readonly asset: MediaAssetReference | null;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/contracts",
-  "version": "26.5.0",
+  "version": "26.7.0",
   "main": "./dist/index.js",
   "ankh": {
     "category": "contracts",
@@ -44,7 +44,7 @@
     "@ankhorage/utility": "^1.10.0"
   },
   "devDependencies": {
-    "@ankhorage/devtools": "^2.4.1",
+    "@ankhorage/devtools": "^2.4.3",
     "@ankhorage/paradox": "^0.3.6",
     "@types/bun": "^1.4.2",
     "@types/node": "^26.6.6",
@@ -115,6 +115,10 @@
       "types": "./dist/ui.d.ts",
       "default": "./dist/ui.js"
     },
+    "./website": {
+      "types": "./dist/website.d.ts",
+      "default": "./dist/website.js"
+    },
     "./media": {
       "types": "./dist/media.d.ts",
       "default": "./dist/media.js"
@@ -138,6 +142,10 @@
     "./capability": {
       "types": "./dist/capability.d.ts",
       "default": "./dist/capability.js"
+    },
+    "./flow": {
+      "types": "./dist/flow.d.ts",
+      "default": "./dist/flow.js"
     }
   },
   "description": "Serializable app, capability, binding, theme, auth, and secret-store contracts for Ankhorage.",

package/src/flow.test.ts

@@ -0,0 +1,218 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { describe, expect, it } from 'bun:test';
+
+import type {
+  FlowApprovalRequest,
+  FlowDefinition,
+  FlowNodeConfig,
+  FlowRunSnapshot,
+  FlowSecretRef,
+} from './flow.js';
+
+type JsonRecord = Readonly<Record<string, unknown>>;
+
+const isRecord = (value: unknown): value is JsonRecord =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isString = (value: unknown): value is string => typeof value === 'string';
+
+const isFlowFixture = (value: unknown): value is FlowDefinition => {
+  if (
+    !isRecord(value) ||
+    !isString(value.id) ||
+    !Number.isInteger(value.version) ||
+    !isString(value.title)
+  ) {
+    return false;
+  }
+
+  return (
+    Array.isArray(value.nodes) &&
+    value.nodes.every(
+      (node) =>
+        isRecord(node) &&
+        isString(node.id) &&
+        isRecord(node.capability) &&
+        isString(node.capability.providerId) &&
+        isString(node.capability.capabilityId) &&
+        Array.isArray(node.ports) &&
+        node.ports.every(
+          (port) =>
+            isRecord(port) &&
+            isString(port.id) &&
+            (port.direction === 'input' || port.direction === 'output'),
+        ),
+    ) &&
+    Array.isArray(value.edges) &&
+    value.edges.every(
+      (edge) =>
+        isRecord(edge) &&
+        isString(edge.id) &&
+        isRecord(edge.source) &&
+        isString(edge.source.nodeId) &&
+        isString(edge.source.portId) &&
+        isRecord(edge.target) &&
+        isString(edge.target.nodeId) &&
+        isString(edge.target.portId),
+    ) &&
+    Array.isArray(value.triggers) &&
+    value.triggers.every(
+      (trigger) => isRecord(trigger) && isString(trigger.id) && isString(trigger.kind),
+    )
+  );
+};
+
+const definition = {
+  id: 'social-publish',
+  version: 3,
+  title: 'Publish approved social media',
+  nodes: [
+    {
+      id: 'compose',
+      capability: { providerId: '@ankhorage/flow/social', capabilityId: 'post.compose' },
+      config: {
+        audience: { kind: 'inline', value: { segment: 'subscribers' } },
+        credential: { kind: 'secret', ref: 'flow/social/publisher' },
+      },
+      ports: [
+        { id: 'draft', direction: 'input', required: true, data: { schema: { type: 'object' } } },
+        { id: 'post', direction: 'output', data: { schema: { type: 'object' } } },
+      ],
+    },
+    {
+      id: 'notify',
+      capability: { providerId: '@ankhorage/flow/social', capabilityId: 'notification.send' },
+      ports: [{ id: 'post', direction: 'input', required: true }],
+    },
+  ],
+  edges: [
+    {
+      id: 'notify-success',
+      source: { nodeId: 'compose', portId: 'post' },
+      target: { nodeId: 'notify', portId: 'post' },
+      condition: { kind: 'outcome', outcome: 'success' },
+    },
+  ],
+  triggers: [{ id: 'manual', kind: 'manual' }],
+} as const satisfies FlowDefinition;
+
+const run = {
+  id: 'run-42',
+  flow: { id: definition.id, version: definition.version },
+  status: 'waiting_for_approval',
+  trigger: { triggerId: 'manual', kind: 'manual' },
+  createdAt: '2026-11-12T09:00:00.000Z',
+  steps: [
+    {
+      id: 'step-compose',
+      nodeId: 'compose',
+      status: 'succeeded',
+      attempt: 1,
+      output: {
+        post: { kind: 'artifact', artifactId: 'artifact-post', mediaType: 'application/json' },
+      },
+    },
+  ],
+} as const satisfies FlowRunSnapshot;
+
+const approval = {
+  id: 'approval-7',
+  runId: run.id,
+  step: { id: 'step-compose', nodeId: 'compose', attempt: 1, runId: run.id },
+  status: 'pending',
+  requestedAt: '2026-11-12T09:01:00.000Z',
+  context: { kind: 'artifact', artifactId: 'artifact-post' },
+} as const satisfies FlowApprovalRequest;
+
+describe('Flow contract serialization', () => {
+  it('round-trips a standalone versioned workflow fixture', () => {
+    const fixturePath = join(process.cwd(), 'test/flow/fixtures/versioned-workflow.json');
+    const fixture = JSON.parse(readFileSync(fixturePath, 'utf8')) as unknown;
+
+    expect(isFlowFixture(fixture)).toBe(true);
+    expect(JSON.parse(JSON.stringify(fixture))).toEqual(fixture);
+  });
+
+  it('rejects malformed fixture structure independently of JSON serialization', () => {
+    const malformedFixture = {
+      id: 'missing-port-direction',
+      version: 1,
+      title: 'Malformed fixture',
+      nodes: [
+        {
+          id: 'compose',
+          capability: { providerId: '@ankhorage/flow/social', capabilityId: 'post.compose' },
+          ports: [{ id: 'post', direction: 'sideways' }],
+        },
+      ],
+      edges: [],
+      triggers: [],
+    };
+
+    expect(isFlowFixture(malformedFixture)).toBe(false);
+    expect(JSON.parse(JSON.stringify(malformedFixture))).toEqual(malformedFixture);
+  });
+
+  it('round-trips a versioned graph, run snapshot, and approval without runtime values', () => {
+    expect(JSON.parse(JSON.stringify({ definition, run, approval }))).toEqual({
+      definition,
+      run,
+      approval,
+    });
+  });
+});
+
+describe('Flow contract boundaries', () => {
+  it('accepts secret references but excludes inline secret material from their contract', () => {
+    const secret = {
+      kind: 'secret',
+      ref: 'flow/social/publisher',
+    } as const satisfies FlowSecretRef;
+
+    expect(JSON.parse(JSON.stringify(secret))).toEqual(secret);
+    // @ts-expect-error Flow secret references must not carry secret material.
+    const inlineSecret: FlowSecretRef = {
+      kind: 'secret',
+      ref: 'flow/social/publisher',
+      value: 'secret',
+    };
+    expect(inlineSecret).toBeDefined();
+
+    // @ts-expect-error Node configuration requires an explicit data or secret reference.
+    const plaintextCredential: FlowNodeConfig = { credential: 'api-key' };
+    expect(plaintextCredential).toBeDefined();
+  });
+
+  it('requires a JSON Pointer whenever a condition compares a port value', () => {
+    // @ts-expect-error Value conditions must name an RFC 6901 JSON Pointer, including '' for root.
+    const implicitRootComparison: FlowDefinition = {
+      ...definition,
+      edges: [
+        {
+          id: 'implicit-root',
+          source: { nodeId: 'compose', portId: 'post' },
+          target: { nodeId: 'notify', portId: 'post' },
+          condition: { kind: 'value', equals: 'published' },
+        },
+      ],
+    };
+    expect(implicitRootComparison).toBeDefined();
+  });
+
+  it('keeps node ports directional and edge endpoints precise', () => {
+    // @ts-expect-error Edges may only originate at a named port.
+    const incompleteEdge: FlowDefinition = {
+      ...definition,
+      edges: [
+        {
+          id: 'missing-port',
+          source: { nodeId: 'compose' },
+          target: { nodeId: 'notify', portId: 'post' },
+        },
+      ],
+    };
+    expect(incompleteEdge).toBeDefined();
+  });
+});