@you-agent-factory/client 0.0.0 → 0.0.1

package/dist/visualization-layout.js

@@ -0,0 +1,299 @@
+import { FACTORY_VISUALIZATION_LAYOUT_SCHEMA_VERSION, } from "./visualization-layout-contracts.js";
+import { clonePlainData, isInputRecord, validatePlainDataContainers, } from "./visualization-layout-data.js";
+import { FactoryVisualizationLayoutValidationError } from "./visualization-layout-error.js";
+import { emptyStateFields, imageAnnotationFields, imageContentFields, imageSourceFields, layoutFields, noteFields, textContentFields, } from "./visualization-layout-fields.js";
+import { validatePosition, validateSize, } from "./visualization-layout-geometry.js";
+import { MAX_IMAGE_ALT_TEXT_LENGTH, validateEmbeddedImageData, } from "./visualization-layout-media.js";
+import { isUnsafeContentField, MAX_EMPTY_STATE_TEXT_LENGTH, MAX_NOTE_BODY_LENGTH, MAX_NOTE_TITLE_LENGTH, validateDuplicateAnnotationIds, validateDuplicateNodeIds, validatePlainText, } from "./visualization-layout-safety.js";
+import { factoryVisualizationCanonicalNodeIds, validateCanonicalNodeId, } from "./visualization-layout-topology.js";
+const imageMediaTypes = new Set(["image/png", "image/jpeg", "image/webp"]);
+const noteTones = new Set([
+    "neutral",
+    "accent",
+    "info",
+    "success",
+    "warning",
+    "danger",
+]);
+function unsupportedFields(value, fields, path, issues) {
+    for (const key of Object.keys(value)) {
+        if (!fields.has(key)) {
+            issues.push({
+                category: "structure",
+                code: "unsupported_field",
+                path: [...path, key],
+                message: `Unsupported field ${key}.`,
+            });
+            if (isUnsafeContentField(key)) {
+                issues.push({
+                    category: "semantic",
+                    code: "unsafe_content_field",
+                    path: [...path, key],
+                    message: `Executable, connection-like, and URI-bearing content field ${key} is not allowed.`,
+                });
+            }
+        }
+    }
+}
+function requiredField(value, key, path, issues) {
+    if (Object.hasOwn(value, key))
+        return true;
+    issues.push({
+        category: "structure",
+        code: "missing_required_field",
+        path: [...path, key],
+        message: `Expected required field ${key}.`,
+    });
+    return false;
+}
+function stringField(value, key, path, issues, required = true) {
+    if (!requiredField(value, key, path, required ? issues : []))
+        return false;
+    if (!Object.hasOwn(value, key))
+        return true;
+    if (typeof value[key] === "string")
+        return true;
+    issues.push({
+        category: "structure",
+        code: "invalid_type",
+        path: [...path, key],
+        message: `Expected ${key} to be a string.`,
+    });
+    return false;
+}
+function validateImageSource(input, path, issues, imageBudget) {
+    if (!isInputRecord(input)) {
+        issues.push({
+            category: "structure",
+            code: "invalid_type",
+            path,
+            message: "Expected image source to be an object.",
+        });
+        return;
+    }
+    unsupportedFields(input, imageSourceFields, path, issues);
+    if (stringField(input, "kind", path, issues) && input.kind !== "embedded") {
+        issues.push({
+            category: "structure",
+            code: "invalid_value",
+            path: [...path, "kind"],
+            message: "Expected image source kind embedded.",
+        });
+    }
+    const validMediaType = stringField(input, "mediaType", path, issues);
+    if (validMediaType && !imageMediaTypes.has(input.mediaType)) {
+        issues.push({
+            category: "semantic",
+            code: "unsupported_image_media_type",
+            path: [...path, "mediaType"],
+            message: "Expected a supported embedded raster media type.",
+        });
+    }
+    const validBase64Type = stringField(input, "base64", path, issues);
+    if (validBase64Type &&
+        validMediaType &&
+        typeof input.base64 === "string" &&
+        typeof input.mediaType === "string" &&
+        imageMediaTypes.has(input.mediaType)) {
+        validateEmbeddedImageData(input.base64, input.mediaType, [...path, "base64"], issues, imageBudget);
+    }
+}
+function validateImageContent(input, path, fields, issues, imageBudget) {
+    unsupportedFields(input, fields, path, issues);
+    if (stringField(input, "altText", path, issues)) {
+        validatePlainText(input.altText, [...path, "altText"], MAX_IMAGE_ALT_TEXT_LENGTH, "image alternative text", issues, true);
+    }
+    if (requiredField(input, "source", path, issues)) {
+        validateImageSource(input.source, [...path, "source"], issues, imageBudget);
+    }
+}
+function validateAnnotation(input, index, issues, imageBudget) {
+    const path = ["annotations", index];
+    if (!isInputRecord(input)) {
+        issues.push({
+            category: "structure",
+            code: "invalid_type",
+            path,
+            message: "Expected annotation to be an object.",
+        });
+        return;
+    }
+    stringField(input, "id", path, issues);
+    if (!stringField(input, "kind", path, issues))
+        return;
+    if (input.kind !== "note" && input.kind !== "image") {
+        issues.push({
+            category: "structure",
+            code: "invalid_annotation_kind",
+            path: [...path, "kind"],
+            message: `Unsupported annotation kind ${input.kind}.`,
+        });
+        return;
+    }
+    if (input.kind === "note") {
+        unsupportedFields(input, noteFields, path, issues);
+        if (stringField(input, "body", path, issues)) {
+            validatePlainText(input.body, [...path, "body"], MAX_NOTE_BODY_LENGTH, "note body", issues, true);
+        }
+        if (stringField(input, "title", path, issues, false) &&
+            typeof input.title === "string") {
+            validatePlainText(input.title, [...path, "title"], MAX_NOTE_TITLE_LENGTH, "note title", issues, false);
+        }
+        if (stringField(input, "tone", path, issues, false) &&
+            input.tone !== undefined &&
+            !noteTones.has(input.tone)) {
+            issues.push({
+                category: "structure",
+                code: "unsupported_note_tone",
+                path: [...path, "tone"],
+                message: `Unsupported note tone ${input.tone}.`,
+            });
+        }
+        if (Object.hasOwn(input, "size")) {
+            validateSize(input.size, [...path, "size"], issues);
+        }
+    }
+    else {
+        validateImageContent(input, path, imageAnnotationFields, issues, imageBudget);
+        if (requiredField(input, "size", path, issues)) {
+            validateSize(input.size, [...path, "size"], issues);
+        }
+    }
+    if (requiredField(input, "position", path, issues)) {
+        validatePosition(input.position, [...path, "position"], issues);
+    }
+}
+function validateEmptyStateContent(input, path, issues, imageBudget) {
+    if (!isInputRecord(input)) {
+        issues.push({
+            category: "structure",
+            code: "invalid_type",
+            path,
+            message: "Expected empty-state content to be an object.",
+        });
+        return;
+    }
+    if (!stringField(input, "kind", path, issues))
+        return;
+    if (input.kind === "text") {
+        unsupportedFields(input, textContentFields, path, issues);
+        if (stringField(input, "text", path, issues)) {
+            validatePlainText(input.text, [...path, "text"], MAX_EMPTY_STATE_TEXT_LENGTH, "node empty-state text", issues, true);
+        }
+        return;
+    }
+    if (input.kind === "image") {
+        validateImageContent(input, path, imageContentFields, issues, imageBudget);
+        return;
+    }
+    issues.push({
+        category: "structure",
+        code: "invalid_empty_state_kind",
+        path: [...path, "kind"],
+        message: `Unsupported empty-state content kind ${input.kind}.`,
+    });
+}
+function validateNodeEmptyState(input, index, issues, imageBudget, canonicalNodeIds) {
+    const path = ["nodeEmptyStates", index];
+    if (!isInputRecord(input)) {
+        issues.push({
+            category: "structure",
+            code: "invalid_type",
+            path,
+            message: "Expected node empty state to be an object.",
+        });
+        return;
+    }
+    unsupportedFields(input, emptyStateFields, path, issues);
+    if (stringField(input, "nodeId", path, issues)) {
+        validateCanonicalNodeId(input.nodeId, [...path, "nodeId"], canonicalNodeIds, issues);
+    }
+    if (requiredField(input, "content", path, issues)) {
+        validateEmptyStateContent(input.content, [...path, "content"], issues, imageBudget);
+    }
+}
+/**
+ * Validate presentation metadata beside an immutable canonical Factory.
+ * The Factory is accepted as context but is never modified or included in the result.
+ */
+export function safeParseFactoryVisualizationLayout(input, factory) {
+    if (!isInputRecord(input)) {
+        return {
+            success: false,
+            issues: [
+                {
+                    category: "structure",
+                    code: "invalid_type",
+                    path: [],
+                    message: "Expected Factory visualization layout to be an object.",
+                },
+            ],
+        };
+    }
+    const issues = [];
+    validatePlainDataContainers(input, [], issues);
+    if (issues.length > 0)
+        return { success: false, issues };
+    const imageBudget = {
+        total: 0,
+        aggregateLimitReported: false,
+    };
+    const canonicalNodeIds = "canonicalNodeIds" in factory
+        ? factory.canonicalNodeIds
+        : factoryVisualizationCanonicalNodeIds(factory);
+    unsupportedFields(input, layoutFields, [], issues);
+    if (stringField(input, "schemaVersion", [], issues) &&
+        input.schemaVersion !== FACTORY_VISUALIZATION_LAYOUT_SCHEMA_VERSION) {
+        issues.push({
+            category: "structure",
+            code: "unsupported_layout_schema_version",
+            path: ["schemaVersion"],
+            message: `Unsupported Factory visualization layout schema version: ${input.schemaVersion}.`,
+        });
+    }
+    if (Object.hasOwn(input, "annotations")) {
+        if (!Array.isArray(input.annotations)) {
+            issues.push({
+                category: "structure",
+                code: "invalid_type",
+                path: ["annotations"],
+                message: "Expected annotations to be an array.",
+            });
+        }
+        else {
+            for (const [index, annotation] of input.annotations.entries()) {
+                validateAnnotation(annotation, index, issues, imageBudget);
+            }
+            validateDuplicateAnnotationIds(input.annotations, issues);
+        }
+    }
+    if (Object.hasOwn(input, "nodeEmptyStates")) {
+        if (!Array.isArray(input.nodeEmptyStates)) {
+            issues.push({
+                category: "structure",
+                code: "invalid_type",
+                path: ["nodeEmptyStates"],
+                message: "Expected nodeEmptyStates to be an array.",
+            });
+        }
+        else {
+            for (const [index, emptyState] of input.nodeEmptyStates.entries()) {
+                validateNodeEmptyState(emptyState, index, issues, imageBudget, canonicalNodeIds);
+            }
+            validateDuplicateNodeIds(input.nodeEmptyStates, issues);
+        }
+    }
+    return issues.length > 0
+        ? { success: false, issues }
+        : {
+            success: true,
+            data: clonePlainData(input),
+        };
+}
+export function parseFactoryVisualizationLayout(input, factory) {
+    const result = safeParseFactoryVisualizationLayout(input, factory);
+    if (!result.success) {
+        throw new FactoryVisualizationLayoutValidationError(result.issues);
+    }
+    return result.data;
+}

package/examples/customer-support.factory-recording.v1.json

@@ -0,0 +1,64 @@
+{
+  "schemaVersion": "factory-recording/v1",
+  "id": "customer-support-triage-example",
+  "title": "Customer support triage topology",
+  "summary": "A minimal recording that establishes the Factory topology before work begins.",
+  "factory": {
+    "name": "customer-support-triage",
+    "workTypes": [
+      {
+        "name": "support-request",
+        "states": [
+          { "name": "queued", "type": "INITIAL" },
+          { "name": "resolved", "type": "TERMINAL" }
+        ]
+      }
+    ],
+    "workstations": [
+      {
+        "name": "triage",
+        "worker": "",
+        "inputs": [{ "workType": "support-request", "state": "queued" }],
+        "outputs": [{ "workType": "support-request", "state": "resolved" }]
+      }
+    ]
+  },
+  "events": [
+    {
+      "schemaVersion": "agent-factory.event.v1",
+      "id": "evt-topology-001",
+      "type": "INITIAL_STRUCTURE_REQUEST",
+      "context": {
+        "sequence": 1,
+        "tick": 0,
+        "eventTime": "2026-07-18T00:00:00Z",
+        "sessionId": "session-customer-support-example",
+        "sessionSequence": 1
+      },
+      "payload": {
+        "factory": {
+          "name": "customer-support-triage",
+          "workTypes": [
+            {
+              "name": "support-request",
+              "states": [
+                { "name": "queued", "type": "INITIAL" },
+                { "name": "resolved", "type": "TERMINAL" }
+              ]
+            }
+          ],
+          "workstations": [
+            {
+              "name": "triage",
+              "worker": "",
+              "inputs": [{ "workType": "support-request", "state": "queued" }],
+              "outputs": [
+                { "workType": "support-request", "state": "resolved" }
+              ]
+            }
+          ]
+        }
+      }
+    }
+  ]
+}

package/examples/customer-support.factory-visualization-layout.v1.json

@@ -0,0 +1,47 @@
+{
+  "schemaVersion": "factory-visualization-layout/v1",
+  "annotations": [
+    {
+      "id": "triage-guidance",
+      "kind": "note",
+      "position": { "x": 120, "y": 80 },
+      "size": { "width": 320, "height": 180 },
+      "title": "Triage guidance",
+      "body": "Review urgency before assigning a specialist.",
+      "tone": "info"
+    },
+    {
+      "id": "support-mark",
+      "kind": "image",
+      "position": { "x": 520, "y": 80 },
+      "size": { "width": 64, "height": 64 },
+      "altText": "Customer support marker",
+      "source": {
+        "kind": "embedded",
+        "mediaType": "image/png",
+        "base64": "iVBORw0KGgo="
+      }
+    }
+  ],
+  "nodeEmptyStates": [
+    {
+      "nodeId": "workstation:triage",
+      "content": {
+        "kind": "text",
+        "text": "No support requests are waiting."
+      }
+    },
+    {
+      "nodeId": "work-state:support-request:resolved",
+      "content": {
+        "kind": "image",
+        "altText": "Resolved queue is empty",
+        "source": {
+          "kind": "embedded",
+          "mediaType": "image/png",
+          "base64": "iVBORw0KGgo="
+        }
+      }
+    }
+  ]
+}

package/package.json

@@ -1,32 +1,51 @@
 {
   "name": "@you-agent-factory/client",
-  "version": "0.0.0",
-  "description": "Framework-neutral Factory contracts and recording validation for you-agent-factory consumers.",
+  "version": "0.0.1",
+  "description": "Transport-neutral Factory contracts and recording utilities.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/portpowered/you-agent-factory.git"
+    "url": "git+https://github.com/portpowered/you-agent-factory.git",
+    "directory": "ui/packages/client"
+  },
+  "publishConfig": {
+    "access": "public"
   },
-  "type": "module",
   "files": [
-    "README.md",
+    "dist",
+    "examples",
     "LICENSE.md",
-    "recordings",
-    "src"
+    "README.md"
   ],
-  "types": "./src/index.ts",
-  "dependencies": {
-    "ajv": "^8.20.0",
-    "ajv-formats": "^3.0.1"
-  },
+  "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.js"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
-    "./generated/openapi": {
-      "types": "./src/generated/openapi.ts"
-    },
-    "./recordings/example": "./recordings/factory-recording.json"
+    "./examples/customer-support.factory-recording.v1.json": "./examples/customer-support.factory-recording.v1.json",
+    "./examples/customer-support.factory-visualization-layout.v1.json": "./examples/customer-support.factory-visualization-layout.v1.json"
+  },
+  "scripts": {
+    "build": "node scripts/build-package.mjs",
+    "check:installed-consumer": "node scripts/verify-installed-consumer.mjs",
+    "check:pack": "node scripts/verify-package-pack.mjs",
+    "check:generated": "node scripts/generate-contracts.mjs --check",
+    "generate": "node scripts/generate-contracts.mjs",
+    "prepack": "bun run build",
+    "test": "vitest run --config vitest.config.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit --pretty false",
+    "verify": "bun run check:generated && bun run typecheck && bun run test && bun run build && bun run check:pack && bun run check:installed-consumer"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "marked": "^14.0.0"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3",
+    "vitest": "4.1.3"
   }
 }

package/recordings/factory-recording.json

@@ -1,36 +0,0 @@
-{
-  "schemaVersion": "agent-factory.recording.v1",
-  "sessionId": "example-session",
-  "events": [
-    {
-      "schemaVersion": "agent-factory.event.v1",
-      "id": "example-event-1",
-      "type": "INITIAL_STRUCTURE_REQUEST",
-      "context": {
-        "sequence": 0,
-        "tick": 0,
-        "eventTime": "2026-07-18T00:00:00Z",
-        "sessionId": "example-session"
-      },
-      "payload": {
-        "factory": {
-          "name": "packaged-recording-example"
-        }
-      }
-    },
-    {
-      "schemaVersion": "agent-factory.event.v1",
-      "id": "example-event-2",
-      "type": "SESSION_STARTED",
-      "context": {
-        "sequence": 1,
-        "tick": 1,
-        "eventTime": "2026-07-18T00:00:01Z",
-        "sessionId": "example-session"
-      },
-      "payload": {
-        "startedAt": "2026-07-18T00:00:01Z"
-      }
-    }
-  ]
-}

package/src/contracts.ts

@@ -1,13 +0,0 @@
-import type { components } from "./generated/openapi.js";
-
-/** A canonical event emitted by the Factory runtime. */
-export type FactoryEvent = components["schemas"]["FactoryEvent"];
-
-/** The customer-visible canonical Factory event vocabulary. */
-export type FactoryEventType = components["schemas"]["FactoryEventType"];
-
-/** A complete authored Factory definition. */
-export type FactoryDefinition = components["schemas"]["Factory"];
-
-/** A chapter-free, ordered event recording for one Factory Session. */
-export type FactoryRecording = components["schemas"]["FactoryRecording"];