70:T3b9d,# Migrating Editing to Pierre Diffs 1.4 Pierre Diffs 1.4 makes editable components responsible for their active edit session. Applications no longer need to mirror every changed file, diff, or annotation back into the component while the user is typing. Use component `onEditChange` to observe or autosave a draft and component `onEditComplete` as the commit boundary. Return `'accept'` to install the completed file or diff and its final annotations, or `'reject'` to restore the latest external value and annotations. ## API changes | Before | 1.4 | | -------------------------------------- | -------------------------------------------------------------- | | `new Editor(options?)` | `new Editor('file' \| 'file-diff', options?, editStateKey?)` | | `onChange(file, annotations, event)` | `onChange(event)` | | `EditorChangeEvent` | `EditorChangeEvent<'file' \| 'file-diff', LAnnotation, Caret>` | | `editor.getState()` / `setState()` | `editor.getViewState()` / `setViewState()` | | `EditorState` | `EditorViewState` | | Old scroll-only `EditorViewState` | `EditorViewportState` | | `persistState` / `persistStateStorage` | `editStateKey` or application-owned storage | | `createEditor(options)` | `createEditor(editorType, options, editStateKey)` | | No editor completion observer | `EditorOptions.onComplete(event)` | | `cleanUp(recycle?: boolean)` | `cleanUp('discard' \| 'recycle' \| 'complete')` | The new `EditorChangeEvent` contains `changes`, `file`, `lineAnnotations`, and the attached `editor`. For a diff, `event.file` is the editable new file, not a `FileDiffMetadata` object. Prefer component-level `onEditChange` and `onEditComplete` callbacks for normal integrations. Their completion return value decides whether to accept or reject. The lower-level `EditorOptions.onChange` and `EditorOptions.onComplete` callbacks are for editor-wide observation. You cannot accept or reject from `EditorOptions.onComplete`. The editor completion observer receives the exact same frozen event before the component callback and still fires when no component completion handler exists. Its argument is `EditorEditCompleteEvent<'file' | 'file-diff', LAnnotation, Caret>`, the union of `FileEditCompleteEvent` and `FileDiffEditCompleteEvent` exported from `@pierre/diffs/edit`. ## Add the EditorType to TypeScript types Editors are component-specific in 1.4. Use `'file'` for `File` and `'file-diff'` for `FileDiff`. The constructor infers the type when you do not provide generic arguments: ```ts const editor = new Editor('file'); ``` If you previously specified annotation metadata, add the editor type before it: ```ts type ThreadMetadata = { threadId: string }; const editor = new Editor<'file-diff', ThreadMetadata>('file-diff'); const options: EditorOptions<'file-diff', ThreadMetadata, undefined> = {}; ``` The same editor-type-first order applies to `TextDocument`, `EditState`, and `EditorInitialState`. ### Supply metadata arguments to type-only APIs Type-only APIs such as `EditorOptions`, `EditorFactory`, `FileOptions`, `FileDiffOptions`, `CodeViewOptions`, and edit event types require annotation and caret metadata arguments. Use `undefined` for metadata you do not provide: ```ts type Options = FileDiffOptions; type Change = EditorChangeEvent<'file-diff', ThreadMetadata, undefined>; ``` Concrete classes, React components, and preload functions retain metadata defaults, so they do not require explicit generic arguments. Use the `'file' | 'file-diff'` union only for code that handles both types. ### Move editor type imports Import editor events, state, selections, document positions, markers, focus options, and factory types from `@pierre/diffs/edit`. ```ts // Before import type { EditorChangeEvent, EditorViewState, MarkerSeverity, } from '@pierre/diffs'; // 1.4 import type { EditorChangeEvent, EditorViewState, MarkerSeverity, } from '@pierre/diffs/edit'; ``` ### Replace structural edit types Pierre only supports its concrete editor and component classes. The structural types that allowed plain objects to look like supported implementations have been removed: - Replace `DiffsEditor` with `Editor<'file', LAnnotation>` or `Editor<'file-diff', LAnnotation>`. - Replace `DiffsTextDocument` with the matching `TextDocument` type. - Replace `DiffsEditableComponent`, `EditableInstance`, and `DiffsBaseComponent` with the concrete `File` or `FileDiff` class being used. - Replace `DiffsComponentOptions` with the options type for the concrete component, such as `FileOptions`, `FileDiffOptions`, or `CodeViewOptions`. Use a union only when application code genuinely handles multiple component types. `Editor.edit()` and `EditorOptions.onAttach` now expose Pierre's matching component instance rather than a separately maintained interface. ## Let components own active edits Remove handlers that immediately feed changed contents or annotations back through `render()`, React state, or CodeView item updates. The component now owns the draft and remaps annotation positions during the session. Feeding those values back can create loops or overwrite session-owned annotation positions with stale external positions. Application state remains the external source of truth. Update the file, diff, and annotations once when the edit is accepted: - `onEditChange(event)` observes the current draft. Use it for autosave, validation, or side effects without updating the active component. - `File.onEditComplete(event)` completes with `event.file` and final `event.lineAnnotations`. - `FileDiff.onEditComplete(event)` completes with `event.fileDiff`, final annotations, and `oldFile`/`newFile` for file-pair or patch owners. - Component `onEditComplete` always fires once when the session ends, including unchanged, selection-only, scroll-only, annotation-only, and fully undone sessions. A missing component completion handler rejects. ## Vanilla JavaScript Put lifecycle callbacks on `File` or `FileDiff`, then end the session with the disposer returned by `editor.edit()`: ```js let file = initialFile; let annotations = initialAnnotations; let shouldAccept = true; const view = new File({ onEditChange(event) { autosaveDraft(event.file); }, onEditComplete(event) { if (!shouldAccept) return 'reject'; file = event.file; annotations = event.lineAnnotations ?? []; return 'accept'; }, }); view.render({ fileContainer, file, lineAnnotations: annotations }); const editor = new Editor('file', {}, `file:${fileId}`); const finishEditing = editor.edit(view); // Save or Cancel sets shouldAccept, then ends the session. finishEditing(); ``` Completed values have no `cacheKey`. If the surface uses keyed render caching, assign a fresh key before accepting. Do not reuse the replaced value's key and do not clone the file or diff, simply mutate it for the `cacheKey`. ```js event.file.cacheKey = `file:${fileId}:${revision}`; return 'accept'; ``` ## React `File`, `FileDiff`, `MultiFileDiff`, and `PatchDiff` expose the same callbacks as top-level props. Move `onEditChange` and `onEditComplete` out of the React component's `options` object. Do not call `setFile`, `setDiff`, or `setAnnotations` from `onEditChange`; update them at completion: ```jsx const cancelRequested = useRef(false); // Reset to false before starting or saving. Set to true before ending via Cancel. autosaveDraft(event.file)} onEditComplete={(event) => { if (cancelRequested.current) { cancelRequested.current = false; return 'reject'; } event.file.cacheKey = `file:${fileId}:${nextRevision()}`; setFile(event.file); setAnnotations(event.lineAnnotations ?? []); return 'accept'; }} />; ``` Update `EditProvider` factories to forward all three arguments. The provider no longer reuses editors based on `editorOptions` object identity. ```jsx new Editor(editorType, options, editStateKey) } > {children} ``` When the factory is declared outside JSX, use the exported `EditorFactory` type so its options and returned editor stay matched to the requested editor type: ```ts import type { EditorFactory } from '@pierre/diffs/edit'; const createEditor: EditorFactory = ( editorType, options, editStateKey ) => new Editor(editorType, options, editStateKey); ``` ## CodeView CodeView callbacks are now event-first. Completion also receives `nextItem`, which contains the completed value and annotations, `edit: false`, and an incremented `version`. `onItemEditComplete` runs whenever the item session ends, including unchanged, annotation-only, and fully undone sessions. Collapse and virtualization only suspend the session. ```js const codeView = new CodeView({ getEditStateKey(item) { return `edit-state:${item.id}`; }, createEditor(editorType, options, editStateKey) { return new Editor(editorType, options, editStateKey); }, onItemEditComplete(event, item, nextItem) { return 'accept'; }, }); ``` The `createEditor` option remains optional, but a provided factory must always return the editor requested by `editorType`. Vanilla CodeView installs `nextItem` after acceptance. Controlled React CodeView users must also put `nextItem` into their `items` state. Rejecting keeps the latest external item. Completion caused by removal or unmount reports the result but cannot reinstall the removed item. ## Replace `persistState` `persistState`, `persistStateStorage`, `IStateStorage`, and built-in IndexedDB storage have been removed. `FileContents.cacheKey` now identifies only render/highlighting cache/WorkerPool entries, not edit state. Use a stable `editStateKey` to retain the draft, undo/redo history, selections, and eligible scroll state between editor instances in the same session: ```jsx ``` ```js const editor = new Editor('file', {}, `draft:${fileId}`); ``` For CodeView, return the key from `getEditStateKey(item)`. Keys are explicit application identities, are not inferred from `cacheKey`, and do not survive a reload. You can clear an inactive draft after it is submitted or abandoned: ```js EditStateManager.clear('file', `draft:${fileId}`); ``` ## Persist across reloads For local storage or another durable store, save the latest file and optional JSON-safe view state. Not all aspects of state are serializable (like undo history). An example of what is serializable: ```js function saveDraft(key, event) { localStorage.setItem( key, JSON.stringify({ file: event.file, viewState: event.editor.getViewState(), }) ); } function loadDraft(key) { const value = localStorage.getItem(key); if (value == null) return undefined; try { return JSON.parse(value); } catch { localStorage.removeItem(key); return undefined; } } ``` Pass the loaded file back as the component input. Restore selections and supported scroll offsets with a small `initialState`: ```jsx const draft = loadDraft(`draft:${fileId}`); ; ``` This starts with fresh undo history. `onEditChange` does not fire for selection- or scroll-only changes, so capture `getViewState()` at an explicit save or navigation boundary when those changes matter. For a durable diff draft, persist the old file and latest new file, then reconstruct the diff after loading. ## Other breaking changes - `EditHistoryEntry` and `EditHistoryState` now take the editor type before annotation metadata. Replace `EditHistoryLineAnnotation` with `EditorLineAnnotation<'file' | 'file-diff', LAnnotation>`, or use the specific editor type when the history belongs to only one component type. - Call the disposer returned by `editor.edit(component)` for normal completion. `cleanUp('discard')` still runs completion callbacks but never installs an accepted result. `cleanUp('recycle')` only suspends rendering for virtualization and does not complete the session. - Direct component `attachEditor()` and `completeEditSession()` calls are no longer supported. Do not call their internal replacements; use `editor.edit(component)` and its returned disposer. - `TextDocument.clone()` was removed. Construct a fresh `TextDocument` from its text when fresh history is appropriate. - We no longer automatically derive `cacheKeys`, so you must supply them now. Ensure they are always unique based on content. ## What's Changed * [diffs] Improve Invalid Diff Parsing by @amadeus in https://github.com/pierrecomputer/pierre/pull/1095 * chore: mark React as optional by @onmax in https://github.com/pierrecomputer/pierre/pull/1091 * [diffs] Cache Key Cleanup by @amadeus in https://github.com/pierrecomputer/pierre/pull/1055 * [diffs] External vs Internal Edit Hardening by @amadeus in https://github.com/pierrecomputer/pierre/pull/1072 * [diffs] Edit Completion Handling by @amadeus in https://github.com/pierrecomputer/pierre/pull/1089 * [diffs] Refactor Edit Persistance by @amadeus in https://github.com/pierrecomputer/pierre/pull/1092 * [diffs/edit] Misc Webkit Bug Fixes by @amadeus in https://github.com/pierrecomputer/pierre/pull/1101 * Harden WorkerPool initialzation to better handle errors by @amadeus in https://github.com/pierrecomputer/pierre/pull/1102 * Fat/editor decorations by @fat in https://github.com/pierrecomputer/pierre/pull/1103 * fix(diffs): portable lru types by @onmax in https://github.com/pierrecomputer/pierre/pull/1112 * fix(diffs): avoid stack overflow when rendering massive diffs by @Josh-Walker-GM in https://github.com/pierrecomputer/pierre/pull/1113 * [diffs/edit] Editor Types Refactor by @amadeus in https://github.com/pierrecomputer/pierre/pull/1105 * Fat/tab tab tab by @fat in https://github.com/pierrecomputer/pierre/pull/1104 ## New Contributors * @onmax made their first contribution in https://github.com/pierrecomputer/pierre/pull/1091 * @Josh-Walker-GM made their first contribution in https://github.com/pierrecomputer/pierre/pull/1113 **Full Changelog**: https://github.com/pierrecomputer/pierre/compare/diffs-v1.3.6...diffs-v1.4.055:["$","$L6c",null,{"entries":[{"key":["platform",{"userId":"anon"},"repo","releases",{"owner":"pierrecomputer","repo":"pierre"},"detail","diffs-v1.4.0"],"data":{"id":"1000910","version":"diffs-v1.4.0","channel":"stable","title":"@pierre/diffs v1.4.0","publishedAt":"2026-09-04T03:43:34Z","summary":"# Migrating Editing to Pierre Diffs 1.4","notesMarkdown":"$70","attachments":[],"htmlUrl":"https://trylle.com/pierrecomputer/pierre/releases/tag/diffs-v1.4.0","target":"main","commitSha":"8d4b6af8c8f1b51c6c373bf7be6c162435306766","publisher":{"id":-1,"login":"Ghost"},"zipballUrl":"/v1/repositories/pierrecomputer/pierre/archive?ref=diffs-v1.4.0&format=zip","tarballUrl":"/v1/repositories/pierrecomputer/pierre/archive?ref=diffs-v1.4.0&format=tar.gz","isDraft":false,"isPrerelease":false},"fetchedAt":1793409395963}],"children":"$L71"}]