@you-agent-factory/client 0.0.0 → 0.0.1

package/dist/visualization-layout-data.js

@@ -0,0 +1,105 @@
+const MAX_PLAIN_DATA_DEPTH = 64;
+export function isInputRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function dataPropertyPath(path, key, isArray) {
+    if (typeof key !== "string")
+        return path;
+    return [
+        ...path,
+        isArray && /^(?:0|[1-9]\d*)$/u.test(key) ? Number(key) : key,
+    ];
+}
+function reportNonPlainData(path, issues) {
+    issues.push({
+        category: "structure",
+        code: "non_plain_data",
+        path,
+        message: "Expected plain data with standard containers and own data properties.",
+    });
+}
+/** Reject behavior-bearing containers before the parser reads any input value. */
+export function validatePlainDataContainers(value, path, issues) {
+    if (typeof value !== "object" || value === null)
+        return;
+    const activeContainers = new WeakSet();
+    const frames = [{ value, path, depth: 0, leaving: false }];
+    while (frames.length > 0) {
+        const frame = frames.pop();
+        if (!frame)
+            break;
+        if (frame.leaving) {
+            activeContainers.delete(frame.value);
+            continue;
+        }
+        if (activeContainers.has(frame.value) ||
+            frame.depth > MAX_PLAIN_DATA_DEPTH) {
+            reportNonPlainData(frame.path, issues);
+            continue;
+        }
+        const isArray = Array.isArray(frame.value);
+        let prototype;
+        let keys;
+        try {
+            prototype = Object.getPrototypeOf(frame.value);
+            keys = Reflect.ownKeys(frame.value);
+        }
+        catch {
+            reportNonPlainData(frame.path, issues);
+            continue;
+        }
+        if ((isArray && prototype !== Array.prototype) ||
+            (!isArray && prototype !== Object.prototype && prototype !== null)) {
+            reportNonPlainData(frame.path, issues);
+            continue;
+        }
+        activeContainers.add(frame.value);
+        frames.push({ ...frame, leaving: true });
+        const childFrames = [];
+        for (const key of keys) {
+            if (isArray && key === "length")
+                continue;
+            const propertyPath = dataPropertyPath(frame.path, key, isArray);
+            let descriptor;
+            try {
+                descriptor = Object.getOwnPropertyDescriptor(frame.value, key);
+            }
+            catch {
+                reportNonPlainData(propertyPath, issues);
+                continue;
+            }
+            if (typeof key !== "string" ||
+                descriptor === undefined ||
+                !Object.hasOwn(descriptor, "value") ||
+                !descriptor.enumerable) {
+                reportNonPlainData(propertyPath, issues);
+                continue;
+            }
+            if (isArray && !/^(?:0|[1-9]\d*)$/u.test(key)) {
+                reportNonPlainData(propertyPath, issues);
+                continue;
+            }
+            if (typeof descriptor.value === "object" && descriptor.value !== null) {
+                childFrames.push({
+                    value: descriptor.value,
+                    path: propertyPath,
+                    depth: frame.depth + 1,
+                    leaving: false,
+                });
+            }
+        }
+        frames.push(...childFrames.reverse());
+    }
+}
+/** Copy validated values into fresh standard containers without prototype data. */
+export function clonePlainData(value) {
+    if (Array.isArray(value))
+        return value.map(clonePlainData);
+    if (typeof value !== "object" || value === null)
+        return value;
+    const clone = {};
+    for (const [key, child] of Object.entries(value)) {
+        clone[key] = clonePlainData(child);
+    }
+    return clone;
+}

package/dist/visualization-layout-error.d.ts

@@ -0,0 +1,5 @@
+import type { FactoryVisualizationLayoutIssue } from "./visualization-layout-contracts.js";
+export declare class FactoryVisualizationLayoutValidationError extends Error {
+    readonly issues: readonly FactoryVisualizationLayoutIssue[];
+    constructor(issues: readonly FactoryVisualizationLayoutIssue[]);
+}

package/dist/visualization-layout-error.js

@@ -0,0 +1,10 @@
+export class FactoryVisualizationLayoutValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(issues.length === 1
+            ? `Factory visualization layout validation failed: ${issues[0]?.message}`
+            : `Factory visualization layout validation failed with ${issues.length} issues`);
+        this.name = "FactoryVisualizationLayoutValidationError";
+        this.issues = issues;
+    }
+}

package/dist/visualization-layout-fields.d.ts

@@ -0,0 +1,7 @@
+export declare const layoutFields: Set<string>;
+export declare const noteFields: Set<string>;
+export declare const imageAnnotationFields: Set<string>;
+export declare const emptyStateFields: Set<string>;
+export declare const textContentFields: Set<string>;
+export declare const imageContentFields: Set<string>;
+export declare const imageSourceFields: Set<string>;

package/dist/visualization-layout-fields.js

@@ -0,0 +1,26 @@
+export const layoutFields = new Set([
+    "schemaVersion",
+    "annotations",
+    "nodeEmptyStates",
+]);
+export const noteFields = new Set([
+    "id",
+    "kind",
+    "position",
+    "size",
+    "title",
+    "body",
+    "tone",
+]);
+export const imageAnnotationFields = new Set([
+    "id",
+    "kind",
+    "position",
+    "size",
+    "altText",
+    "source",
+]);
+export const emptyStateFields = new Set(["nodeId", "content"]);
+export const textContentFields = new Set(["kind", "text"]);
+export const imageContentFields = new Set(["kind", "altText", "source"]);
+export const imageSourceFields = new Set(["kind", "mediaType", "base64"]);

package/dist/visualization-layout-geometry.d.ts

@@ -0,0 +1,5 @@
+import type { FactoryVisualizationLayoutIssue } from "./visualization-layout-contracts.js";
+type InputPath = readonly (string | number)[];
+export declare function validatePosition(input: unknown, path: InputPath, issues: FactoryVisualizationLayoutIssue[]): void;
+export declare function validateSize(input: unknown, path: InputPath, issues: FactoryVisualizationLayoutIssue[]): void;
+export {};

package/dist/visualization-layout-geometry.js

@@ -0,0 +1,74 @@
+import { isInvalidCoordinate, isInvalidDimension, MAX_ANNOTATION_COORDINATE, MAX_ANNOTATION_DIMENSION, MIN_ANNOTATION_COORDINATE, } from "./visualization-layout-safety.js";
+function validateNumericShape(input, fields, path, label, issues) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        issues.push({
+            category: "structure",
+            code: "invalid_type",
+            path,
+            message: `Expected ${label} to be an object.`,
+        });
+        return undefined;
+    }
+    const record = input;
+    for (const key of Object.keys(record)) {
+        if (!fields.includes(key)) {
+            issues.push({
+                category: "structure",
+                code: "unsupported_field",
+                path: [...path, key],
+                message: `Unsupported field ${key}.`,
+            });
+        }
+    }
+    for (const field of fields) {
+        if (!Object.hasOwn(record, field)) {
+            issues.push({
+                category: "structure",
+                code: "missing_required_field",
+                path: [...path, field],
+                message: `Expected required field ${field}.`,
+            });
+        }
+        else if (typeof record[field] !== "number") {
+            issues.push({
+                category: "structure",
+                code: "invalid_type",
+                path: [...path, field],
+                message: `Expected ${field} to be a number.`,
+            });
+        }
+    }
+    return record;
+}
+export function validatePosition(input, path, issues) {
+    const position = validateNumericShape(input, ["x", "y"], path, "position", issues);
+    if (!position)
+        return;
+    for (const coordinate of ["x", "y"]) {
+        const value = position[coordinate];
+        if (typeof value === "number" && isInvalidCoordinate(value)) {
+            issues.push({
+                category: "semantic",
+                code: "invalid_coordinate",
+                path: [...path, coordinate],
+                message: `Expected ${coordinate} to be finite and between ${MIN_ANNOTATION_COORDINATE} and ${MAX_ANNOTATION_COORDINATE}.`,
+            });
+        }
+    }
+}
+export function validateSize(input, path, issues) {
+    const size = validateNumericShape(input, ["width", "height"], path, "size", issues);
+    if (!size)
+        return;
+    for (const dimension of ["width", "height"]) {
+        const value = size[dimension];
+        if (typeof value === "number" && isInvalidDimension(value)) {
+            issues.push({
+                category: "semantic",
+                code: "invalid_dimension",
+                path: [...path, dimension],
+                message: `Expected ${dimension} to be finite, greater than zero, and at most ${MAX_ANNOTATION_DIMENSION}.`,
+            });
+        }
+    }
+}

package/dist/visualization-layout-media.d.ts

@@ -0,0 +1,11 @@
+import type { FactoryVisualizationLayoutIssue } from "./visualization-layout-contracts.js";
+type InputPath = readonly (string | number)[];
+export declare const MAX_EMBEDDED_IMAGE_BYTES: number;
+export declare const MAX_LAYOUT_IMAGE_BYTES: number;
+export declare const MAX_IMAGE_ALT_TEXT_LENGTH = 500;
+export interface ImageByteBudget {
+    total: number;
+    aggregateLimitReported: boolean;
+}
+export declare function validateEmbeddedImageData(base64: string, mediaType: string, path: InputPath, issues: FactoryVisualizationLayoutIssue[], budget: ImageByteBudget): void;
+export {};

package/dist/visualization-layout-media.js

@@ -0,0 +1,110 @@
+export const MAX_EMBEDDED_IMAGE_BYTES = 2 * 1024 * 1024;
+export const MAX_LAYOUT_IMAGE_BYTES = 8 * 1024 * 1024;
+export const MAX_IMAGE_ALT_TEXT_LENGTH = 500;
+const canonicalPaddedBase64 = /^(?:[A-Za-z\d+/]{4})*(?:[A-Za-z\d+/]{2}==|[A-Za-z\d+/]{3}=)?$/u;
+const base64Alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function decodedByteLength(value) {
+    const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+    return (value.length / 4) * 3 - padding;
+}
+function isCanonicalBase64(value) {
+    if (!canonicalPaddedBase64.test(value))
+        return false;
+    if (value.endsWith("==")) {
+        return (base64Alphabet.indexOf(value[value.length - 3] ?? "") & 0x0f) === 0;
+    }
+    if (value.endsWith("=")) {
+        return (base64Alphabet.indexOf(value[value.length - 2] ?? "") & 0x03) === 0;
+    }
+    return true;
+}
+function decodePrefix(value, byteLimit) {
+    const decoded = new Uint8Array(Math.min(decodedByteLength(value), byteLimit));
+    let decodedIndex = 0;
+    for (let index = 0; index < value.length && decodedIndex < byteLimit; index += 4) {
+        const first = base64Alphabet.indexOf(value[index] ?? "");
+        const second = base64Alphabet.indexOf(value[index + 1] ?? "");
+        const thirdCharacter = value[index + 2] ?? "=";
+        const fourthCharacter = value[index + 3] ?? "=";
+        const third = thirdCharacter === "=" ? 0 : base64Alphabet.indexOf(thirdCharacter);
+        const fourth = fourthCharacter === "=" ? 0 : base64Alphabet.indexOf(fourthCharacter);
+        const bits = (first << 18) | (second << 12) | (third << 6) | fourth;
+        decoded[decodedIndex] = (bits >> 16) & 0xff;
+        decodedIndex += 1;
+        if (thirdCharacter !== "=" && decodedIndex < decoded.length) {
+            decoded[decodedIndex] = (bits >> 8) & 0xff;
+            decodedIndex += 1;
+        }
+        if (fourthCharacter !== "=" && decodedIndex < decoded.length) {
+            decoded[decodedIndex] = bits & 0xff;
+            decodedIndex += 1;
+        }
+    }
+    return decoded;
+}
+function startsWith(bytes, signature) {
+    return (bytes.length >= signature.length &&
+        signature.every((byte, index) => bytes[index] === byte));
+}
+function signatureMatches(mediaType, bytes) {
+    if (mediaType === "image/png") {
+        return startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    }
+    if (mediaType === "image/jpeg") {
+        return startsWith(bytes, [0xff, 0xd8, 0xff]);
+    }
+    return (mediaType === "image/webp" &&
+        startsWith(bytes, [0x52, 0x49, 0x46, 0x46]) &&
+        bytes.length >= 12 &&
+        bytes[8] === 0x57 &&
+        bytes[9] === 0x45 &&
+        bytes[10] === 0x42 &&
+        bytes[11] === 0x50);
+}
+export function validateEmbeddedImageData(base64, mediaType, path, issues, budget) {
+    if (!isCanonicalBase64(base64)) {
+        issues.push({
+            category: "semantic",
+            code: "invalid_base64",
+            path,
+            message: "Expected strict canonical padded base64 without whitespace or a data-URL prefix.",
+        });
+        return;
+    }
+    const byteLength = decodedByteLength(base64);
+    if (byteLength === 0) {
+        issues.push({
+            category: "semantic",
+            code: "empty_image_payload",
+            path,
+            message: "Expected an embedded image with a non-empty decoded payload.",
+        });
+        return;
+    }
+    if (byteLength > MAX_EMBEDDED_IMAGE_BYTES) {
+        issues.push({
+            category: "semantic",
+            code: "image_too_large",
+            path,
+            message: `Expected each decoded image to contain at most ${MAX_EMBEDDED_IMAGE_BYTES} bytes.`,
+        });
+    }
+    budget.total += byteLength;
+    if (budget.total > MAX_LAYOUT_IMAGE_BYTES && !budget.aggregateLimitReported) {
+        budget.aggregateLimitReported = true;
+        issues.push({
+            category: "semantic",
+            code: "aggregate_image_bytes_exceeded",
+            path,
+            message: `This image occurrence raises the combined decoded image size above ${MAX_LAYOUT_IMAGE_BYTES} bytes.`,
+        });
+    }
+    if (signatureMatches(mediaType, decodePrefix(base64, 12)))
+        return;
+    issues.push({
+        category: "semantic",
+        code: "image_media_type_mismatch",
+        path,
+        message: `Decoded image signature does not match declared media type ${mediaType}.`,
+    });
+}

package/dist/visualization-layout-safety.d.ts

@@ -0,0 +1,15 @@
+import type { FactoryVisualizationLayoutIssue } from "./visualization-layout-contracts.js";
+type InputPath = readonly (string | number)[];
+export declare const MIN_ANNOTATION_COORDINATE = -100000;
+export declare const MAX_ANNOTATION_COORDINATE = 100000;
+export declare const MAX_ANNOTATION_DIMENSION = 10000;
+export declare const MAX_NOTE_TITLE_LENGTH = 160;
+export declare const MAX_NOTE_BODY_LENGTH = 4000;
+export declare const MAX_EMPTY_STATE_TEXT_LENGTH = 500;
+export declare function validatePlainText(value: string, path: InputPath, maxLength: number, label: string, issues: FactoryVisualizationLayoutIssue[], requireNonWhitespace: boolean): void;
+export declare function isUnsafeContentField(field: string): boolean;
+export declare function isInvalidCoordinate(value: number): boolean;
+export declare function isInvalidDimension(value: number): boolean;
+export declare function validateDuplicateAnnotationIds(annotations: readonly unknown[], issues: FactoryVisualizationLayoutIssue[]): void;
+export declare function validateDuplicateNodeIds(emptyStates: readonly unknown[], issues: FactoryVisualizationLayoutIssue[]): void;
+export {};

package/dist/visualization-layout-safety.js

@@ -0,0 +1,142 @@
+import { marked } from "marked";
+export const MIN_ANNOTATION_COORDINATE = -100_000;
+export const MAX_ANNOTATION_COORDINATE = 100_000;
+export const MAX_ANNOTATION_DIMENSION = 10_000;
+export const MAX_NOTE_TITLE_LENGTH = 160;
+export const MAX_NOTE_BODY_LENGTH = 4_000;
+export const MAX_EMPTY_STATE_TEXT_LENGTH = 500;
+function containsFormattedToken(tokens) {
+    for (const token of tokens) {
+        if (token.type !== "paragraph" &&
+            token.type !== "text" &&
+            token.type !== "space") {
+            return true;
+        }
+        if ("tokens" in token &&
+            token.tokens &&
+            containsFormattedToken(token.tokens)) {
+            return true;
+        }
+    }
+    return false;
+}
+function containsMarkdown(value) {
+    // Undefined reference labels are plain text to a renderer, but still carry
+    // Markdown syntax that could become active when combined with a definition.
+    return (containsFormattedToken(marked.lexer(value, { gfm: true })) ||
+        /!?\[[^\]\n]*\]\[[^\]\n]*\]/u.test(value));
+}
+function unsafeTextMatch(value) {
+    if (/<!--|<!doctype\b|<\/?[a-z][^>]*>/iu.test(value)) {
+        return {
+            code: "unsafe_html",
+            message: "Expected inert plain text without HTML or media markup.",
+        };
+    }
+    if (/(?:\b(?:https?|ftp|file|data|javascript|mailto):|\bwww\.)\S*/iu.test(value)) {
+        return {
+            code: "unsafe_uri",
+            message: "Expected inert plain text without URI-bearing content.",
+        };
+    }
+    if (containsMarkdown(value)) {
+        return {
+            code: "unsafe_markdown",
+            message: "Expected inert plain text without Markdown or links.",
+        };
+    }
+    return undefined;
+}
+export function validatePlainText(value, path, maxLength, label, issues, requireNonWhitespace) {
+    if (requireNonWhitespace && value.trim().length === 0) {
+        issues.push({
+            category: "semantic",
+            code: "empty_text",
+            path,
+            message: `Expected ${label} to contain non-whitespace text.`,
+        });
+    }
+    if ([...value].length > maxLength) {
+        issues.push({
+            category: "semantic",
+            code: "text_too_long",
+            path,
+            message: `Expected ${label} to contain at most ${maxLength} characters.`,
+        });
+    }
+    const unsafe = unsafeTextMatch(value);
+    if (unsafe) {
+        issues.push({
+            category: "semantic",
+            code: unsafe.code,
+            path,
+            message: unsafe.message,
+        });
+    }
+}
+export function isUnsafeContentField(field) {
+    return /^(?:callback|command|connection|connections|edge|edges|event|handler|href|html|link|markdown|onclick|route|script|src|uri|url)$/iu.test(field);
+}
+export function isInvalidCoordinate(value) {
+    return (!Number.isFinite(value) ||
+        value < MIN_ANNOTATION_COORDINATE ||
+        value > MAX_ANNOTATION_COORDINATE);
+}
+export function isInvalidDimension(value) {
+    return (!Number.isFinite(value) || value <= 0 || value > MAX_ANNOTATION_DIMENSION);
+}
+export function validateDuplicateAnnotationIds(annotations, issues) {
+    const indexesById = new Map();
+    for (const [index, annotation] of annotations.entries()) {
+        const record = annotation;
+        if (typeof annotation !== "object" ||
+            annotation === null ||
+            !Object.hasOwn(record, "id") ||
+            typeof record.id !== "string") {
+            continue;
+        }
+        const indexes = indexesById.get(record.id) ?? [];
+        indexes.push(index);
+        indexesById.set(record.id, indexes);
+    }
+    for (const [id, indexes] of indexesById) {
+        if (indexes.length < 2)
+            continue;
+        for (const index of indexes) {
+            issues.push({
+                category: "semantic",
+                code: "duplicate_annotation_id",
+                path: ["annotations", index, "id"],
+                message: `Annotation ID ${id} is duplicated at annotation indexes ${indexes.join(", ")}.`,
+            });
+        }
+    }
+}
+export function validateDuplicateNodeIds(emptyStates, issues) {
+    const indexesById = new Map();
+    for (const [index, emptyState] of emptyStates.entries()) {
+        const record = emptyState;
+        if (typeof emptyState !== "object" ||
+            emptyState === null ||
+            !Object.hasOwn(record, "nodeId") ||
+            typeof record.nodeId !== "string" ||
+            record.nodeId.trim().length === 0) {
+            continue;
+        }
+        const indexes = indexesById.get(record.nodeId) ?? [];
+        indexes.push(index);
+        indexesById.set(record.nodeId, indexes);
+    }
+    for (const [nodeId, indexes] of indexesById) {
+        if (indexes.length < 2)
+            continue;
+        for (const index of indexes) {
+            issues.push({
+                category: "semantic",
+                code: "duplicate_node_id",
+                path: ["nodeEmptyStates", index, "nodeId"],
+                message: `Canonical node ID ${nodeId} is duplicated at empty-state indexes ${indexes.join(", ")}.`,
+            });
+        }
+    }
+}

package/dist/visualization-layout-topology.d.ts

@@ -0,0 +1,11 @@
+import type { FactoryDefinition } from "./contracts.js";
+import type { FactoryVisualizationLayoutIssue } from "./visualization-layout-contracts.js";
+type InputPath = readonly (string | number)[];
+/**
+ * Project the canonical node IDs that the existing Factory graph projection
+ * derives from authored entities and references. This is data-only and does
+ * not read or update graph-editor state.
+ */
+export declare function factoryVisualizationCanonicalNodeIds(factory: Readonly<FactoryDefinition>): ReadonlySet<string>;
+export declare function validateCanonicalNodeId(nodeId: string, path: InputPath, canonicalNodeIds: ReadonlySet<string>, issues: FactoryVisualizationLayoutIssue[]): void;
+export {};

package/dist/visualization-layout-topology.js

@@ -0,0 +1,90 @@
+function entityIdentifier(explicitId, fallbackName) {
+    const normalizedId = explicitId?.trim();
+    return normalizedId ? normalizedId : fallbackName;
+}
+function addSubjectNode(nodeIds, kind, explicitId, fallbackName) {
+    nodeIds.add(`${kind}:${entityIdentifier(explicitId, fallbackName)}`);
+}
+/**
+ * Project the canonical node IDs that the existing Factory graph projection
+ * derives from authored entities and references. This is data-only and does
+ * not read or update graph-editor state.
+ */
+export function factoryVisualizationCanonicalNodeIds(factory) {
+    const nodeIds = new Set();
+    const resourceIds = new Map();
+    const workerIds = new Map();
+    const workTypeIds = new Map();
+    const stateIds = new Map();
+    for (const file of factory.supportingFiles?.bundledFiles ?? []) {
+        const targetPath = file.targetPath?.trim();
+        if (targetPath)
+            addSubjectNode(nodeIds, "doc", targetPath, targetPath);
+    }
+    for (const resource of factory.resources ?? []) {
+        if (resource.id?.trim())
+            resourceIds.set(resource.name, resource.id);
+        addSubjectNode(nodeIds, "resource", resource.id, resource.name);
+    }
+    for (const worker of factory.workers ?? []) {
+        if (worker.id?.trim())
+            workerIds.set(worker.name, worker.id);
+        addSubjectNode(nodeIds, "worker", worker.id, worker.name);
+        for (const resource of worker.resources ?? []) {
+            addSubjectNode(nodeIds, "resource", resourceIds.get(resource.name), resource.name);
+        }
+    }
+    for (const workType of factory.workTypes ?? []) {
+        if (workType.id?.trim())
+            workTypeIds.set(workType.name, workType.id);
+        addSubjectNode(nodeIds, "work-type", workType.id, workType.name);
+        const workTypeStateIds = new Map();
+        for (const state of workType.states) {
+            if (state.id?.trim())
+                workTypeStateIds.set(state.name, state.id);
+            nodeIds.add(`work-state:${entityIdentifier(workType.id, workType.name)}:${entityIdentifier(state.id, state.name)}`);
+        }
+        stateIds.set(workType.name, workTypeStateIds);
+    }
+    const addWorkState = (workTypeName, stateName) => {
+        nodeIds.add(`work-state:${entityIdentifier(workTypeIds.get(workTypeName), workTypeName)}:${entityIdentifier(stateIds.get(workTypeName)?.get(stateName), stateName)}`);
+    };
+    for (const workstation of factory.workstations ?? []) {
+        addSubjectNode(nodeIds, "workstation", workstation.id, workstation.name);
+        const workerName = workstation.worker.trim();
+        if (workerName) {
+            addSubjectNode(nodeIds, "worker", workerIds.get(workerName), workerName);
+        }
+        for (const resource of workstation.resources ?? []) {
+            addSubjectNode(nodeIds, "resource", resourceIds.get(resource.name), resource.name);
+        }
+        for (const route of [
+            ...(workstation.inputs ?? []),
+            ...(workstation.outputs ?? []),
+            ...(workstation.onContinue ?? []),
+            ...(workstation.onFailure ?? []),
+            ...(workstation.onRejection ?? []),
+        ]) {
+            addWorkState(route.workType, route.state);
+        }
+    }
+    return nodeIds;
+}
+export function validateCanonicalNodeId(nodeId, path, canonicalNodeIds, issues) {
+    if (nodeId.trim().length === 0) {
+        issues.push({
+            category: "semantic",
+            code: "empty_node_id",
+            path,
+            message: "Expected a non-blank canonical topology node ID.",
+        });
+    }
+    else if (!canonicalNodeIds.has(nodeId)) {
+        issues.push({
+            category: "semantic",
+            code: "unknown_canonical_node_id",
+            path,
+            message: `Canonical topology node ${nodeId} does not exist in the supplied Factory.`,
+        });
+    }
+}

package/dist/visualization-layout.d.ts

@@ -0,0 +1,12 @@
+import type { FactoryDefinition } from "./contracts.js";
+import { type FactoryVisualizationLayoutV1, type SafeParseFactoryVisualizationLayoutResult } from "./visualization-layout-contracts.js";
+/** A prepared topology can supply its canonical node IDs without owning Factory state. */
+export interface FactoryVisualizationLayoutCanonicalNodeContext {
+    canonicalNodeIds: ReadonlySet<string>;
+}
+/**
+ * Validate presentation metadata beside an immutable canonical Factory.
+ * The Factory is accepted as context but is never modified or included in the result.
+ */
+export declare function safeParseFactoryVisualizationLayout(input: unknown, factory: Readonly<FactoryDefinition> | FactoryVisualizationLayoutCanonicalNodeContext): SafeParseFactoryVisualizationLayoutResult;
+export declare function parseFactoryVisualizationLayout(input: unknown, factory: Readonly<FactoryDefinition> | FactoryVisualizationLayoutCanonicalNodeContext): FactoryVisualizationLayoutV1;