Add stateful block editor mutation steps (#1859)

* Add stateful editor mutations (#1855)

* Verify editor mutation postconditions

* Classify rejected editor inserts

Author: chubes4

packages/runtime-core/src/command-registry.ts

@@ -1282,14 +1282,14 @@ export const commandRegistry = [
       { name: "post-id", description: "Existing post ID to open in the post editor.", format: "positive integer" },
       { name: "post-type", description: "Post type for post-new or post-id targets; defaults to post.", format: "post type slug" },
       { name: "url", description: "Explicit editor path or absolute URL to open instead of resolving a target.", format: "path or URL" },
-      { name: "steps-json", description: "Ordered editor action script: open, waitForReady, insertBlock, selectBlock, savePost, and inspectState. savePost uses Gutenberg core/editor.savePost and reports typed editorSave diagnostics.", required: true, format: "JSON array (inline or @<path>)" },
+      { name: "steps-json", description: "Ordered typed editor action script. Block targets resolve by exactly one clientId, root index, or numeric path. Supports insert/select, attribute update, remove/move/duplicate/replace, inner-block replacement, undo/redo, reload/reopen, save, and inspect. Clipboard actions are explicitly unsupported because this runtime has no deterministic clipboard contract.", required: true, format: "JSON array (inline or @<path>)" },
       { name: "wait-selector", description: "Selector that marks the editor as ready; defaults to the block editor shell.", format: "CSS selector" },
       { name: "wait-timeout", description: "Timeout for navigation and editor-ready waits.", format: "duration, e.g. 15s or 500ms" },
       { name: "step-timeout", description: "Per-action timeout applied to each editor action step.", format: "duration, e.g. 15s or 500ms" },
       { name: "timeout", description: "Total-script timeout bounding the whole editor action run.", format: "duration, e.g. 30s or 1500ms" },
       { name: "capture", description: "Comma-separated artifacts to capture after actions.", format: "steps,console,errors,html,screenshot,editor-state,editor-validity" },
     ],
-    outputShape: "JSON summary plus files/browser/editor-action-steps.jsonl, editor-action-summary.json, editor-action-state.json, optional editor-action-validity.json, and optional console/errors/html/screenshot artifacts.",
+    outputShape: "JSON summary plus per-step before/after mutation summaries, files/browser/editor-action-steps.jsonl, editor-action-summary.json, editor-action-state.json (typed block tree, attributes, validity, serialized/saved content identities, dirty/saving state), editor-action-validity.json, and optional console/errors/html/screenshot artifacts.",
     policyRequirement: "Runtime policy commands must include wordpress.editor-actions.",
     validation: editorActionsValidation,
     recipe: true,

packages/runtime-playground/src/browser-artifacts.ts

@@ -137,6 +137,7 @@ export interface BrowserArtifactSummary {
   editorReadiness?: BrowserEditorReadinessSummary
   editorSave?: BrowserEditorSaveSummary
   editorCanvas?: BrowserEditorCanvasProbeSummary
+  editorCapabilities?: { clipboard: "unsupported" }
   steps?: number
   assertions?: BrowserAssertionsSummary
   consoleMessages: number
@@ -805,6 +806,22 @@ export interface BrowserStepRecord {
   verifierResult?: string
   finalUrl?: string
   error?: BrowserProbeErrorRecord
+  editorMutation?: BrowserEditorMutationSummary
+}
+
+export interface BrowserEditorMutationSummary {
+  status: "applied" | "no-op" | "failed"
+  before: BrowserEditorStateSummary
+  after?: BrowserEditorStateSummary
+  failure?: string
+}
+
+export interface BrowserEditorStateSummary {
+  blockCount?: number
+  contentSha256?: string
+  dirty?: boolean
+  saving?: boolean
+  savedContentSha256?: string
 }
 
 export interface BrowserStepScreenshotFallback {

packages/runtime-playground/src/browser-interactions.ts

@@ -2,7 +2,7 @@ import type { BrowserInteractionStep } from "@automattic/wp-codebox-core"
 import { now } from "@automattic/wp-codebox-core/internals"
 import type { Frame, Page } from "playwright"
 import { browserActionLoadState, browserDeepEqual, browserStepTimeoutMs, durationStringMs, sanitizeScreenshotName } from "./browser-actions.js"
-import type { BrowserProbeErrorRecord, BrowserStepAssertion, BrowserStepReadiness, BrowserStepRecord } from "./browser-artifacts.js"
+import type { BrowserEditorMutationSummary, BrowserProbeErrorRecord, BrowserStepAssertion, BrowserStepReadiness, BrowserStepRecord } from "./browser-artifacts.js"
 import { browserCommandLivenessPolicy, withBrowserCommandLiveness } from "./browser-liveness.js"
 
 export interface BrowserStepOutcome {
@@ -14,6 +14,7 @@ export interface BrowserStepOutcome {
   screenshotFallback?: { reason: string; mode: "page-screenshot" }
   verifierResult?: string
   error?: BrowserProbeErrorRecord
+  editorMutation?: BrowserEditorMutationSummary
 }
 
 export interface BrowserStepScreenshotWriterResult {
@@ -386,6 +387,7 @@ export function browserStepRecord(
     ...(outcome.verifierResult ? { verifierResult: outcome.verifierResult } : {}),
     finalUrl,
     ...(outcome.error ? { error: outcome.error } : {}),
+    ...(outcome.editorMutation ? { editorMutation: outcome.editorMutation } : {}),
   }
 }
 

packages/runtime-playground/src/editor-actions.ts

@@ -29,10 +29,32 @@ export type EditorActionStep =
   | { kind: "open"; timeout?: string }
   | { kind: "waitForReady"; timeout?: string }
   | { kind: "insertBlock"; name?: string; attributes?: Record<string, unknown>; content?: string; select?: boolean; timeout?: string }
-  | { kind: "selectBlock"; clientId?: string; index?: number; timeout?: string }
+  | ({ kind: "selectBlock"; timeout?: string } & EditorBlockTarget)
+  | ({ kind: "updateBlockAttributes"; attributes: Record<string, unknown>; timeout?: string } & EditorBlockTarget)
+  | ({ kind: "removeBlock"; timeout?: string } & EditorBlockTarget)
+  | ({ kind: "moveBlock"; position: number; timeout?: string } & EditorBlockTarget)
+  | ({ kind: "duplicateBlock"; timeout?: string } & EditorBlockTarget)
+  | ({ kind: "replaceBlock"; block: EditorBlockSpec; timeout?: string } & EditorBlockTarget)
+  | ({ kind: "replaceInnerBlocks"; blocks: EditorBlockSpec[]; timeout?: string } & EditorBlockTarget)
+  | { kind: "undo"; timeout?: string }
+  | { kind: "redo"; timeout?: string }
+  | { kind: "reload"; timeout?: string }
+  | { kind: "reopen"; timeout?: string }
   | { kind: "savePost"; marker?: string; content?: string; timeout?: string }
   | { kind: "inspectState"; timeout?: string }
 
+export interface EditorBlockTarget {
+  clientId?: string
+  index?: number
+  path?: number[]
+}
+
+export interface EditorBlockSpec {
+  name: string
+  attributes?: Record<string, unknown>
+  innerBlocks?: EditorBlockSpec[]
+}
+
 export function editorOpenTargetFromArgs(args: string[]): EditorOpenTarget {
   const explicitUrl = argValue(args, "url")?.trim()
   const waitSelector = argValue(args, "wait-selector")?.trim() || undefined
@@ -228,18 +250,31 @@ function normalizeEditorActionStep(step: unknown, index: number): EditorActionSt
     return { kind: "waitForReady", ...(typeof input.timeout === "string" ? { timeout: input.timeout } : {}) }
   }
   if (input.kind === "selectBlock") {
-    if (input.clientId !== undefined && typeof input.clientId !== "string") {
-      throw new Error(`wordpress.editor-actions steps-json[${index}].clientId must be a string`)
-    }
-    if (input.index !== undefined && (typeof input.index !== "number" || !Number.isInteger(input.index) || input.index < 0)) {
-      throw new Error(`wordpress.editor-actions steps-json[${index}].index must be a non-negative integer`)
+    return { kind: "selectBlock", ...normalizeEditorBlockTarget(input, index), ...editorActionTimeout(input) }
+  }
+  if (input.kind === "updateBlockAttributes") {
+    return { kind: "updateBlockAttributes", ...normalizeEditorBlockTarget(input, index), attributes: normalizeAttributes(input.attributes, index), ...editorActionTimeout(input) }
+  }
+  if (input.kind === "removeBlock" || input.kind === "duplicateBlock") {
+    return { kind: input.kind, ...normalizeEditorBlockTarget(input, index), ...editorActionTimeout(input) }
+  }
+  if (input.kind === "moveBlock") {
+    if (typeof input.position !== "number" || !Number.isInteger(input.position) || input.position < 0) {
+      throw new Error(`wordpress.editor-actions steps-json[${index}].position must be a non-negative integer`)
     }
-    return {
-      kind: "selectBlock",
-      ...(typeof input.clientId === "string" ? { clientId: input.clientId } : {}),
-      ...(Number.isInteger(input.index) && (input.index as number) >= 0 ? { index: input.index as number } : {}),
-      ...(typeof input.timeout === "string" ? { timeout: input.timeout } : {}),
+    return { kind: "moveBlock", ...normalizeEditorBlockTarget(input, index), position: input.position, ...editorActionTimeout(input) }
+  }
+  if (input.kind === "replaceBlock") {
+    return { kind: "replaceBlock", ...normalizeEditorBlockTarget(input, index), block: normalizeEditorBlockSpec(input.block, index, "block"), ...editorActionTimeout(input) }
+  }
+  if (input.kind === "replaceInnerBlocks") {
+    if (!Array.isArray(input.blocks)) {
+      throw new Error(`wordpress.editor-actions steps-json[${index}].blocks must be a JSON array`)
     }
+    return { kind: "replaceInnerBlocks", ...normalizeEditorBlockTarget(input, index), blocks: input.blocks.map((block, blockIndex) => normalizeEditorBlockSpec(block, index, `blocks[${blockIndex}]`)), ...editorActionTimeout(input) }
+  }
+  if (input.kind === "undo" || input.kind === "redo" || input.kind === "reload" || input.kind === "reopen") {
+    return { kind: input.kind, ...editorActionTimeout(input) }
   }
   if (input.kind === "savePost") {
     if (input.marker !== undefined && typeof input.marker !== "string") {
@@ -261,3 +296,38 @@ function normalizeEditorActionStep(step: unknown, index: number): EditorActionSt
 
   throw new Error(`wordpress.editor-actions step kind is not supported: ${String(input.kind)}`)
 }
+
+function normalizeEditorBlockTarget(input: Record<string, unknown>, index: number): EditorBlockTarget {
+  const targetCount = Number(typeof input.clientId === "string") + Number(input.index !== undefined) + Number(input.path !== undefined)
+  if (targetCount !== 1) {
+    throw new Error(`wordpress.editor-actions steps-json[${index}] requires exactly one target: clientId, index, or path`)
+  }
+  if (typeof input.clientId === "string" && input.clientId.length > 0) return { clientId: input.clientId }
+  if (typeof input.index === "number" && Number.isInteger(input.index) && input.index >= 0) return { index: input.index }
+  if (Array.isArray(input.path) && input.path.length > 0 && input.path.every((part) => typeof part === "number" && Number.isInteger(part) && part >= 0)) return { path: input.path as number[] }
+  throw new Error(`wordpress.editor-actions steps-json[${index}] target must be a non-empty clientId, non-negative index, or non-empty path of non-negative indexes`)
+}
+
+function normalizeAttributes(value: unknown, index: number): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`wordpress.editor-actions steps-json[${index}].attributes must be a JSON object`)
+  }
+  return value as Record<string, unknown>
+}
+
+function normalizeEditorBlockSpec(value: unknown, index: number, field: string): EditorBlockSpec {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`wordpress.editor-actions steps-json[${index}].${field} must be an object`)
+  const input = value as Record<string, unknown>
+  if (typeof input.name !== "string" || input.name.length === 0) throw new Error(`wordpress.editor-actions steps-json[${index}].${field}.name must be a block name string`)
+  if (input.attributes !== undefined) normalizeAttributes(input.attributes, index)
+  if (input.innerBlocks !== undefined && !Array.isArray(input.innerBlocks)) throw new Error(`wordpress.editor-actions steps-json[${index}].${field}.innerBlocks must be a JSON array`)
+  return {
+    name: input.name,
+    ...(input.attributes !== undefined ? { attributes: input.attributes as Record<string, unknown> } : {}),
+    ...(Array.isArray(input.innerBlocks) ? { innerBlocks: input.innerBlocks.map((block, childIndex) => normalizeEditorBlockSpec(block, index, `${field}.innerBlocks[${childIndex}]`)) } : {}),
+  }
+}
+
+function editorActionTimeout(input: Record<string, unknown>): { timeout?: string } {
+  return typeof input.timeout === "string" ? { timeout: input.timeout } : {}
+}