SDK API Specification

use std::collections::BTreeSet;

        use casual_doc_sdk::{
            Affinity, BlockSnapshot, Engine, EngineConfig, InsertTextRequest, Position,
            SelectionSnapshot, SetSelectionRequest,
        };

        let engine = Engine::new(EngineConfig::default())?;
        let session = engine.create_blank()?;
        let snapshot = session.snapshot()?;
        let paragraph = match &snapshot.body[0] {
            BlockSnapshot::Paragraph(paragraph) => paragraph.id.clone(),
        };

        let result = session.insert_text(InsertTextRequest {
            base_revision: snapshot.revision,
            at: Position {
                node: paragraph,
                grapheme_offset: 0,
                affinity: Affinity::After,
            },
            text: "Hello".to_owned(),
            marks: BTreeSet::new(),
        })?;

        assert_eq!(result.revision.get(), 1);

        let selection = session.selection()?;
        session.set_selection(SetSelectionRequest {
            base_revision: result.revision,
            selection: SelectionSnapshot {
                anchor: selection.anchor,
                focus: selection.focus,
            },
        })?;

let mut subscription = session.subscribe()?;
        session.delete_range(DeleteRangeRequest { /* ... */ })?;
        session.split_paragraph(SplitParagraphRequest { /* ... */ })?;
        session.join_paragraphs(JoinParagraphRequest { /* ... */ })?;
        session.undo(expected_revision)?;
        session.redo(expected_revision)?;
        let batch = subscription.drain(64)?;

let session = engine.open_normalized_json(
            bytes,
            OpenNormalizedOptions::default(),
        )?;
        let deterministic_bytes = session.export_normalized_json()?;

// All three cross the JS boundary as one JSON string per call, the same
        // convention as every other multi-record casual-doc-wasm query (e.g.
        // `documentOutline`, `copyRichRuns`) — see that crate's Cargo.toml for the
        // documented rationale. `reviewSummary()` (below) remains available,
        // unchanged, for existing callers; the three methods here are the first-class
        // typed replacement for its nested `comments`/`revisions` arrays.

        // Every comment or threaded reply. `anchor` is present only if the marker
        // pair resolved in the live tree.
        doc.listComments(): string; // JSON: Array<{
          //   id: string; author?: string; initials?: string; date?: string;
          //   resolved: boolean; paraId?: string; parentParaId?: string; text: string;
          //   anchor?: { node: string; start: number; end: number };
          // }>

        // Every tracked-change/formatting revision, document order.
        doc.listRevisions(): string; // JSON: Array<{
          //   id: string;
          //   kind: "insertion" | "deletion" | "move_from" | "move_to" | "formatting";
          //   author?: string; date?: string; groupId?: string;
          //   groupKind?: "typing" | "replacement" | "formatting";
          //   revisionId?: string; text: string;
          //   anchor: { node: string; start: number; end: number };
          //   movePair?: { name: string; fromStart: string; toStart: string };
          //   formattingDelta?: unknown;
          // }>

        // One thread: `comment`'s root plus every descendant reply, root-first in
        // creation order. Resolves any member id (including a reply-to-a-reply) to
        // its thread root first. Throws if `comment` is not a known comment id.
        doc.commentThread(comment: string): string; // JSON: Array<...same shape as listComments()>

        // Legacy combined query, unchanged: `{ comments: [...], revisions: [...] }`
        // using the same per-item shapes as above.
        doc.reviewSummary(): string;

use casual_doc_sdk::{
            Engine, EngineConfig, OpenOptions, Viewport, CommandArgs,
        };

        let engine = Engine::new(EngineConfig::default())?;
        let session = engine.open_docx(docx_bytes, OpenOptions::default()).await?;

        let subscription = session.subscribe(|event| {
            println!("{event:?}");
        });

        session.set_viewport(Viewport {
            width_px: 1200.0,
            height_px: 900.0,
            scale: 1.0,
            scroll_y: 0.0,
        })?;

        session.execute("text.insert", CommandArgs::text("Hello"))?;
        let bytes = session.save_docx(Default::default()).await?;

// Designed, not shipped. See the note above.
        import { DocumentEngine } from "@casualoffice/opendoc-embed";

        const engine = await DocumentEngine.create({
          locale: "en-US",
          externalResources: "deny",
        });

        const session = await engine.openDocx(fileBytes);

        session.on("transactionCommitted", event => {
          console.log(event.revision);
        });

        session.setViewport({
          width: canvas.width,
          height: canvas.height,
          scale: devicePixelRatio,
          scrollY: 0,
        });

        canvas.addEventListener("pointerdown", e => {
          session.handlePointer({
            kind: "down",
            x: e.offsetX,
            y: e.offsetY,
            button: e.button,
            modifiers: readModifiers(e),
          });
        });

        await session.execute("format.toggle_bold");
        const saved = await session.saveDocx();

pub struct Engine { /* opaque */ }

        impl Engine {
            pub fn new(config: EngineConfig) -> Result<Self, SdkError>;
            pub async fn open_docx(
                &self,
                bytes: Bytes,
                options: OpenOptions,
            ) -> Result<DocumentSession, SdkError>;
            pub fn create_blank(
                &self,
                options: NewDocumentOptions,
            ) -> Result<DocumentSession, SdkError>;
            pub fn register_plugin(
                &self,
                plugin: Arc<dyn Plugin>,
            ) -> Result<(), SdkError>;
        }

impl DocumentSession {
            pub fn id(&self) -> SessionId;
            pub fn revision(&self) -> RevisionId;
            pub fn metadata(&self) -> DocumentMetadataSnapshot;

            pub fn execute(
                &self,
                command: impl Into<CommandId>,
                args: CommandArgs,
            ) -> Result<CommandResult, SdkError>;

            pub fn query_command(
                &self,
                command: impl Into<CommandId>,
            ) -> Result<CommandState, SdkError>;

            pub fn selection(&self) -> Result<SelectionSnapshot, SdkError>;
            pub fn set_selection(&self, request: SetSelectionRequest) -> Result<(), SdkError>;

            pub fn handle_key(&self, event: KeyEvent) -> Result<InputResult, SdkError>;
            pub fn handle_pointer(&self, event: PointerEvent) -> Result<InputResult, SdkError>;
            pub fn handle_ime(&self, event: ImeEvent) -> Result<InputResult, SdkError>;

            pub fn set_viewport(&self, viewport: Viewport) -> Result<(), SdkError>;
            pub async fn scene(&self, request: SceneRequest) -> Result<SceneSnapshot, SdkError>;

            pub async fn save_docx(
                &self,
                options: SaveOptions,
            ) -> Result<Bytes, SdkError>;

            pub fn snapshot(&self) -> Result<DocumentSnapshot, SdkError>;
            pub fn subscribe(
                &self,
                listener: EventListener,
            ) -> Subscription;

            pub fn close(self) -> Result<(), SdkError>;
        }

pub enum ResourceRequest {
            Font(FontRequest),
            Image(ImageRequest),
            ExternalRelationship(ExternalRelationshipRequest),
            Dictionary(DictionaryRequest),
        }

pub trait Plugin: Send + Sync {
            fn manifest(&self) -> PluginManifest;
            fn register(&self, registry: &mut PluginRegistry) -> Result<(), PluginError>;
        }