mewkit 1.14.1 → 1.16.0

package/dist/visual-plan/domain/errors.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Validation error vocabulary for the visual-plan contracts.
+ *
+ * Every deterministic check emits a `ValidationError` carrying an exact JSON
+ * path into the artifact, a stable machine code, and a human message. The
+ * `--json` reporter surfaces these verbatim so a fresh agent session can
+ * self-repair a rejected artifact from the path alone.
+ */
+/** Stable, machine-readable error codes. Never renumber — consumers match on these. */
+export declare const ErrorCode: {
+    readonly ARTIFACT_MISSING: "ARTIFACT_MISSING";
+    readonly ARTIFACT_INVALID_JSON: "ARTIFACT_INVALID_JSON";
+    readonly SCHEMA: "SCHEMA";
+    readonly DUPLICATE_ID: "DUPLICATE_ID";
+    readonly DANGLING_CONNECTOR_ENDPOINT: "DANGLING_CONNECTOR_ENDPOINT";
+    readonly DANGLING_ANNOTATION_TARGET: "DANGLING_ANNOTATION_TARGET";
+    readonly DANGLING_LANE: "DANGLING_LANE";
+    readonly DANGLING_COVERAGE_FRAME: "DANGLING_COVERAGE_FRAME";
+    readonly DANGLING_SOURCE_REF: "DANGLING_SOURCE_REF";
+    readonly DANGLING_REPRESENTED_BY: "DANGLING_REPRESENTED_BY";
+    readonly COVERAGE_UNRESOLVED: "COVERAGE_UNRESOLVED";
+    readonly COVERAGE_EQUIVALENCE_CYCLE: "COVERAGE_EQUIVALENCE_CYCLE";
+    readonly COVERAGE_EQUIVALENCE_UNBACKED: "COVERAGE_EQUIVALENCE_UNBACKED";
+    readonly COVERAGE_MISSING_RISK_ID: "COVERAGE_MISSING_RISK_ID";
+    readonly COVERAGE_MISSING_REPRESENTED_BY: "COVERAGE_MISSING_REPRESENTED_BY";
+    readonly UNSAFE_HTML: "UNSAFE_HTML";
+    readonly STALE_SOURCE_HASH: "STALE_SOURCE_HASH";
+};
+export type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
+/** One deterministic finding. `path` is a dotted/bracketed JSON path into the artifact. */
+export interface ValidationError {
+    path: string;
+    code: ErrorCodeValue;
+    message: string;
+}
+/** Machine-readable result of any validation pass. `ok` is derived from `errors`. */
+export interface ValidationResult {
+    ok: boolean;
+    errors: ValidationError[];
+}
+/** Build a `ValidationError` (thin helper to keep call sites terse and consistent). */
+export declare function err(path: string, code: ErrorCodeValue, message: string): ValidationError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/visual-plan/domain/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/visual-plan/domain/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,uFAAuF;AACvF,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;CAkBZ,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAExE,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,eAAe,EAAE,CAAC;CAC1B;AAED,uFAAuF;AACvF,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe,CAExF"}

package/dist/visual-plan/domain/errors.js

@@ -0,0 +1,33 @@
+/**
+ * Validation error vocabulary for the visual-plan contracts.
+ *
+ * Every deterministic check emits a `ValidationError` carrying an exact JSON
+ * path into the artifact, a stable machine code, and a human message. The
+ * `--json` reporter surfaces these verbatim so a fresh agent session can
+ * self-repair a rejected artifact from the path alone.
+ */
+/** Stable, machine-readable error codes. Never renumber — consumers match on these. */
+export const ErrorCode = {
+    ARTIFACT_MISSING: "ARTIFACT_MISSING",
+    ARTIFACT_INVALID_JSON: "ARTIFACT_INVALID_JSON",
+    SCHEMA: "SCHEMA",
+    DUPLICATE_ID: "DUPLICATE_ID",
+    DANGLING_CONNECTOR_ENDPOINT: "DANGLING_CONNECTOR_ENDPOINT",
+    DANGLING_ANNOTATION_TARGET: "DANGLING_ANNOTATION_TARGET",
+    DANGLING_LANE: "DANGLING_LANE",
+    DANGLING_COVERAGE_FRAME: "DANGLING_COVERAGE_FRAME",
+    DANGLING_SOURCE_REF: "DANGLING_SOURCE_REF",
+    DANGLING_REPRESENTED_BY: "DANGLING_REPRESENTED_BY",
+    COVERAGE_UNRESOLVED: "COVERAGE_UNRESOLVED",
+    COVERAGE_EQUIVALENCE_CYCLE: "COVERAGE_EQUIVALENCE_CYCLE",
+    COVERAGE_EQUIVALENCE_UNBACKED: "COVERAGE_EQUIVALENCE_UNBACKED",
+    COVERAGE_MISSING_RISK_ID: "COVERAGE_MISSING_RISK_ID",
+    COVERAGE_MISSING_REPRESENTED_BY: "COVERAGE_MISSING_REPRESENTED_BY",
+    UNSAFE_HTML: "UNSAFE_HTML",
+    STALE_SOURCE_HASH: "STALE_SOURCE_HASH",
+};
+/** Build a `ValidationError` (thin helper to keep call sites terse and consistent). */
+export function err(path, code, message) {
+    return { path, code, message };
+}
+//# sourceMappingURL=errors.js.map

package/dist/visual-plan/domain/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/visual-plan/domain/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,uFAAuF;AACvF,MAAM,CAAC,MAAM,SAAS,GAAG;IACxB,gBAAgB,EAAE,kBAAkB;IACpC,qBAAqB,EAAE,uBAAuB;IAC9C,MAAM,EAAE,QAAQ;IAChB,YAAY,EAAE,cAAc;IAC5B,2BAA2B,EAAE,6BAA6B;IAC1D,0BAA0B,EAAE,4BAA4B;IACxD,aAAa,EAAE,eAAe;IAC9B,uBAAuB,EAAE,yBAAyB;IAClD,mBAAmB,EAAE,qBAAqB;IAC1C,uBAAuB,EAAE,yBAAyB;IAClD,mBAAmB,EAAE,qBAAqB;IAC1C,0BAA0B,EAAE,4BAA4B;IACxD,6BAA6B,EAAE,+BAA+B;IAC9D,wBAAwB,EAAE,0BAA0B;IACpD,+BAA+B,EAAE,iCAAiC;IAClE,WAAW,EAAE,aAAa;IAC1B,iBAAiB,EAAE,mBAAmB;CAC7B,CAAC;AAiBX,uFAAuF;AACvF,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,IAAoB,EAAE,OAAe;IACtE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAChC,CAAC"}

package/dist/visual-plan/domain/feedback-schemas.d.ts

@@ -0,0 +1,160 @@
+/**
+ * `visual-feedback/v1` immutable batch schema + resolution-receipt schema.
+ *
+ * A feedback batch is written once and never mutated (red-team: immutability is
+ * the misapplication guard). It captures the reviewer's intent against an exact
+ * `baseRevision` + `baseHash`; the apply loop (Phase 6) refuses to apply a batch
+ * whose base no longer matches the artifact. The batch `id` is charset-locked so
+ * a consumer can validate it BEFORE any path join.
+ *
+ * The resolution receipt mirrors the batch, recording a per-operation outcome
+ * (`applied | rejected | unresolved`). Batches remain byte-immutable after
+ * resolution; the receipt is the mutable-outcome surface.
+ *
+ * `markup` operation points are position-absolute / unanchored (red-team L3):
+ * they do NOT track frames across layout regeneration — documented, not a bug.
+ */
+import { z } from "zod";
+export declare const FEEDBACK_OP_TYPES: readonly ["annotation", "copy-change", "field-change", "flow-change", "scope-change", "other"];
+export declare const FeedbackBatchSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"visual-feedback/v1">;
+    id: z.ZodString;
+    planId: z.ZodString;
+    baseRevision: z.ZodNumber;
+    baseHash: z.ZodString;
+    createdAt: z.ZodString;
+    operations: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<["annotation", "copy-change", "field-change", "flow-change", "scope-change", "other"]>;
+        frameId: z.ZodOptional<z.ZodString>;
+        elementId: z.ZodOptional<z.ZodString>;
+        sourceRefId: z.ZodOptional<z.ZodString>;
+        visualPoint: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            y: number;
+            x: number;
+        }, {
+            y: number;
+            x: number;
+        }>>;
+        intent: z.ZodString;
+        comment: z.ZodOptional<z.ZodString>;
+        context: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        type: "annotation" | "other" | "copy-change" | "field-change" | "flow-change" | "scope-change";
+        intent: string;
+        context?: string | undefined;
+        frameId?: string | undefined;
+        elementId?: string | undefined;
+        sourceRefId?: string | undefined;
+        visualPoint?: {
+            y: number;
+            x: number;
+        } | undefined;
+        comment?: string | undefined;
+    }, {
+        type: "annotation" | "other" | "copy-change" | "field-change" | "flow-change" | "scope-change";
+        intent: string;
+        context?: string | undefined;
+        frameId?: string | undefined;
+        elementId?: string | undefined;
+        sourceRefId?: string | undefined;
+        visualPoint?: {
+            y: number;
+            x: number;
+        } | undefined;
+        comment?: string | undefined;
+    }>, "many">;
+    status: z.ZodDefault<z.ZodEnum<["open", "resolved"]>>;
+}, "strict", z.ZodTypeAny, {
+    status: "resolved" | "open";
+    schemaVersion: "visual-feedback/v1";
+    id: string;
+    planId: string;
+    baseRevision: number;
+    baseHash: string;
+    createdAt: string;
+    operations: {
+        type: "annotation" | "other" | "copy-change" | "field-change" | "flow-change" | "scope-change";
+        intent: string;
+        context?: string | undefined;
+        frameId?: string | undefined;
+        elementId?: string | undefined;
+        sourceRefId?: string | undefined;
+        visualPoint?: {
+            y: number;
+            x: number;
+        } | undefined;
+        comment?: string | undefined;
+    }[];
+}, {
+    schemaVersion: "visual-feedback/v1";
+    id: string;
+    planId: string;
+    baseRevision: number;
+    baseHash: string;
+    createdAt: string;
+    operations: {
+        type: "annotation" | "other" | "copy-change" | "field-change" | "flow-change" | "scope-change";
+        intent: string;
+        context?: string | undefined;
+        frameId?: string | undefined;
+        elementId?: string | undefined;
+        sourceRefId?: string | undefined;
+        visualPoint?: {
+            y: number;
+            x: number;
+        } | undefined;
+        comment?: string | undefined;
+    }[];
+    status?: "resolved" | "open" | undefined;
+}>;
+export type FeedbackBatch = z.infer<typeof FeedbackBatchSchema>;
+export declare const ResolutionReceiptSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"visual-feedback-receipt/v1">;
+    batchId: z.ZodString;
+    planId: z.ZodString;
+    baseRevision: z.ZodNumber;
+    resolvedAtRevision: z.ZodNumber;
+    resolvedAt: z.ZodString;
+    entries: z.ZodArray<z.ZodObject<{
+        index: z.ZodNumber;
+        outcome: z.ZodEnum<["applied", "rejected", "unresolved"]>;
+        notes: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        index: number;
+        outcome: "rejected" | "applied" | "unresolved";
+        notes?: string | undefined;
+    }, {
+        index: number;
+        outcome: "rejected" | "applied" | "unresolved";
+        notes?: string | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    entries: {
+        index: number;
+        outcome: "rejected" | "applied" | "unresolved";
+        notes?: string | undefined;
+    }[];
+    schemaVersion: "visual-feedback-receipt/v1";
+    planId: string;
+    baseRevision: number;
+    batchId: string;
+    resolvedAtRevision: number;
+    resolvedAt: string;
+}, {
+    entries: {
+        index: number;
+        outcome: "rejected" | "applied" | "unresolved";
+        notes?: string | undefined;
+    }[];
+    schemaVersion: "visual-feedback-receipt/v1";
+    planId: string;
+    baseRevision: number;
+    batchId: string;
+    resolvedAtRevision: number;
+    resolvedAt: string;
+}>;
+export type ResolutionReceipt = z.infer<typeof ResolutionReceiptSchema>;
+//# sourceMappingURL=feedback-schemas.d.ts.map

package/dist/visual-plan/domain/feedback-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feedback-schemas.d.ts","sourceRoot":"","sources":["../../../src/visual-plan/domain/feedback-schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,iBAAiB,gGAOpB,CAAC;AAeX,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWtB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAUhE,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAU1B,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/visual-plan/domain/feedback-schemas.js

@@ -0,0 +1,71 @@
+/**
+ * `visual-feedback/v1` immutable batch schema + resolution-receipt schema.
+ *
+ * A feedback batch is written once and never mutated (red-team: immutability is
+ * the misapplication guard). It captures the reviewer's intent against an exact
+ * `baseRevision` + `baseHash`; the apply loop (Phase 6) refuses to apply a batch
+ * whose base no longer matches the artifact. The batch `id` is charset-locked so
+ * a consumer can validate it BEFORE any path join.
+ *
+ * The resolution receipt mirrors the batch, recording a per-operation outcome
+ * (`applied | rejected | unresolved`). Batches remain byte-immutable after
+ * resolution; the receipt is the mutable-outcome surface.
+ *
+ * `markup` operation points are position-absolute / unanchored (red-team L3):
+ * they do NOT track frames across layout regeneration — documented, not a bug.
+ */
+import { z } from "zod";
+import { ENTITY_ID_RE, FEEDBACK_BATCH_ID_RE } from "./ids.js";
+const EntityId = z.string().regex(ENTITY_ID_RE);
+const BatchId = z.string().regex(FEEDBACK_BATCH_ID_RE, "invalid feedback batch id (path-injection guard)");
+export const FEEDBACK_OP_TYPES = [
+    "annotation",
+    "copy-change",
+    "field-change",
+    "flow-change",
+    "scope-change",
+    "other",
+];
+const FeedbackOperationSchema = z
+    .object({
+    type: z.enum(FEEDBACK_OP_TYPES),
+    frameId: EntityId.optional(),
+    elementId: z.string().optional(),
+    sourceRefId: EntityId.optional(),
+    visualPoint: z.object({ x: z.number(), y: z.number() }).strict().optional(),
+    intent: z.string().min(1),
+    comment: z.string().optional(),
+    context: z.string().optional(),
+})
+    .strict();
+export const FeedbackBatchSchema = z
+    .object({
+    schemaVersion: z.literal("visual-feedback/v1"),
+    id: BatchId,
+    planId: EntityId,
+    baseRevision: z.number().int().nonnegative(),
+    baseHash: z.string().min(1),
+    createdAt: z.string().min(1),
+    operations: z.array(FeedbackOperationSchema).min(1).max(500),
+    status: z.enum(["open", "resolved"]).default("open"),
+})
+    .strict();
+const ResolutionEntrySchema = z
+    .object({
+    index: z.number().int().nonnegative(),
+    outcome: z.enum(["applied", "rejected", "unresolved"]),
+    notes: z.string().optional(),
+})
+    .strict();
+export const ResolutionReceiptSchema = z
+    .object({
+    schemaVersion: z.literal("visual-feedback-receipt/v1"),
+    batchId: BatchId,
+    planId: EntityId,
+    baseRevision: z.number().int().nonnegative(),
+    resolvedAtRevision: z.number().int().nonnegative(),
+    resolvedAt: z.string().min(1),
+    entries: z.array(ResolutionEntrySchema),
+})
+    .strict();
+//# sourceMappingURL=feedback-schemas.js.map

package/dist/visual-plan/domain/feedback-schemas.js.map

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

package/dist/visual-plan/domain/ids.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared identifier patterns for the visual-plan contracts.
+ *
+ * Feedback batch ids are the security-sensitive one: a consumer validates the
+ * id against `FEEDBACK_BATCH_ID_RE` BEFORE any path join (red-team M8), so the
+ * charset is deliberately narrow — no dots, slashes, or path separators can
+ * appear in a batch filename.
+ */
+/** Generic artifact-internal id: lowercase/uppercase alnum + hyphen/underscore. */
+export declare const ENTITY_ID_RE: RegExp;
+/**
+ * Strict feedback-batch id: `feedback-<digits>-<slug>`. The fixed charset makes
+ * the id safe to interpolate into a filename without traversal risk. Validated
+ * before any path join.
+ */
+export declare const FEEDBACK_BATCH_ID_RE: RegExp;
+/** True when `id` is a structurally valid artifact-internal id. */
+export declare function isValidEntityId(id: string): boolean;
+/** True when `id` is a structurally valid feedback-batch id (path-injection safe). */
+export declare function isValidFeedbackBatchId(id: string): boolean;
+//# sourceMappingURL=ids.d.ts.map

package/dist/visual-plan/domain/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../../src/visual-plan/domain/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,mFAAmF;AACnF,eAAO,MAAM,YAAY,QAAsC,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAAgD,CAAC;AAElF,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,sFAAsF;AACtF,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE1D"}

package/dist/visual-plan/domain/ids.js

@@ -0,0 +1,25 @@
+/**
+ * Shared identifier patterns for the visual-plan contracts.
+ *
+ * Feedback batch ids are the security-sensitive one: a consumer validates the
+ * id against `FEEDBACK_BATCH_ID_RE` BEFORE any path join (red-team M8), so the
+ * charset is deliberately narrow — no dots, slashes, or path separators can
+ * appear in a batch filename.
+ */
+/** Generic artifact-internal id: lowercase/uppercase alnum + hyphen/underscore. */
+export const ENTITY_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+/**
+ * Strict feedback-batch id: `feedback-<digits>-<slug>`. The fixed charset makes
+ * the id safe to interpolate into a filename without traversal risk. Validated
+ * before any path join.
+ */
+export const FEEDBACK_BATCH_ID_RE = /^feedback-\d{8,}-[a-z0-9]([a-z0-9-]{0,63})$/;
+/** True when `id` is a structurally valid artifact-internal id. */
+export function isValidEntityId(id) {
+    return ENTITY_ID_RE.test(id);
+}
+/** True when `id` is a structurally valid feedback-batch id (path-injection safe). */
+export function isValidFeedbackBatchId(id) {
+    return FEEDBACK_BATCH_ID_RE.test(id);
+}
+//# sourceMappingURL=ids.js.map

package/dist/visual-plan/domain/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../../src/visual-plan/domain/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAG,mCAAmC,CAAC;AAEhE;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,6CAA6C,CAAC;AAElF,mEAAmE;AACnE,MAAM,UAAU,eAAe,CAAC,EAAU;IACzC,OAAO,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,sBAAsB,CAAC,EAAU;IAChD,OAAO,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACtC,CAAC"}

package/dist/visual-plan/domain/patches.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Typed VISUAL-ONLY patch operations (Phase 5).
+ *
+ * These are the only mutations the studio may apply directly to the artifact —
+ * lane/order moves, annotation add/edit/remove, connector-label edits, and
+ * schema-backed wireframe TEXT-field edits. Raw HTML/CSS editing, freeform
+ * resize, and Markdown edits are NOT patch ops (semantic changes go through the
+ * feedback→agent loop). Every accepted patch bumps `revision` and clears
+ * approval; the application layer re-validates the mutated plan before writing.
+ *
+ * A wireframe field is targeted by a `wf-field-<id>` CLASS in the wireframe HTML
+ * (class is in the sanitizer allowlist, so no allowlist change is needed) — only
+ * that element's TEXT content is replaced, then the whole wireframe re-sanitized.
+ */
+import { z } from "zod";
+export declare const PatchOpSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    type: z.ZodLiteral<"move-frame-lane">;
+    frameId: z.ZodString;
+    laneId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "move-frame-lane";
+    laneId: string;
+    frameId: string;
+}, {
+    type: "move-frame-lane";
+    laneId: string;
+    frameId: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"reorder-frame">;
+    frameId: z.ZodString;
+    order: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    type: "reorder-frame";
+    order: number;
+    frameId: string;
+}, {
+    type: "reorder-frame";
+    order: number;
+    frameId: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"update-annotation">;
+    annotationId: z.ZodString;
+    text: z.ZodOptional<z.ZodString>;
+    placement: z.ZodOptional<z.ZodEnum<["top", "right", "bottom", "left"]>>;
+    points: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        y: number;
+        x: number;
+    }, {
+        y: number;
+        x: number;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    type: "update-annotation";
+    annotationId: string;
+    text?: string | undefined;
+    placement?: "top" | "right" | "bottom" | "left" | undefined;
+    points?: {
+        y: number;
+        x: number;
+    }[] | undefined;
+}, {
+    type: "update-annotation";
+    annotationId: string;
+    text?: string | undefined;
+    placement?: "top" | "right" | "bottom" | "left" | undefined;
+    points?: {
+        y: number;
+        x: number;
+    }[] | undefined;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"append-annotation">;
+    annotation: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<["note", "markup"]>;
+        text: z.ZodString;
+        targetId: z.ZodOptional<z.ZodString>;
+        placement: z.ZodOptional<z.ZodEnum<["top", "right", "bottom", "left"]>>;
+        points: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            y: number;
+            x: number;
+        }, {
+            y: number;
+            x: number;
+        }>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        kind: "note" | "markup";
+        text: string;
+        targetId?: string | undefined;
+        placement?: "top" | "right" | "bottom" | "left" | undefined;
+        points?: {
+            y: number;
+            x: number;
+        }[] | undefined;
+    }, {
+        id: string;
+        kind: "note" | "markup";
+        text: string;
+        targetId?: string | undefined;
+        placement?: "top" | "right" | "bottom" | "left" | undefined;
+        points?: {
+            y: number;
+            x: number;
+        }[] | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    type: "append-annotation";
+    annotation: {
+        id: string;
+        kind: "note" | "markup";
+        text: string;
+        targetId?: string | undefined;
+        placement?: "top" | "right" | "bottom" | "left" | undefined;
+        points?: {
+            y: number;
+            x: number;
+        }[] | undefined;
+    };
+}, {
+    type: "append-annotation";
+    annotation: {
+        id: string;
+        kind: "note" | "markup";
+        text: string;
+        targetId?: string | undefined;
+        placement?: "top" | "right" | "bottom" | "left" | undefined;
+        points?: {
+            y: number;
+            x: number;
+        }[] | undefined;
+    };
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"remove-annotation">;
+    annotationId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "remove-annotation";
+    annotationId: string;
+}, {
+    type: "remove-annotation";
+    annotationId: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"update-connector-label">;
+    connectorId: z.ZodString;
+    label: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "update-connector-label";
+    label: string;
+    connectorId: string;
+}, {
+    type: "update-connector-label";
+    label: string;
+    connectorId: string;
+}>, z.ZodObject<{
+    type: z.ZodLiteral<"update-wireframe-field">;
+    frameId: z.ZodString;
+    fieldId: z.ZodString;
+    text: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    type: "update-wireframe-field";
+    text: string;
+    frameId: string;
+    fieldId: string;
+}, {
+    type: "update-wireframe-field";
+    text: string;
+    frameId: string;
+    fieldId: string;
+}>]>;
+export type PatchOp = z.infer<typeof PatchOpSchema>;
+//# sourceMappingURL=patches.d.ts.map

package/dist/visual-plan/domain/patches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patches.d.ts","sourceRoot":"","sources":["../../../src/visual-plan/domain/patches.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoBxB,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAQxB,CAAC;AAEH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/visual-plan/domain/patches.js

@@ -0,0 +1,41 @@
+/**
+ * Typed VISUAL-ONLY patch operations (Phase 5).
+ *
+ * These are the only mutations the studio may apply directly to the artifact —
+ * lane/order moves, annotation add/edit/remove, connector-label edits, and
+ * schema-backed wireframe TEXT-field edits. Raw HTML/CSS editing, freeform
+ * resize, and Markdown edits are NOT patch ops (semantic changes go through the
+ * feedback→agent loop). Every accepted patch bumps `revision` and clears
+ * approval; the application layer re-validates the mutated plan before writing.
+ *
+ * A wireframe field is targeted by a `wf-field-<id>` CLASS in the wireframe HTML
+ * (class is in the sanitizer allowlist, so no allowlist change is needed) — only
+ * that element's TEXT content is replaced, then the whole wireframe re-sanitized.
+ */
+import { z } from "zod";
+import { ENTITY_ID_RE } from "./ids.js";
+import { AnnotationSchema } from "./schemas.js";
+const EntityId = z.string().regex(ENTITY_ID_RE);
+const Placement = z.enum(["top", "right", "bottom", "left"]);
+const Points = z.array(z.object({ x: z.number(), y: z.number() }).strict());
+const MoveFrameLane = z.object({ type: z.literal("move-frame-lane"), frameId: EntityId, laneId: EntityId }).strict();
+const ReorderFrame = z.object({ type: z.literal("reorder-frame"), frameId: EntityId, order: z.number().int() }).strict();
+const UpdateAnnotation = z
+    .object({ type: z.literal("update-annotation"), annotationId: EntityId, text: z.string().min(1).optional(), placement: Placement.optional(), points: Points.optional() })
+    .strict();
+const AppendAnnotation = z.object({ type: z.literal("append-annotation"), annotation: AnnotationSchema }).strict();
+const RemoveAnnotation = z.object({ type: z.literal("remove-annotation"), annotationId: EntityId }).strict();
+const UpdateConnectorLabel = z.object({ type: z.literal("update-connector-label"), connectorId: EntityId, label: z.string() }).strict();
+const UpdateWireframeField = z
+    .object({ type: z.literal("update-wireframe-field"), frameId: EntityId, fieldId: EntityId, text: z.string() })
+    .strict();
+export const PatchOpSchema = z.discriminatedUnion("type", [
+    MoveFrameLane,
+    ReorderFrame,
+    UpdateAnnotation,
+    AppendAnnotation,
+    RemoveAnnotation,
+    UpdateConnectorLabel,
+    UpdateWireframeField,
+]);
+//# sourceMappingURL=patches.js.map

package/dist/visual-plan/domain/patches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patches.js","sourceRoot":"","sources":["../../../src/visual-plan/domain/patches.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,MAAM,QAAQ,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;AAChD,MAAM,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AAC7D,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AAE5E,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AACrH,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AACzH,MAAM,gBAAgB,GAAG,CAAC;KACxB,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,SAAS,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;KACxK,MAAM,EAAE,CAAC;AACX,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AACnH,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AAC7G,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,wBAAwB,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AACxI,MAAM,oBAAoB,GAAG,CAAC;KAC5B,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,wBAAwB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;KAC7G,MAAM,EAAE,CAAC;AAEX,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACzD,aAAa;IACb,YAAY;IACZ,gBAAgB;IAChB,gBAAgB;IAChB,gBAAgB;IAChB,oBAAoB;IACpB,oBAAoB;CACpB,CAAC,CAAC"}