Use semantic Gutenberg readiness for editor-open (#1794)

* Use semantic editor readiness and retain failure artifacts

* Fix semantic editor readiness detection

Author: chubes4

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

@@ -1264,7 +1264,7 @@ 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: "wait-selector", description: "Selector that marks the editor as ready; defaults to the block editor shell.", format: "CSS selector" },
+      { name: "wait-selector", description: "Optional visible selector assertion evaluated after semantic editor readiness.", format: "CSS selector" },
       { name: "wait-timeout", description: "Timeout for navigation and editor-ready waits.", format: "duration, e.g. 15s or 500ms" },
       { name: "capture", description: "Comma-separated artifacts to capture after opening the editor.", format: "steps,console,errors,html,screenshot,editor-state,editor-validity" },
       { name: "artifact-prefix", description: "Optional artifact directory relative to the runtime artifact root for this invocation; defaults to files/browser. Use files/browser/editor-open/<name> to isolate per-fixture editor-open evidence in a batch.", format: "relative artifact directory" },

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

@@ -229,8 +229,9 @@ export interface BrowserEditorValidateBlocksSummary {
 export interface BrowserEditorReadinessSummary {
   schema: "wp-codebox/editor-readiness/v1"
   status: "ready"
-  storesAvailable: true
+  storesAvailable: boolean
   canSave: boolean
+  blockTypesRegistered?: number
   postId?: number
   postType?: string
 }

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

@@ -20,9 +20,11 @@ export interface EditorOpenTarget {
   postId?: number
   postSlug?: string
   postType?: string
-  waitSelector: string
+  waitSelector?: string
 }
 
+export const DEFAULT_EDITOR_WAIT_SELECTOR = ".edit-post-visual-editor, .editor-styles-wrapper, .block-editor, .interface-interface-skeleton"
+
 export type EditorActionStep =
   | { kind: "open"; timeout?: string }
   | { kind: "waitForReady"; timeout?: string }
@@ -31,11 +33,9 @@ export type EditorActionStep =
   | { kind: "savePost"; marker?: string; content?: string; timeout?: string }
   | { kind: "inspectState"; timeout?: string }
 
-const DEFAULT_EDITOR_WAIT_SELECTOR = ".edit-post-visual-editor, .editor-styles-wrapper, .block-editor, .interface-interface-skeleton"
-
 export function editorOpenTargetFromArgs(args: string[]): EditorOpenTarget {
   const explicitUrl = argValue(args, "url")?.trim()
-  const waitSelector = argValue(args, "wait-selector")?.trim() || DEFAULT_EDITOR_WAIT_SELECTOR
+  const waitSelector = argValue(args, "wait-selector")?.trim() || undefined
   if (explicitUrl) {
     return { url: explicitUrl, kind: "url", waitSelector }
   }

packages/runtime-playground/src/editor-command-runners.ts

@@ -9,7 +9,7 @@ import { browserStepRecord } from "./browser-interactions.js"
 import { browserPreviewNetworkPolicyIsActive, browserPreviewNetworkPolicySummary, browserPreviewNeedsContextRouting, browserPreviewOrigins, browserPreviewReadinessError, browserPreviewRouting, browserPreviewSecureContextError, browserPreviewTopology, resolveBrowserPreviewUrl, routeBrowserPreviewContextNetwork } from "./browser-preview-routing.js"
 import { browserProbeReplayability, browserProbeViewport } from "./browser-probe.js"
 import { argValue, commaListArg, durationArg, jsonArrayArg } from "./commands.js"
-import { editorActionStepsFromArgs, editorOpenTargetFromArgs, editorValidateContentFromArgs, editorValidateProviderFromArgs, resolveEditorOpenTarget, type EditorActionStep } from "./editor-actions.js"
+import { DEFAULT_EDITOR_WAIT_SELECTOR, editorActionStepsFromArgs, editorOpenTargetFromArgs, editorValidateContentFromArgs, editorValidateProviderFromArgs, resolveEditorOpenTarget, type EditorActionStep } from "./editor-actions.js"
 import type { PlaygroundRunResponse } from "./playground-command-errors.js"
 import type { PlaygroundCliServer } from "./preview-server.js"
 import { serializeBrowserError } from "./browser-metrics.js"
@@ -538,6 +538,7 @@ export async function runEditorOpenCommand({
   let editorState: EditorStateSnapshot | undefined
   let editorValidity: EditorValidityArtifact | undefined
   let editorCanvasReadiness: BrowserEditorCanvasProbeSummary | undefined
+  let editorReadiness: BrowserEditorReadinessSummary | undefined
   let authSummary: BrowserProbeAuthSummary | undefined
   let pendingError: Error | undefined
   let artifact: BrowserArtifact | undefined
@@ -577,10 +578,12 @@ export async function runEditorOpenCommand({
       const waitStartedAt = now()
       const waitStartedAtMs = Date.now()
       try {
-        await waitForAnyVisibleSelector(page, target.waitSelector, waitTimeoutMs)
-        editorCanvasReadiness = await waitForEditorOpenCanvasReadiness(page, target.waitSelector, waitTimeoutMs)
+        const readiness = await waitForEditorOpenReadiness(page, target.waitSelector, waitTimeoutMs)
+        editorReadiness = readiness.editorReadiness
+        editorCanvasReadiness = readiness.editorCanvasReadiness
         finalUrl = page.url()
-        stepRecords.push(browserStepRecord(1, { kind: "waitFor", selector: target.waitSelector }, "ok", waitStartedAt, waitStartedAtMs, finalUrl, {
+        stepRecords.push(browserStepRecord(1, { kind: "waitFor", selector: target.waitSelector ?? "wp.data core/block-editor.getBlocks" }, "ok", waitStartedAt, waitStartedAtMs, finalUrl, {
+          editorReadiness,
           ...(editorCanvasReadiness ? { editorCanvas: editorCanvasReadiness } : {}),
         } as never))
       } catch (error) {
@@ -606,7 +609,7 @@ export async function runEditorOpenCommand({
     }
     if (capture.has("screenshot")) {
       await artifactSession.writeGenerated("screenshot", "editor-screenshot.png", async (path) => {
-        if (editorCanvasReadiness?.ready) {
+        if (editorCanvasReadiness?.ready && target.waitSelector) {
           const frame = await resolveEditorCanvasFrame(page, target.waitSelector)
           if (frame) {
             await frame.locator(EDITOR_CANVAS_DEFAULT_LAYOUT_SELECTOR).first().screenshot({ path, timeout: waitTimeoutMs })
@@ -653,6 +656,7 @@ export async function runEditorOpenCommand({
         screenshot: capture.has("screenshot"),
         ...(editorSummary ? { editor: editorSummary } : {}),
         ...(editorValidity ? { editorValidity: editorValidity.summary } : {}),
+        ...(editorReadiness ? { editorReadiness } : {}),
         ...(editorCanvasReadiness ? { editorCanvas: editorCanvasReadiness } : {}),
         viewport,
       },
@@ -682,7 +686,7 @@ export async function runEditorOpenCommand({
   }
 
   if (pendingError) {
-    throw new Error(`wordpress.editor-open failed after ${stepRecords.length} step(s): ${pendingError.message}`)
+    throw editorOpenArtifactError(stepRecords.length, pendingError, artifact)
   }
 
   return {
@@ -727,9 +731,15 @@ export function editorOpenArtifactFilesForCapture(capture: ReadonlySet<string>,
   }
 }
 
-async function waitForEditorOpenCanvasReadiness(page: import("playwright").Page, waitSelector: string, timeoutMs: number): Promise<BrowserEditorCanvasProbeSummary | undefined> {
+export async function waitForEditorOpenReadiness(page: import("playwright").Page, waitSelector: string | undefined, timeoutMs: number): Promise<{ editorReadiness: BrowserEditorReadinessSummary; editorCanvasReadiness?: BrowserEditorCanvasProbeSummary }> {
+  const editorReadiness = await waitForEditorSemanticReadiness(page, timeoutMs)
+  if (!waitSelector) {
+    return { editorReadiness }
+  }
+
+  await waitForAnyVisibleSelector(page, waitSelector, timeoutMs)
   if (!waitSelector.includes("editor-canvas")) {
-    return undefined
+    return { editorReadiness }
   }
 
   const probe = await waitForEditorCanvasProbe(page, {
@@ -744,7 +754,11 @@ async function waitForEditorOpenCanvasReadiness(page: import("playwright").Page,
     throw new Error(`Editor canvas was not ready: ${probe.summary.diagnostics.map((diagnostic) => diagnostic.code).join(", ") || "not-ready"}`)
   }
 
-  return probe.summary
+  return { editorReadiness, editorCanvasReadiness: probe.summary }
+}
+
+export function editorOpenArtifactError(stepCount: number, error: Error, artifact: BrowserArtifact): BrowserCommandArtifactError {
+  return new BrowserCommandArtifactError(`wordpress.editor-open failed after ${stepCount} step(s): ${error.message}`, artifact)
 }
 
 export async function runEditorActionsCommand({
@@ -768,6 +782,7 @@ export async function runEditorActionsCommand({
     server,
   })
   const actionSteps = await editorActionStepsFromArgs(args)
+  const editorWaitSelector = target.waitSelector ?? DEFAULT_EDITOR_WAIT_SELECTOR
   const capture = new Set(commaListArg(args, "capture"))
   if (capture.size === 0) {
     capture.add("steps")
@@ -845,13 +860,13 @@ export async function runEditorActionsCommand({
       const waitStartedAt = now()
       const waitStartedAtMs = Date.now()
       try {
-        await waitForAnyVisibleSelector(page, target.waitSelector, waitTimeoutMs)
+        await waitForAnyVisibleSelector(page, editorWaitSelector, waitTimeoutMs)
         finalUrl = page.url()
-        stepRecords.push(browserStepRecord(1, { kind: "waitFor", selector: target.waitSelector }, "ok", waitStartedAt, waitStartedAtMs, finalUrl, {}))
+        stepRecords.push(browserStepRecord(1, { kind: "waitFor", selector: editorWaitSelector }, "ok", waitStartedAt, waitStartedAtMs, finalUrl, {}))
       } catch (error) {
         const serialized = serializeBrowserError("probe-error", error)
         errors.push(serialized)
-        stepRecords.push(browserStepRecord(1, { kind: "waitFor", selector: target.waitSelector }, "failed", waitStartedAt, waitStartedAtMs, page.url(), { error: serialized }))
+        stepRecords.push(browserStepRecord(1, { kind: "waitFor", selector: editorWaitSelector }, "failed", waitStartedAt, waitStartedAtMs, page.url(), { error: serialized }))
         pendingError = error instanceof Error ? error : new Error(String(error))
       }
     }
@@ -1113,14 +1128,14 @@ async function waitForEditorReadiness(page: import("playwright").Page, timeoutMs
     const editor = select("core/editor")
     const blockEditor = select("core/block-editor")
     const editorDispatch = dispatch("core/editor")
-    if (!editor || !blockEditor || !editorDispatch) {
+    if (!editor || !blockEditor || !editorDispatch || typeof editorDispatch.savePost !== "function") {
       return false
     }
     return {
       schema: "wp-codebox/editor-readiness/v1",
       status: "ready",
       storesAvailable: true,
-      canSave: typeof editorDispatch.savePost === "function",
+      canSave: true,
       postId: typeof editor.getCurrentPostId === "function" ? editor.getCurrentPostId() : undefined,
       postType: typeof editor.getCurrentPostType === "function" ? editor.getCurrentPostType() : undefined,
     }
@@ -1133,6 +1148,49 @@ async function waitForEditorReadiness(page: import("playwright").Page, timeoutMs
   })
 }
 
+// Opening and validating an editor require the block-editor data store. Global
+// block APIs and save availability are stricter, separate capabilities.
+async function waitForEditorSemanticReadiness(page: import("playwright").Page, timeoutMs: number): Promise<BrowserEditorReadinessSummary> {
+  return page.waitForFunction(() => {
+    const win = window as unknown as {
+      wp?: {
+        blocks?: { parse?: unknown; getBlockTypes?: () => unknown[] }
+        data?: { select?: (store: string) => Record<string, unknown>; dispatch?: (store: string) => Record<string, unknown> }
+      }
+    }
+    const select = win.wp?.data?.select
+    if (typeof select !== "function") {
+      return false
+    }
+
+    const blockEditor = select("core/block-editor")
+    if (!blockEditor || typeof blockEditor.getBlocks !== "function") {
+      return false
+    }
+
+    const wpBlocks = win.wp?.blocks
+    const blockTypes = typeof wpBlocks?.getBlockTypes === "function" ? wpBlocks.getBlockTypes() : undefined
+    const dispatch = win.wp?.data?.dispatch
+    const editor = select("core/editor")
+    const editorDispatch = typeof dispatch === "function" ? dispatch("core/editor") : undefined
+    return {
+      schema: "wp-codebox/editor-readiness/v1",
+      status: "ready",
+      storesAvailable: Boolean(editor && blockEditor),
+      canSave: typeof editorDispatch?.savePost === "function",
+      ...(Array.isArray(blockTypes) ? { blockTypesRegistered: blockTypes.length } : {}),
+      postId: typeof editor?.getCurrentPostId === "function" ? editor.getCurrentPostId() : undefined,
+      postType: typeof editor?.getCurrentPostType === "function" ? editor.getCurrentPostType() : undefined,
+    }
+  }, undefined, { timeout: timeoutMs }).then(async (handle) => {
+    const readiness = await handle.jsonValue() as BrowserEditorReadinessSummary | false
+    if (!readiness) {
+      throw new Error("wp-codebox-editor-readiness-timeout: Gutenberg block runtime did not become available")
+    }
+    return readiness
+  })
+}
+
 async function saveEditorPost(page: import("playwright").Page, step: Extract<EditorActionStep, { kind: "savePost" }>, timeoutMs: number): Promise<BrowserEditorSaveSummary> {
   const save = await page.evaluate(async (input) => {
     const win = window as unknown as {
@@ -1601,6 +1659,7 @@ export async function runEditorValidateBlocksCommand({
     runtimeSpec,
     server,
   })
+  const editorWaitSelector = target.waitSelector ?? DEFAULT_EDITOR_WAIT_SELECTOR
   const content = await editorValidateContentFromArgs(args)
   const provider = editorValidateProviderFromArgs(args)
   const waitTimeoutMs = durationArg(args, "wait-timeout", EDITOR_VALIDATE_BLOCKS_READY_TIMEOUT_MS)
@@ -1639,7 +1698,7 @@ export async function runEditorValidateBlocksCommand({
 
     await page.goto(targetUrl, { waitUntil: "domcontentloaded", timeout: waitTimeoutMs })
     finalUrl = page.url()
-    await waitForAnyVisibleSelector(page, target.waitSelector, waitTimeoutMs)
+    await waitForAnyVisibleSelector(page, editorWaitSelector, waitTimeoutMs)
     await waitForEditorBlocksRuntime(page, waitTimeoutMs)
     finalUrl = page.url()
     validation = await validateEditorBlocks(page, { content, provider })

tests/editor-actions.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict"
-import { captureEditorState, captureEditorValidity, editorOpenArtifactFilesForCapture, editorOpenArtifactPathPrefixFromArgs } from "../packages/runtime-playground/src/editor-command-runners.js"
+import { captureEditorState, captureEditorValidity, editorOpenArtifactError, editorOpenArtifactFilesForCapture, editorOpenArtifactPathPrefixFromArgs, waitForEditorOpenReadiness } from "../packages/runtime-playground/src/editor-command-runners.js"
+import { isBrowserCommandArtifactError } from "../packages/runtime-playground/src/browser-command-artifact-error.js"
 import { editorActionStepsFromArgs, editorOpenTargetFromArgs, resolveEditorOpenTarget } from "../packages/runtime-playground/src/editor-actions.js"
 
 const steps = await editorActionStepsFromArgs([
@@ -24,6 +25,7 @@ await assert.rejects(
 )
 
 const target = editorOpenTargetFromArgs(["target=post-new"])
+assert.equal(target.waitSelector, undefined)
 const unavailableEditorState = await captureEditorState({
   evaluate: async (callback: () => unknown) => {
     const globals = globalThis as typeof globalThis & { window?: unknown }
@@ -166,4 +168,58 @@ assert.throws(
   /relative artifact directory/,
 )
 
+// Live fixture evidence established that the block-editor store can be usable
+// before global block APIs, core/editor, or savePost are available. Opening the
+// editor must accept that state; an explicit selector remains an additional
+// caller assertion.
+const readinessCalls: Array<string | undefined> = []
+const semanticReadyPage = {
+  waitForFunction: async (predicate: (selector?: string) => unknown, selector?: string) => {
+    readinessCalls.push(selector)
+    if (selector) {
+      throw new Error(`Timed out waiting for ${selector}`)
+    }
+    const globals = globalThis as typeof globalThis & { window?: unknown }
+    const previousWindow = globals.window
+    globals.window = {
+      wp: {
+        data: {
+          select: (store: string) => store === "core/block-editor"
+            ? { getBlocks: () => Array.from({ length: 118 }) }
+            : undefined,
+          dispatch: () => ({}),
+        },
+      },
+    }
+    try {
+      const readiness = predicate()
+      assert.ok(readiness)
+      return { jsonValue: async () => readiness }
+    } finally {
+      globals.window = previousWindow
+    }
+  },
+} as never
+const semanticReadiness = await waitForEditorOpenReadiness(semanticReadyPage, undefined, 1)
+assert.equal(semanticReadiness.editorReadiness.blockTypesRegistered, undefined)
+assert.equal(semanticReadiness.editorReadiness.storesAvailable, false)
+assert.equal(semanticReadiness.editorReadiness.canSave, false)
+await assert.rejects(
+  () => waitForEditorOpenReadiness(semanticReadyPage, ".legacy-editor-shell", 1),
+  /Timed out waiting for \.legacy-editor-shell/,
+)
+assert.deepEqual(readinessCalls, [undefined, undefined, ".legacy-editor-shell"])
+
+const retainedArtifact = {
+  artifactType: "editor-open",
+  requestedUrl: "http://example.test/wp-admin/post-new.php",
+  url: "http://example.test/wp-admin/post-new.php",
+  preview: { effectiveOrigin: "http://example.test" },
+  files: { screenshot: "files/browser/editor-screenshot.png", editorState: "files/browser/editor-state.json", console: "files/browser/editor-console.jsonl", summary: "files/browser/editor-summary.json" },
+  summary: { consoleMessages: 1, errors: 1, finalUrl: "http://example.test/wp-admin/post-new.php", htmlSnapshot: false, networkEvents: 0, replayability: "diagnostic-only", screenshot: true, viewport: null },
+} as never
+const readinessFailure = editorOpenArtifactError(2, new Error("editor readiness timed out"), retainedArtifact)
+assert.equal(isBrowserCommandArtifactError(readinessFailure), true)
+assert.strictEqual(readinessFailure.artifact, retainedArtifact)
+
 console.log("editor actions ok")