@dailephd/my-frontend-observer 0.8.1

package/dist/domain/externalReferenceIdentity.d.ts

@@ -0,0 +1,38 @@
+import type { ExternalReferenceImageFormat } from './externalReferenceImage.js';
+import type { ReferenceRegion } from './externalReferenceRegions.js';
+import type { ExternalReferenceRequirement } from './externalReferenceRequirements.js';
+import type { ExternalReferenceApplicability } from './externalReferenceApplicability.js';
+/**
+ * Pure function of {imageSha256, format, width, height, supersedesReferenceId,
+ * regions?} - the semantic content of the reference image, which prior
+ * reference (if any) it explicitly supersedes, and (v0.7 Prompt 2 addition)
+ * its explicitly authored reference regions when present. Never includes a
+ * filesystem path, output location, a captured timestamp, or a
+ * caller-supplied label: two imports of byte-identical image content and
+ * region content from different operational locations, with different
+ * labels, produce the same logical identity; changing the image content, its
+ * detected format/dimensions, the supersession target, or the region set
+ * (added/removed/renamed/moved/resized) changes it.
+ *
+ * `regions`/`requirements`/`applicability` are each omitted from the hashed
+ * view entirely when not supplied (rather than included as `null`, unlike
+ * `supersedes`) so that every pre-Prompt-2/3/4 call site - and every later
+ * call that legitimately omits one of them - keeps producing byte-identical
+ * identity to the earlier prompt, never a new hash purely because a
+ * parameter now exists. Region/requirement order is part of the semantic
+ * view (authored order is semantic, mirroring domain/identity.ts's `targets`
+ * treatment) - canonicalize sorts object keys but deliberately never
+ * reorders arrays. `requirements` entries already carry their own
+ * content-derived `requirementId` (see externalReferenceRequirementIdentity.ts),
+ * so changing a selected property, tolerance, or category changes both that
+ * requirement's own id and this artifact-level identity.
+ */
+export declare function buildExternalReferenceRequestIdentity(imageSha256: string, format: ExternalReferenceImageFormat, width: number, height: number, supersedesReferenceId?: string, regions?: readonly ReferenceRegion[], requirements?: readonly ExternalReferenceRequirement[], applicability?: ExternalReferenceApplicability): string;
+/**
+ * Fresh, opaque per-persisted-instance identity - never derived from a
+ * timestamp alone, never collides even when called twice with the same
+ * requestIdentity within the same millisecond. Used both for a fresh import
+ * and for a fresh approval of an already-imported reference (same
+ * referenceRequestId, a new referenceId each time something is persisted).
+ */
+export declare function buildExternalReferenceInstanceIdentity(requestIdentity: string): string;

package/dist/domain/externalReferenceIdentity.js

@@ -0,0 +1,70 @@
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * Deliberately duplicated from domain/identity.ts#canonicalize (itself
+ * duplicated across comparisonIdentity.ts/frontendContractIdentity.ts) rather
+ * than imported - each identity module owns its own private canonicalize per
+ * existing repository convention. Same algorithm (sorted object keys,
+ * order-preserving arrays).
+ */
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([key, entryValue]) => [key, canonicalize(entryValue)]);
+        return Object.fromEntries(entries);
+    }
+    return value;
+}
+/**
+ * Pure function of {imageSha256, format, width, height, supersedesReferenceId,
+ * regions?} - the semantic content of the reference image, which prior
+ * reference (if any) it explicitly supersedes, and (v0.7 Prompt 2 addition)
+ * its explicitly authored reference regions when present. Never includes a
+ * filesystem path, output location, a captured timestamp, or a
+ * caller-supplied label: two imports of byte-identical image content and
+ * region content from different operational locations, with different
+ * labels, produce the same logical identity; changing the image content, its
+ * detected format/dimensions, the supersession target, or the region set
+ * (added/removed/renamed/moved/resized) changes it.
+ *
+ * `regions`/`requirements`/`applicability` are each omitted from the hashed
+ * view entirely when not supplied (rather than included as `null`, unlike
+ * `supersedes`) so that every pre-Prompt-2/3/4 call site - and every later
+ * call that legitimately omits one of them - keeps producing byte-identical
+ * identity to the earlier prompt, never a new hash purely because a
+ * parameter now exists. Region/requirement order is part of the semantic
+ * view (authored order is semantic, mirroring domain/identity.ts's `targets`
+ * treatment) - canonicalize sorts object keys but deliberately never
+ * reorders arrays. `requirements` entries already carry their own
+ * content-derived `requirementId` (see externalReferenceRequirementIdentity.ts),
+ * so changing a selected property, tolerance, or category changes both that
+ * requirement's own id and this artifact-level identity.
+ */
+export function buildExternalReferenceRequestIdentity(imageSha256, format, width, height, supersedesReferenceId, regions, requirements, applicability) {
+    const semanticView = {
+        imageSha256,
+        format,
+        width,
+        height,
+        supersedes: supersedesReferenceId ?? null,
+        ...(regions !== undefined ? { regions } : {}),
+        ...(requirements !== undefined ? { requirements } : {}),
+        ...(applicability !== undefined ? { applicability } : {}),
+    };
+    const serialized = JSON.stringify(canonicalize(semanticView));
+    return createHash('sha256').update(serialized).digest('hex');
+}
+/**
+ * Fresh, opaque per-persisted-instance identity - never derived from a
+ * timestamp alone, never collides even when called twice with the same
+ * requestIdentity within the same millisecond. Used both for a fresh import
+ * and for a fresh approval of an already-imported reference (same
+ * referenceRequestId, a new referenceId each time something is persisted).
+ */
+export function buildExternalReferenceInstanceIdentity(requestIdentity) {
+    const nonce = randomBytes(16).toString('hex');
+    return `${requestIdentity}-${nonce}`;
+}
+//# sourceMappingURL=externalReferenceIdentity.js.map

package/dist/domain/externalReferenceIdentity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"externalReferenceIdentity.js","sourceRoot":"","sources":["../../src/domain/externalReferenceIdentity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAMtD;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACzD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;aAC7D,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aAChD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,YAAY,CAAC,UAAU,CAAC,CAAU,CAAC,CAAC;QACxE,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,qCAAqC,CACnD,WAAmB,EACnB,MAAoC,EACpC,KAAa,EACb,MAAc,EACd,qBAA8B,EAC9B,OAAoC,EACpC,YAAsD,EACtD,aAA8C;IAE9C,MAAM,YAAY,GAAG;QACnB,WAAW;QACX,MAAM;QACN,KAAK;QACL,MAAM;QACN,UAAU,EAAE,qBAAqB,IAAI,IAAI;QACzC,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,GAAG,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1D,CAAC;IACF,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC;IAC9D,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sCAAsC,CAAC,eAAuB;IAC5E,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC9C,OAAO,GAAG,eAAe,IAAI,KAAK,EAAE,CAAC;AACvC,CAAC"}

package/dist/domain/externalReferenceImage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * v0.7 Prompt 1 external-reference image boundary. Pure, dependency-free,
+ * header/magic-byte-only parsing for the three formats
+ * EXTERNAL_REFERENCE_SUPPORTED_IMAGE_FORMATS freezes below - no image-processing
+ * framework, no OCR, no raster decoding, no computer vision. Every function
+ * here reads only bounded header bytes and never trusts a caller-declared
+ * file extension or MIME type.
+ */
+export declare const EXTERNAL_REFERENCE_SUPPORTED_IMAGE_FORMATS: readonly ["png", "jpeg", "webp"];
+export type ExternalReferenceImageFormat = (typeof EXTERNAL_REFERENCE_SUPPORTED_IMAGE_FORMATS)[number];
+export declare function isExternalReferenceImageFormat(value: unknown): value is ExternalReferenceImageFormat;
+/** Deliberately generous but bounded - reference images are design mockups/screenshots, never arbitrary large media. */
+export declare const EXTERNAL_REFERENCE_MAX_IMAGE_BYTES = 20000000;
+export declare const EXTERNAL_REFERENCE_MIN_DIMENSION_PX = 1;
+export declare const EXTERNAL_REFERENCE_MAX_DIMENSION_PX = 8192;
+/**
+ * Detects one of the three frozen formats from magic bytes only - never from a
+ * caller-supplied file extension or MIME type. Returns undefined for anything
+ * else, including a truncated/corrupted header of a genuinely supported
+ * format's signature bytes.
+ */
+export declare function detectExternalReferenceImageFormat(bytes: Uint8Array): ExternalReferenceImageFormat | undefined;
+export interface ImageDimensions {
+    width: number;
+    height: number;
+}
+/**
+ * Reads width/height from already-detected-format header bytes only - never
+ * decodes pixel data. Returns undefined (never a fabricated 0x0) for a
+ * truncated header or an unrecognized chunk layout within a genuinely
+ * supported container (e.g. an unrecognized WebP chunk kind).
+ */
+export declare function readExternalReferenceImageDimensions(bytes: Uint8Array, format: ExternalReferenceImageFormat): ImageDimensions | undefined;
+export declare function isValidExternalReferenceImageDimensions(dimensions: ImageDimensions): boolean;
+export declare function fileExtensionForFormat(format: ExternalReferenceImageFormat): string;

package/dist/domain/externalReferenceImage.js

@@ -0,0 +1,160 @@
+/**
+ * v0.7 Prompt 1 external-reference image boundary. Pure, dependency-free,
+ * header/magic-byte-only parsing for the three formats
+ * EXTERNAL_REFERENCE_SUPPORTED_IMAGE_FORMATS freezes below - no image-processing
+ * framework, no OCR, no raster decoding, no computer vision. Every function
+ * here reads only bounded header bytes and never trusts a caller-declared
+ * file extension or MIME type.
+ */
+export const EXTERNAL_REFERENCE_SUPPORTED_IMAGE_FORMATS = ['png', 'jpeg', 'webp'];
+export function isExternalReferenceImageFormat(value) {
+    return typeof value === 'string' && EXTERNAL_REFERENCE_SUPPORTED_IMAGE_FORMATS.includes(value);
+}
+/** Deliberately generous but bounded - reference images are design mockups/screenshots, never arbitrary large media. */
+export const EXTERNAL_REFERENCE_MAX_IMAGE_BYTES = 20_000_000;
+export const EXTERNAL_REFERENCE_MIN_DIMENSION_PX = 1;
+export const EXTERNAL_REFERENCE_MAX_DIMENSION_PX = 8192;
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+const JPEG_SIGNATURE = [0xff, 0xd8, 0xff];
+function bytesStartWith(bytes, signature) {
+    if (bytes.length < signature.length)
+        return false;
+    return signature.every((byte, index) => bytes[index] === byte);
+}
+function asciiAt(bytes, offset, length) {
+    if (bytes.length < offset + length)
+        return '';
+    let result = '';
+    for (let index = 0; index < length; index += 1) {
+        result += String.fromCharCode(bytes[offset + index]);
+    }
+    return result;
+}
+/**
+ * Detects one of the three frozen formats from magic bytes only - never from a
+ * caller-supplied file extension or MIME type. Returns undefined for anything
+ * else, including a truncated/corrupted header of a genuinely supported
+ * format's signature bytes.
+ */
+export function detectExternalReferenceImageFormat(bytes) {
+    if (bytesStartWith(bytes, PNG_SIGNATURE))
+        return 'png';
+    if (bytesStartWith(bytes, JPEG_SIGNATURE))
+        return 'jpeg';
+    if (asciiAt(bytes, 0, 4) === 'RIFF' && asciiAt(bytes, 8, 4) === 'WEBP')
+        return 'webp';
+    return undefined;
+}
+function readUInt32BE(bytes, offset) {
+    return ((bytes[offset] << 24) | (bytes[offset + 1] << 16) | (bytes[offset + 2] << 8) | bytes[offset + 3]) >>> 0;
+}
+function readUInt16BE(bytes, offset) {
+    return ((bytes[offset] << 8) | bytes[offset + 1]) >>> 0;
+}
+function readUInt32LE(bytes, offset) {
+    return ((bytes[offset + 3] << 24) | (bytes[offset + 2] << 16) | (bytes[offset + 1] << 8) | bytes[offset]) >>> 0;
+}
+/** PNG: the IHDR chunk is always the first chunk, immediately after the 8-byte signature, with a fixed 4-byte length + "IHDR" + width + height layout. */
+function readPngDimensions(bytes) {
+    if (bytes.length < 24)
+        return undefined;
+    if (asciiAt(bytes, 12, 4) !== 'IHDR')
+        return undefined;
+    return { width: readUInt32BE(bytes, 16), height: readUInt32BE(bytes, 20) };
+}
+/**
+ * JPEG: scan marker segments starting after the SOI (0xFFD8) for the first
+ * start-of-frame marker (every SOFn except the reserved/DHT/DAC 0xC4/0xC8/0xCC),
+ * which always carries height then width as two big-endian uint16s beginning
+ * 5 bytes into the segment payload. Bounded scan: stops at the end of the
+ * buffer rather than looping indefinitely on a truncated/malformed file.
+ */
+function readJpegDimensions(bytes) {
+    let offset = 2;
+    while (offset + 9 < bytes.length) {
+        if (bytes[offset] !== 0xff) {
+            offset += 1;
+            continue;
+        }
+        const marker = bytes[offset + 1];
+        if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+            offset += 2;
+            continue;
+        }
+        if (marker === 0xd9)
+            break;
+        const segmentLength = readUInt16BE(bytes, offset + 2);
+        const isSof = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+        if (isSof) {
+            return { height: readUInt16BE(bytes, offset + 5), width: readUInt16BE(bytes, offset + 7) };
+        }
+        if (segmentLength < 2)
+            return undefined;
+        offset += 2 + segmentLength;
+    }
+    return undefined;
+}
+/**
+ * WebP: the simple-lossy (VP8), simple-lossless (VP8L), and extended (VP8X)
+ * chunk layouts each encode dimensions differently. Only these three
+ * documented chunk shapes are parsed; anything else is honestly unsupported.
+ */
+function readWebpDimensions(bytes) {
+    const chunkId = asciiAt(bytes, 12, 4);
+    if (chunkId === 'VP8 ') {
+        if (bytes.length < 30)
+            return undefined;
+        return { width: readUInt16BE(bytes, 26) & 0x3fff, height: readUInt16BE(bytes, 28) & 0x3fff };
+    }
+    if (chunkId === 'VP8L') {
+        if (bytes.length < 25)
+            return undefined;
+        if (bytes[20] !== 0x2f)
+            return undefined;
+        const bits = readUInt32LE(bytes, 21);
+        return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 };
+    }
+    if (chunkId === 'VP8X') {
+        if (bytes.length < 30)
+            return undefined;
+        const width = ((bytes[24] | (bytes[25] << 8) | (bytes[26] << 16)) >>> 0) + 1;
+        const height = ((bytes[27] | (bytes[28] << 8) | (bytes[29] << 16)) >>> 0) + 1;
+        return { width, height };
+    }
+    return undefined;
+}
+/**
+ * Reads width/height from already-detected-format header bytes only - never
+ * decodes pixel data. Returns undefined (never a fabricated 0x0) for a
+ * truncated header or an unrecognized chunk layout within a genuinely
+ * supported container (e.g. an unrecognized WebP chunk kind).
+ */
+export function readExternalReferenceImageDimensions(bytes, format) {
+    switch (format) {
+        case 'png':
+            return readPngDimensions(bytes);
+        case 'jpeg':
+            return readJpegDimensions(bytes);
+        case 'webp':
+            return readWebpDimensions(bytes);
+    }
+}
+export function isValidExternalReferenceImageDimensions(dimensions) {
+    return (Number.isInteger(dimensions.width) &&
+        Number.isInteger(dimensions.height) &&
+        dimensions.width >= EXTERNAL_REFERENCE_MIN_DIMENSION_PX &&
+        dimensions.height >= EXTERNAL_REFERENCE_MIN_DIMENSION_PX &&
+        dimensions.width <= EXTERNAL_REFERENCE_MAX_DIMENSION_PX &&
+        dimensions.height <= EXTERNAL_REFERENCE_MAX_DIMENSION_PX);
+}
+export function fileExtensionForFormat(format) {
+    switch (format) {
+        case 'png':
+            return 'png';
+        case 'jpeg':
+            return 'jpg';
+        case 'webp':
+            return 'webp';
+    }
+}
+//# sourceMappingURL=externalReferenceImage.js.map

package/dist/domain/externalReferenceImage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"externalReferenceImage.js","sourceRoot":"","sources":["../../src/domain/externalReferenceImage.ts"],"names":[],"mappings":"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"}

package/dist/domain/externalReferenceRegionRelationships.d.ts

@@ -0,0 +1,63 @@
+/**
+ * v0.7 Prompt 2 reference-region relationship derivation. Reuses the exact
+ * same pure, tolerance-aware geometry predicates that
+ * domain/relationships.ts#deriveLayoutRelationships uses for runtime
+ * targets (horizontalOrderOf/verticalOrderOf/areaOverlapOf/relativeWidthOf/
+ * geometricFitOf/verticalSequenceOf, and the PairwiseRelationshipKind
+ * vocabulary/EvidenceReference type) - never a duplicated or reinterpreted
+ * copy of those formulas. Only the six geometry-only families apply here;
+ * DOM containment, scroll ownership, runtime visibility, and page-width-vs-
+ * viewport are runtime/browser concepts with no reference-image equivalent
+ * and are deliberately not reused (see docs/CONTRACTS.md).
+ *
+ * A reference relationship is a fact about the reference image's geometry
+ * only. It is never a design requirement, never a pass/fail verdict, and
+ * never claims a runtime target or source owner exists - those are later
+ * v0.7 prompts.
+ */
+import type { PairwiseRelationshipKind, EvidenceReference } from './relationships.js';
+import type { ReferenceRegion } from './externalReferenceRegions.js';
+/** Same bound-derivation shape as relationships.ts's MAX_PAIRWISE_RELATIONSHIP_PAIRS/RECORDS, over MAX_REFERENCE_REGIONS instead of the runtime-target limit - this is a maximum capacity, never a required minimum region count. */
+export declare const MAX_REFERENCE_REGION_PAIRS: number;
+export declare const REFERENCE_REGION_RELATIONSHIP_FAMILY_COUNT = 6;
+export declare const MAX_REFERENCE_REGION_RELATIONSHIP_RECORDS: number;
+/** One derived spatial relationship between two reference regions - subjectRegion/relatedRegion are region ids, deliberately named distinctly from PairwiseLayoutRelationship's subjectTarget/relatedTarget so a reference relationship can never be mistaken for a runtime-target relationship at the type level. */
+export interface ReferenceRegionRelationship {
+    kind: PairwiseRelationshipKind;
+    subjectRegion: string;
+    relatedRegion: string;
+    evidence: EvidenceReference[];
+}
+export declare function isValidReferenceRegionRelationship(value: unknown): value is ReferenceRegionRelationship;
+/** Bounded structured relationship graph for one reference's region set - never persisted (see externalReference.ts), always re-derivable on demand from the artifact's own `regions` field. */
+export interface ReferenceRegionRelationshipGraph {
+    referenceRequestId: string;
+    geometryTolerancePx: number;
+    regions: string[];
+    pairwiseRelationships: ReferenceRegionRelationship[];
+}
+export declare function isValidReferenceRegionRelationshipGraph(value: unknown): value is ReferenceRegionRelationshipGraph;
+export interface DeriveReferenceRegionRelationshipsOptions {
+    geometryTolerancePx?: number;
+}
+export type DeriveReferenceRegionRelationshipsResult = {
+    ok: true;
+    graph: ReferenceRegionRelationshipGraph;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The one canonical pure derivation from an authored region set to a
+ * ReferenceRegionRelationshipGraph - deterministic and synchronous: same
+ * `regions`/`geometryTolerancePx` in, same graph out, every time. Mirrors
+ * `deriveLayoutRelationships`'s pairwise-loop shape exactly (earlier
+ * authored region is always `subjectRegion` for every family except
+ * `follows-vertically`, whose direction is decided by actual geometry) but
+ * has no `unresolvedTargets`/`pageRelationships` concept: every authored
+ * region that reaches this function has already passed
+ * `isValidReferenceRegions`, so there is no "could not resolve" case, and a
+ * static image has no page/viewport to derive a page-level relationship
+ * from.
+ */
+export declare function deriveReferenceRegionRelationships(referenceRequestId: string, regions: readonly ReferenceRegion[], options?: DeriveReferenceRegionRelationshipsOptions): DeriveReferenceRegionRelationshipsResult;

package/dist/domain/externalReferenceRegionRelationships.js

@@ -0,0 +1,98 @@
+import { PAIRWISE_RELATIONSHIP_KINDS, isValidEvidenceReference, horizontalOrderOf, verticalOrderOf, areaOverlapOf, relativeWidthOf, geometricFitOf, verticalSequenceOf, } from './relationships.js';
+import { deriveReferenceRegionGeometry, MAX_REFERENCE_REGIONS } from './externalReferenceRegions.js';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Same bound-derivation shape as relationships.ts's MAX_PAIRWISE_RELATIONSHIP_PAIRS/RECORDS, over MAX_REFERENCE_REGIONS instead of the runtime-target limit - this is a maximum capacity, never a required minimum region count. */
+export const MAX_REFERENCE_REGION_PAIRS = (MAX_REFERENCE_REGIONS * (MAX_REFERENCE_REGIONS - 1)) / 2;
+export const REFERENCE_REGION_RELATIONSHIP_FAMILY_COUNT = 6;
+export const MAX_REFERENCE_REGION_RELATIONSHIP_RECORDS = MAX_REFERENCE_REGION_PAIRS * REFERENCE_REGION_RELATIONSHIP_FAMILY_COUNT;
+export function isValidReferenceRegionRelationship(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (typeof value.kind !== 'string' || !PAIRWISE_RELATIONSHIP_KINDS.includes(value.kind))
+        return false;
+    if (typeof value.subjectRegion !== 'string' || value.subjectRegion.length === 0)
+        return false;
+    if (typeof value.relatedRegion !== 'string' || value.relatedRegion.length === 0)
+        return false;
+    if (value.subjectRegion === value.relatedRegion)
+        return false;
+    return Array.isArray(value.evidence) && value.evidence.every((entry) => isValidEvidenceReference(entry));
+}
+export function isValidReferenceRegionRelationshipGraph(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (typeof value.referenceRequestId !== 'string' || value.referenceRequestId.length === 0)
+        return false;
+    if (typeof value.geometryTolerancePx !== 'number' || !Number.isFinite(value.geometryTolerancePx))
+        return false;
+    if (!Array.isArray(value.regions) || !value.regions.every((r) => typeof r === 'string' && r.length > 0))
+        return false;
+    if (new Set(value.regions).size !== value.regions.length)
+        return false;
+    const regionSet = new Set(value.regions);
+    if (!Array.isArray(value.pairwiseRelationships) || !value.pairwiseRelationships.every((r) => isValidReferenceRegionRelationship(r)))
+        return false;
+    if (value.pairwiseRelationships.length > MAX_REFERENCE_REGION_RELATIONSHIP_RECORDS)
+        return false;
+    for (const relationship of value.pairwiseRelationships) {
+        if (!regionSet.has(relationship.subjectRegion) || !regionSet.has(relationship.relatedRegion))
+            return false;
+    }
+    return true;
+}
+function regionGeometryEvidence(a, b) {
+    return [{ path: `regions.${a}.rectangle` }, { path: `regions.${b}.rectangle` }];
+}
+/**
+ * The one canonical pure derivation from an authored region set to a
+ * ReferenceRegionRelationshipGraph - deterministic and synchronous: same
+ * `regions`/`geometryTolerancePx` in, same graph out, every time. Mirrors
+ * `deriveLayoutRelationships`'s pairwise-loop shape exactly (earlier
+ * authored region is always `subjectRegion` for every family except
+ * `follows-vertically`, whose direction is decided by actual geometry) but
+ * has no `unresolvedTargets`/`pageRelationships` concept: every authored
+ * region that reaches this function has already passed
+ * `isValidReferenceRegions`, so there is no "could not resolve" case, and a
+ * static image has no page/viewport to derive a page-level relationship
+ * from.
+ */
+export function deriveReferenceRegionRelationships(referenceRequestId, regions, options = {}) {
+    if (regions.length > MAX_REFERENCE_REGIONS) {
+        return { ok: false, reason: `regions has ${regions.length} entries, exceeding the ${MAX_REFERENCE_REGIONS}-region relationship-derivation bound` };
+    }
+    const geometryTolerancePx = options.geometryTolerancePx ?? 0.5;
+    if (!Number.isFinite(geometryTolerancePx) || geometryTolerancePx < 0) {
+        return { ok: false, reason: 'geometryTolerancePx must be a non-negative finite number' };
+    }
+    const entries = regions.map((region) => ({ name: region.id, geometry: deriveReferenceRegionGeometry(region.rectangle) }));
+    const pairwiseRelationships = [];
+    for (let i = 0; i < entries.length; i += 1) {
+        const subject = entries[i];
+        for (let j = i + 1; j < entries.length; j += 1) {
+            const related = entries[j];
+            const evidence = regionGeometryEvidence(subject.name, related.name);
+            pairwiseRelationships.push({ kind: horizontalOrderOf(subject.geometry, related.geometry, geometryTolerancePx), subjectRegion: subject.name, relatedRegion: related.name, evidence }, { kind: verticalOrderOf(subject.geometry, related.geometry, geometryTolerancePx), subjectRegion: subject.name, relatedRegion: related.name, evidence }, { kind: areaOverlapOf(subject.geometry, related.geometry, geometryTolerancePx), subjectRegion: subject.name, relatedRegion: related.name, evidence }, { kind: relativeWidthOf(subject.geometry, related.geometry, geometryTolerancePx), subjectRegion: subject.name, relatedRegion: related.name, evidence }, { kind: geometricFitOf(subject.geometry, related.geometry, geometryTolerancePx), subjectRegion: subject.name, relatedRegion: related.name, evidence });
+            const sequence = verticalSequenceOf(subject, related, geometryTolerancePx);
+            if (sequence) {
+                pairwiseRelationships.push({
+                    kind: 'follows-vertically',
+                    subjectRegion: sequence.subjectTarget,
+                    relatedRegion: sequence.relatedTarget,
+                    evidence: regionGeometryEvidence(sequence.subjectTarget, sequence.relatedTarget),
+                });
+            }
+        }
+    }
+    return {
+        ok: true,
+        graph: {
+            referenceRequestId,
+            geometryTolerancePx,
+            regions: entries.map((entry) => entry.name),
+            pairwiseRelationships,
+        },
+    };
+}
+//# sourceMappingURL=externalReferenceRegionRelationships.js.map

package/dist/domain/externalReferenceRegionRelationships.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"externalReferenceRegionRelationships.js","sourceRoot":"","sources":["../../src/domain/externalReferenceRegionRelationships.ts"],"names":[],"mappings":"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"}

package/dist/domain/externalReferenceRegions.d.ts

@@ -0,0 +1,65 @@
+/**
+ * v0.7 Prompt 2 explicit reference-region geometry. A region is one
+ * user/configuration-authored rectangle in the coordinate system of an
+ * external reference image - origin at the image's top-left corner, x
+ * increasing rightward, y increasing downward, unit is reference-image
+ * pixels (never CSS pixels - this is a static image, not a rendered page).
+ * Coordinates may be fractional. This module never infers a region from
+ * pixel content: no OCR, no computer vision, no automatic segmentation.
+ *
+ * Only the rectangle {x, y, width, height} is canonical/authored; every
+ * other geometric fact (right, bottom, centerX, centerY) is a pure
+ * calculation over it (see deriveReferenceRegionGeometry) so that no
+ * redundant, potentially-drifting copy of the same fact is ever persisted.
+ */
+/** Same character/length convention as request/request.ts's target-name pattern (`^[A-Za-z0-9_-]{1,64}$`) - reused directly, not reinvented, for the same "stable, portable, log/path-safe identifier" reason. */
+export declare const REFERENCE_REGION_ID_PATTERN: RegExp;
+/** Same numeric bound as request/request.ts's MAX_TARGETS (20) - a coincidentally equal, independently-owned constant: reference regions are design-authoring input, not runtime targets, so the two are not structurally coupled even though they share a value and the same "bound the O(n^2) pairwise-relationship explosion" rationale (see externalReferenceRegionRelationships.ts). */
+export declare const MAX_REFERENCE_REGIONS = 20;
+export interface ReferenceRegionRectangle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ReferenceRegion {
+    id: string;
+    rectangle: ReferenceRegionRectangle;
+}
+/** Pure derived geometry over one region's canonical rectangle - never persisted, always recomputed, so it can never drift from {x, y, width, height}. */
+export interface ReferenceRegionGeometry {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    right: number;
+    bottom: number;
+    centerX: number;
+    centerY: number;
+}
+export declare function deriveReferenceRegionGeometry(rectangle: ReferenceRegionRectangle): ReferenceRegionGeometry;
+export type ReferenceRegionValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * Structural + numeric validation of one rectangle only - does not know
+ * about image bounds (see isValidReferenceRegions for the boundary check,
+ * which needs the owning image's dimensions). Fails closed on non-finite,
+ * negative, or zero width/height: authored design geometry is never
+ * silently clamped into validity.
+ */
+export declare function isValidReferenceRegionRectangle(value: unknown): ReferenceRegionValidationResult;
+export declare function isValidReferenceRegion(value: unknown): ReferenceRegionValidationResult;
+/**
+ * Collection-level validation: bounded count, unique IDs (case-insensitive,
+ * mirroring request/request.ts's target-name dedup convention), and every
+ * region's rectangle contained within the owning image's own dimensions -
+ * never silently clipped, rejected outright instead. `imageWidth`/
+ * `imageHeight` come from the artifact's own already-validated image
+ * metadata (ExternalReferenceImageReference or the approved artifact's
+ * sourceReference.image), never re-parsed here.
+ */
+export declare function isValidReferenceRegions(value: unknown, imageWidth: number, imageHeight: number): ReferenceRegionValidationResult;