feat(diagnostics): integrate revision-safe actions into CwlEditor

.github/workflows/writing-diagnostics-editor-actions-tdd.yml

@@ -0,0 +1,77 @@
+name: Writing Diagnostics Editor Actions TDD
+
+on:
+  push:
+    branches:
+      - feat/writing-diagnostics-editor-actions
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: writing-diagnostics-editor-actions-tdd-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  focused-editor-actions:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6.0.10
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Run standalone writing-diagnostic integration tests
+        run: |
+          set -euo pipefail
+          output_file="$(mktemp)"
+          trap 'rm -f "$output_file"' EXIT
+          set +e
+          pnpm exec vitest run \
+            src/components/CwlEditor.writingDiagnostics.test.tsx \
+            src/components/CwlEditor.writingDiagnosticApply.test.tsx \
+            src/components/useWritingDiagnosticsController.apply.test.tsx \
+            src/components/useEditorHandle.test.tsx \
+            --pool=forks \
+            --maxWorkers=1 2>&1 | tee "$output_file"
+          test_status=${PIPESTATUS[0]}
+          set -e
+          if grep -Fq 'not wrapped in act' "$output_file"; then
+            echo "::error::Focused editor actions emitted a React act warning."
+            exit 1
+          fi
+          exit "$test_status"
+      - name: Typecheck standalone writing-diagnostic contracts
+        run: pnpm typecheck
+      - name: Run complete production coverage gate
+        env:
+          NODE_OPTIONS: --max-old-space-size=6144
+        run: |
+          set -euo pipefail
+          output_file="$(mktemp)"
+          trap 'rm -f "$output_file"' EXIT
+          set +e
+          pnpm coverage 2>&1 | tee "$output_file"
+          test_status=${PIPESTATUS[0]}
+          set -e
+          if grep -Fq 'not wrapped in act' "$output_file"; then
+            echo "::error::Production coverage emitted a React act warning."
+            exit 1
+          fi
+          exit "$test_status"
+      - name: Build all package entrypoints
+        run: pnpm build
+      - name: Verify isolated packed-package consumers
+        run: pnpm verify:package
+      - name: Build demonstration application
+        run: pnpm build:demo

src/components/CwlEditor.tsx

@@ -19,6 +19,8 @@ import { applyEditorFormReset } from './editorFormReset.js';
 import { editorHtmlToValue, editorValueToHtml } from './editorSerialization.js';
 import { useEditorHandle } from './useEditorHandle.js';
 import { useLatestRef } from './useLatestRef.js';
+import { useWritingDiagnosticsController } from './useWritingDiagnosticsController.js';
+import { WritingDiagnosticsPanel } from './WritingDiagnosticsPanel.js';
 
 /**
  * CwlEditor — a commercial-grade rich-text editor with interchangeable
@@ -62,6 +64,11 @@ export const CwlEditor = forwardRef<CwlEditorHandle, CwlEditorProps>(
       ariaErrorMessage,
       ariaInvalid,
       ariaRequired,
+      writingDiagnostics,
+      onWritingDiagnosticAction,
+      onWritingDiagnosticsError,
+      writingDiagnosticsLabel,
+      printWritingDiagnostics,
     },
     ref,
   ) {
@@ -190,7 +197,14 @@ export const CwlEditor = forwardRef<CwlEditorHandle, CwlEditorProps>(
       },
     });
 
-    useEditorHandle(ref, editor, modeRef);
+    const writingDiagnosticsController = useWritingDiagnosticsController({
+      editor,
+      diagnostics: writingDiagnostics,
+      onAction: onWritingDiagnosticAction,
+      onError: onWritingDiagnosticsError,
+    });
+
+    useEditorHandle(ref, editor, modeRef, writingDiagnosticsController);
 
     useEffect(() => {
       editor?.setEditable(editable);
@@ -248,6 +262,24 @@ export const CwlEditor = forwardRef<CwlEditorHandle, CwlEditorProps>(
         formFieldDisabled={formFieldDisabled}
         formFieldInitialValue={selectedDocumentValue}
         onFormReset={editor && observesFormReset ? handleFormReset : undefined}
+        writingDiagnosticsPanel={
+          writingDiagnostics === undefined ? undefined : (
+            <WritingDiagnosticsPanel
+              controller={writingDiagnosticsController}
+              label={writingDiagnosticsLabel ?? 'Writing guidance'}
+              onApplyDiagnostic={
+                editable
+                  ? (diagnosticId) => {
+                      void writingDiagnosticsController.applyDiagnostic(
+                        diagnosticId,
+                      );
+                    }
+                  : undefined
+              }
+              printEnabled={printWritingDiagnostics}
+            />
+          )
+        }
       />
     );
   },

src/components/CwlEditor.writingDiagnosticApply.test.tsx

@@ -0,0 +1,146 @@
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react';
+import { createRef } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { CwlEditorHandle } from '../types.js';
+import type { CwlWritingDiagnostic } from '../writingDiagnostics.js';
+import { CwlEditor } from './CwlEditor.js';
+
+afterEach(cleanup);
+
+async function exactDiagnostic(
+  handle: CwlEditorHandle,
+  replacement: string,
+): Promise<CwlWritingDiagnostic> {
+  const evidence = await handle.getTextPositionSelectorEvidence();
+  if (evidence === null) throw new Error('Missing selector evidence');
+  return {
+    diagnosticId: 'apply-diagnostic',
+    documentRevision: evidence.revision,
+    textProjection: evidence.textProjection,
+    selector: evidence.selector,
+    categoryCode: 'clarity',
+    priority: 'important',
+    title: 'Clarify the request',
+    explanation: 'Make the requested action explicit.',
+    suggestedReplacement: replacement,
+    provenance: {
+      workflowId: 'email-writing-review',
+      workflowVersion: '1',
+      judgePolicyVersion: 'evaluation-only-1',
+    },
+  };
+}
+
+describe('CwlEditor writing-diagnostic application', () => {
+  it('rechecks the exact revision, inserts plain text, invalidates diagnostics, and remains undoable', async () => {
+    const handleRef: { current: CwlEditorHandle | null } = { current: null };
+    const onAction = vi.fn();
+    const onChange = vi.fn();
+    const view = render(
+      <CwlEditor
+        defaultValue="Alpha beta"
+        hideToolbar
+        onChange={onChange}
+        onWritingDiagnosticAction={onAction}
+        ref={handleRef}
+      />,
+    );
+    await waitFor(() => expect(handleRef.current?.getEditor()).not.toBeNull());
+
+    act(() => {
+      handleRef.current!.getEditor()!.commands.setTextSelection({ from: 1, to: 6 });
+    });
+    const hostileTagName = ['scr', 'ipt'].join('');
+    const replacement = `<${hostileTagName}>alert(1)</${hostileTagName}>`;
+    const diagnostic = await exactDiagnostic(handleRef.current!, replacement);
+
+    view.rerender(
+      <CwlEditor
+        defaultValue="Alpha beta"
+        hideToolbar
+        onChange={onChange}
+        onWritingDiagnosticAction={onAction}
+        ref={handleRef}
+        writingDiagnostics={[diagnostic]}
+        writingDiagnosticsLabel="Email writing guidance"
+      />,
+    );
+
+    const apply = await screen.findByRole('button', {
+      name: 'Apply suggestion for Clarify the request',
+    });
+    expect(apply).toBeEnabled();
+    fireEvent.click(apply);
+
+    await waitFor(() =>
+      expect(handleRef.current?.getValue()).toBe(`${replacement} beta`),
+    );
+    expect(document.querySelector('script')).toBeNull();
+    expect(document.querySelector('.cwl-writing-diagnostic')).toBeNull();
+    expect(onAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: 'applied',
+        reasonCode: 'explicit',
+        diagnosticId: 'apply-diagnostic',
+        resultingDocumentRevision: expect.objectContaining({
+          algorithm: 'SHA-256',
+        }),
+      }),
+    );
+    expect(onChange).toHaveBeenCalled();
+
+    act(() => {
+      expect(handleRef.current!.getEditor()!.commands.undo()).toBe(true);
+    });
+    expect(handleRef.current?.getValue()).toBe('Alpha beta');
+  });
+
+  it('keeps replacement application disabled and inert in read-only mode', async () => {
+    const handleRef = createRef<CwlEditorHandle>();
+    const onAction = vi.fn();
+    const view = render(
+      <CwlEditor
+        defaultValue="Alpha beta"
+        editable={false}
+        hideToolbar
+        onWritingDiagnosticAction={onAction}
+        ref={handleRef}
+      />,
+    );
+    await waitFor(() => expect(handleRef.current?.getEditor()).not.toBeNull());
+
+    act(() => {
+      handleRef.current!.getEditor()!.commands.setTextSelection({ from: 1, to: 6 });
+    });
+    const diagnostic = await exactDiagnostic(handleRef.current!, 'Omega');
+
+    view.rerender(
+      <CwlEditor
+        defaultValue="Alpha beta"
+        editable={false}
+        hideToolbar
+        onWritingDiagnosticAction={onAction}
+        ref={handleRef}
+        writingDiagnostics={[diagnostic]}
+      />,
+    );
+
+    const apply = await screen.findByRole('button', {
+      name: 'Apply suggestion for Clarify the request',
+    });
+    expect(apply).toBeDisabled();
+    await expect(
+      handleRef.current!.applyWritingDiagnostic('apply-diagnostic'),
+    ).resolves.toBeNull();
+    expect(handleRef.current!.getValue()).toBe('Alpha beta');
+    expect(onAction).not.toHaveBeenCalled();
+    expect(document.querySelector('.cwl-writing-diagnostic')).not.toBeNull();
+  });
+});