TINYDOC-3562 - Document beforeSetContent listener for AI-only revision history

modules/ROOT/pages/revisionhistory.adoc

@@ -116,9 +116,14 @@ The metadata is an `+Object+` that holds additional information about a revision
 
 A revision is identified as AI-assisted through the `+source+` field of its xref:#metadata[`+metadata+`] object. When `+metadata.source+` is `+'ai'+`, an AI badge appears on that revision card by default. Set xref:revisionhistory_ai_attribution[`+revisionhistory_ai_attribution+`] to `+false+` to hide the badge.
 
-The {pluginname} plugin does not set this marker automatically. The xref:tinymceai.adoc[{productname} AI] plugin sets `+ai+` to `+true+` on the `+SetContent+` event for any content it inserts. Detecting that signal and recording it as `+metadata.source+` when saving a revision is the responsibility of the application. There are three steps to keep attribution accurate:
+The {pluginname} plugin does not set this marker automatically. The xref:tinymceai.adoc[{productname} AI] plugin sets `+ai+` to `+true+` on both the `+BeforeSetContent+` and `+SetContent+` events for any content it inserts, so either event can signal AI involvement:
 
-. **Detect**: Listen for the `+SetContent+` event and record when its `+ai+` property is `+true+`.
+* `+BeforeSetContent+` fires immediately before the AI content is inserted. Calling `+editor.getContent()+` at this point returns the content as it stood before the AI edit.
+* `+SetContent+` fires immediately after the AI content is inserted. Calling `+editor.getContent()+` at this point returns the AI-generated result.
+
+Either event can drive attribution, and both can be used together. Listening for `+SetContent+` alone records the AI-assisted result; listening for both also preserves the content that preceded each AI edit as its own revision. Detecting the signal and recording it as `+metadata.source+` when saving a revision is the responsibility of the application. There are three steps to keep attribution accurate:
+
+. **Detect**: Listen for `+BeforeSetContent+`, `+SetContent+`, or both, and record when the `+ai+` property is `+true+`.
 . **Save**: When saving a revision, set `+metadata.source+` to `+'ai'+` if AI contributed since the last save.
 . **Restore**: When a revision is restored, carry its marker forward so later revisions remain correctly attributed.
 
@@ -155,6 +160,36 @@ const saveRevision = () => {
 };
 ----
 
+A revision saved this way can combine human edits made since the last save with the AI-generated change. To keep the two apart, save a revision from `+BeforeSetContent+` as well. This records the content that preceded each AI edit as its own revision, producing a finer-grained history:
+
+[source,js]
+----
+// Save the pre-AI (human) content before the TinyMCE AI plugin inserts its edit.
+editor.on('BeforeSetContent', (e) => {
+  if (e.ai) {
+    const revision = {
+      revisionId: createRevisionId(), // Replace with your ID generation
+      createdAt: new Date().toISOString(),
+      content: editor.getContent()
+    };
+    saveToStorage(revision); // Replace with your storage call
+  }
+});
+
+// Save the post-AI content and mark it as AI-assisted.
+editor.on('SetContent', (e) => {
+  if (e.ai) {
+    const revision = {
+      revisionId: createRevisionId(), // Replace with your ID generation
+      createdAt: new Date().toISOString(),
+      content: editor.getContent(),
+      metadata: { source: 'ai' }
+    };
+    saveToStorage(revision); // Replace with your storage call
+  }
+});
+----
+
 === Restoring an AI-assisted revision
 
 Restoring a revision sets its content back into the editor and fires the `+VersionRestored+` event. The restored content is not flagged as AI-assisted, so look up the restored revision and carry its marker forward to the next save: