Develop reusable framework for conversation-linked visual file editing

[paullizer]

Summary

Develop a reusable SimpleChat framework for conversation-initiated file editing experiences. The framework should provide a common editing surface that can render a file or generated artifact in a side pane, popout pane, or modal, keep that editing session tied back to the originating conversation, and save the result back to the originating workspace as either a new file or an overwrite of the source file.

This issue is intentionally framework-first. It should establish the reusable interaction model, state model, extension points, and persistence contracts before SimpleChat adds specific editing capabilities such as image editing, Word editing, PowerPoint editing, LaTeX editing, Mermaid editing, Visio editing, or other future file editors.

User Value

SimpleChat users should eventually be able to move naturally from a conversation into a visual editing flow, then return to the conversation with the edit history, source file, and generated output still connected. Examples include annotating an image to highlight or circle what should change before generating a revised image; viewing a Word document while requesting or typing edits; editing a PowerPoint with text, images, tables, charts, and generated visuals; or future structured editors for LaTeX, Mermaid, Visio, and similar formats.

Proposed Behavior

• Start an edit session from a conversation and associate it with the conversation id, user, source workspace, source file, file version or ETag, and workspace authorization context.
• Provide a reusable editor shell that can be hosted as a side pane, popout pane, or modal without each file type rebuilding the surrounding UX.
• Support file-type adapters that own preview/rendering, editable operations, validation, export, and saveback behavior for each supported format.
• Represent edits through a common change model that can include user instructions, direct manual edits, visual markups or annotations, assistant-proposed changes, generated outputs, and accepted or discarded revisions.
• Keep the conversation aware of the active edit session so users can ask SimpleChat to make changes while the visual surface remains synchronized.
• Allow users to save results back to the originating workspace as a new file by default, or overwrite the existing file with explicit confirmation and conflict detection.
• Preserve lineage between source file, edit session, generated file, and conversation messages so users and admins can understand how the output was created.
• Handle unsupported formats, large files, failed render/export operations, and permission failures with clear recoverable states.

Framework and Architecture Considerations

• Define backend edit-session storage, lifecycle states, authorization checks, audit/logging expectations, and cleanup behavior.
• Define frontend editor-shell contracts for layout mode, preview state, toolbar actions, dirty state, status messages, error handling, and accessibility.
• Define adapter contracts for preview generation, user-edit capture, AI instruction handling, file transformation, validation, export, and saveback.
• Define conversation integration points, including how chat messages reference an edit session, how tool calls or generation jobs update the session, and how session state survives refresh or navigation.
• Define workspace integration for personal, group, and public workspace contexts, including ownership, overwrite permissions, metadata, tags, and document indexing implications.
• Define security requirements for file preview sanitization, workspace access control, generated asset handling, and avoiding leakage of raw configuration or sensitive document data.
• Define progressive delivery boundaries so an initial framework can be implemented and validated with one reference adapter before expanding to richer file types.

UX/UI Considerations

• Provide a consistent visual editing surface that can appear as a side pane for in-context work, a popout pane for larger documents, or a modal for focused actions.
• Show source file identity, workspace location, current revision status, unsaved changes, and save destination clearly.
• Provide standard controls for preview, edit history, apply or discard changes, regenerate or revise, save as copy, overwrite, download, and return to conversation.
• Support direct user edits where appropriate while also allowing natural language instructions from the conversation to update the same session.
• Make conflict, permission, export, and generation failures visible without losing the editing session.
• Ensure keyboard accessibility, screen-reader labeling, responsive behavior, and reasonable behavior on smaller viewports.

Acceptance Criteria

• A framework design is documented covering edit-session lifecycle, adapter contracts, UI host modes, conversation binding, workspace saveback, security, and extensibility.
• Backend edit-session APIs or service contracts support creating, loading, updating, completing, cancelling, and saving conversation-linked edit sessions.
• Frontend editor-shell contracts support side pane, popout pane, and modal hosting patterns with shared state and action handling.
• A common adapter interface is defined for file preview/render, edit capture, assistant-driven transformation, validation, export, and saveback.
• Saveback supports both save-as-new-file and overwrite-with-confirmation flows, including workspace authorization and conflict detection.
• Conversation messages can reference and resume an edit session, including source file and output file lineage.
• At least one reference adapter or prototype validates the framework end to end, even if full production editing for every file type is deferred.
• Functional and/or UI tests cover the framework contracts, key UX flows, permission failures, and saveback behavior.
• Feature documentation describes the framework, extension points, UX patterns, and guidance for future editor adapters.

Notes

Potential future adapters include image editing with visual markup and image generation, Word document preview and edit, PowerPoint slide editing with generated content, LaTeX editing, Mermaid editing, Visio editing, and other structured or visual file types. This issue should focus on the reusable framework and user experience foundation rather than committing all of those adapters in the first implementation.