@aseity/idocs-preview 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @aseity/idocs-preview
 
+## 0.4.0
+
+### Minor Changes
+
+- Add `openEditor` for stateful editing of iDocs source documents, with source snapshots, undo and redo, revision tracking, and DOCX export. Add `mountEditor` for Canvas text editing with Chinese IME input and `mountEditorWorkspace` for page thumbnails, an outline, formatting controls, and paragraph, table, and image edits. Existing preview APIs remain available. Hosts own source persistence and editor session disposal.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -1,7 +1,7 @@
-# iDocs preview
+# iDocs preview and editor
 
-Read-only browser preview for Word documents (`.docx`) and iDocs source documents
-(`.idoc`). A Web Worker measures browser-local fonts with Canvas and lays out
+Browser preview for Word documents (`.docx`) and iDocs source documents
+(`.idoc`), with an interactive editor for iDocs source documents. A Web Worker measures browser-local fonts with Canvas and lays out
 the document in WASM. Canvas draws text using the same font settings. No text
 font downloads or Local Font Access permissions are required. Different installed
 fonts can change line breaks and page counts.
@@ -55,6 +55,42 @@ during server rendering.
   owns a session and a view; `mountPreview(container, doc)` shows a document you
   opened yourself. Both re-export the core types.
 
+## Editing iDocs source documents
+
+Open an editor session and mount the workspace in a container with a height:
+
+```ts
+const { openEditor } = await import("@aseity/idocs-preview/core");
+const { mountEditorWorkspace } = await import("@aseity/idocs-preview/view");
+
+const session = await openEditor({ source, name: "report.idoc" });
+const workspace = mountEditorWorkspace(container, session, { railOpen: true });
+```
+
+`source` is an iDocs YAML string or a `Uint8Array`. Use `readResource` in
+`openEditor` to resolve referenced images. The workspace includes page thumbnails,
+an outline, formatting controls, and an insert dock. It supports text selection,
+Chinese IME input, undo and redo, paragraph styles, tables, and images.
+Use `mountEditor(container, session)` for the page editor without workspace controls.
+
+Save the source snapshot through your host, then mark that revision as saved:
+
+```ts
+const snapshot = await session.snapshot();
+await saveSource(snapshot.source);
+await session.markSaved({ revision: snapshot.revision });
+const docx = await session.exportDocx();
+```
+
+`saveSource` is your application's persistence function. Subscribe to
+`session.subscribe(listener)` to observe revisions, unsaved changes, and layout
+state. Supply `onPickImage` to the workspace to enable image insertion.
+`onQuoteSelection` receives selected text for a host assistant integration.
+
+When closing the editor, call `workspace.destroy()` and `session.dispose()`.
+The workspace does not own the session. Existing preview APIs remain available.
+The development page enables the workspace with `?edit=1`.
+
 ## Opening documents
 
 `open(bytes, { name?, kind?, readResource? })` takes a `Uint8Array` or

package/dist/core/display.d.ts

@@ -150,6 +150,71 @@ export interface LineGlyph {
     /** UTF-16 offset within the line's text. */
     offset: number;
 }
+export type Affinity = 'upstream' | 'downstream';
+export type GeneratedRole = 'listMarker' | 'headingNumber' | 'captionLabel' | 'equationNumber' | 'noteNumber';
+export type ReadOnlyReason = 'aliasShared' | 'generated' | 'repeatedHeader' | 'unsupportedStory' | 'unsupportedStructure' | 'protectedInline';
+export type Revision = string & {
+    readonly __brand: 'Revision';
+};
+export type SessionId = string & {
+    readonly __brand: 'SessionId';
+};
+export type FlowId = string & {
+    readonly __brand: 'FlowId';
+};
+export type BlockId = string & {
+    readonly __brand: 'BlockId';
+};
+export type DisplayUtf16 = number & {
+    readonly __brand: 'DisplayUtf16';
+};
+export type ScalarUtf16 = number & {
+    readonly __brand: 'ScalarUtf16';
+};
+export type FlowOffset = number & {
+    readonly __brand: 'FlowOffset';
+};
+export interface Anchor {
+    readonly session: SessionId;
+    readonly flow: FlowId;
+    readonly offset: FlowOffset;
+    readonly affinity: Affinity;
+}
+export interface CaretStop {
+    readonly displayOffset: DisplayUtf16;
+    readonly anchor: Anchor;
+}
+export type BlockStyle = 'body' | 'heading1' | 'heading2' | 'heading3';
+export type TextAlign = 'left' | 'center' | 'right' | 'justify';
+export type LineSource = {
+    readonly kind: 'editable';
+    readonly path: string;
+    readonly sourceStart: ScalarUtf16;
+    readonly sourceEnd: ScalarUtf16;
+    readonly stops: readonly CaretStop[];
+    readonly blockStyle?: BlockStyle;
+    readonly align?: TextAlign;
+} | {
+    readonly kind: 'atomic';
+    readonly path?: string;
+    readonly reason: ReadOnlyReason;
+    readonly role?: GeneratedRole;
+    readonly before?: Anchor;
+    readonly after?: Anchor;
+};
+export interface LineSourceSegment {
+    readonly start: DisplayUtf16;
+    readonly end: DisplayUtf16;
+    readonly source: LineSource;
+}
+export type LineOccurrence = {
+    readonly kind: 'original';
+} | {
+    readonly kind: 'repeatedHeader';
+    readonly canonicalPath: string;
+} | {
+    readonly kind: 'readOnlyStory';
+};
 /** One laid-out line's glyph table, for hit testing. */
 export interface TextLine {
     story: Story;
@@ -169,6 +234,8 @@ export interface TextLine {
     /** Read-only in opened previews; indexed glyph objects are snapshots. */
     glyphs: readonly LineGlyph[];
     turn?: [number, number];
+    sourceSegments?: readonly LineSourceSegment[];
+    occurrence?: LineOccurrence;
 }
 export interface DisplayPage {
     number: number;

package/dist/core/editor.d.ts

@@ -0,0 +1,172 @@
+import { type Affinity, type Anchor, type BlockId, type BlockStyle, type CaretStop, type DisplayUtf16, type FlowId, type FlowOffset, type GeneratedRole, type LineOccurrence, type LineSource, type LineSourceSegment, type ReadOnlyReason, type Revision, type ScalarUtf16, type SessionId, type TextAlign, type TextLine } from './display.js';
+import { type Endpoint, type PreviewDiagnostic, type PreviewDocument, type Read, type SessionOptions } from './protocol.js';
+export type { Affinity, Anchor, BlockId, CaretStop, DisplayUtf16, FlowId, FlowOffset, GeneratedRole, LineOccurrence, LineSource, LineSourceSegment, ReadOnlyReason, Revision, ScalarUtf16, SessionId, };
+export interface EditRange {
+    readonly revision: Revision;
+    readonly start: Anchor;
+    readonly end: Anchor;
+}
+export interface Selection {
+    readonly revision: Revision;
+    readonly range: EditRange;
+    readonly reversed: boolean;
+}
+export type Mark = 'bold' | 'italic' | 'underline' | 'strike';
+export type InsertBlock = {
+    kind: 'paragraph';
+    text?: string;
+} | {
+    kind: 'heading';
+    level: 1 | 2 | 3;
+    text?: string;
+} | {
+    kind: 'callout';
+    text?: string;
+} | {
+    kind: 'table';
+    rows: number;
+    cols: number;
+} | {
+    kind: 'image';
+    src: string;
+    alt?: string;
+    widthRatio?: number;
+} | {
+    kind: 'pageBreak';
+};
+export type TableAction = 'insertRowAbove' | 'insertRowBelow' | 'insertColumnLeft' | 'insertColumnRight' | 'deleteRow' | 'deleteColumn' | 'toggleHeaderRow';
+export type ImageAlign = 'left' | 'center' | 'right';
+export type Edit = {
+    kind: 'replaceText';
+    range: EditRange;
+    text: string;
+} | {
+    kind: 'setMark';
+    range: EditRange;
+    mark: Mark;
+    enabled: boolean;
+} | {
+    kind: 'splitBlock';
+    at: Anchor;
+} | {
+    kind: 'mergeBackward';
+    at: Anchor;
+} | {
+    kind: 'setBlockStyle';
+    at: Anchor;
+    style: BlockStyle;
+} | {
+    kind: 'setAlignment';
+    at: Anchor;
+    align: TextAlign;
+} | {
+    kind: 'insertBlock';
+    after?: Anchor;
+    block: InsertBlock;
+} | {
+    kind: 'editTable';
+    at: Anchor;
+    action: TableAction;
+} | {
+    kind: 'editImage';
+    path: string;
+    widthRatio?: number;
+    align?: ImageAlign;
+    src?: string;
+    alt?: string;
+};
+export interface SourceSnapshot {
+    readonly revision: Revision;
+    readonly source: string;
+}
+export interface RenderStats {
+    readonly localResolve: boolean;
+    readonly paragraphsLaid: number;
+    readonly paragraphsReused: number;
+    readonly passes: number;
+}
+export interface Commit {
+    readonly revision: Revision;
+    readonly selection: Selection | null;
+    readonly changedBlocks: readonly BlockId[];
+    readonly localResolve: boolean;
+    readonly diagnostics: readonly PreviewDiagnostic[];
+}
+export interface EditorFrame {
+    readonly revision: Revision;
+    readonly document: PreviewDocument;
+    readonly stats: RenderStats;
+}
+export type LayoutState = {
+    kind: 'pending';
+    previous: EditorFrame | null;
+} | {
+    kind: 'ready';
+    frame: EditorFrame;
+} | {
+    kind: 'failed';
+    revision: Revision;
+    message: string;
+    diagnostics: readonly PreviewDiagnostic[];
+    previous: EditorFrame | null;
+};
+export interface EditorState {
+    readonly revision: Revision;
+    readonly dirty: boolean;
+    readonly selection: Selection | null;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    readonly layout: LayoutState;
+}
+export interface OpenEditorOptions {
+    source: string | Uint8Array;
+    name?: string;
+    readResource?: Read;
+    runtime?: SessionOptions;
+}
+export interface EditorSession {
+    state(): EditorState;
+    subscribe(listener: (state: EditorState) => void): () => void;
+    range(input: {
+        revision: Revision;
+        start: Anchor;
+        end: Anchor;
+    }): Promise<EditRange>;
+    apply(input: {
+        base: Revision;
+        edit: Edit;
+    }): Promise<Commit>;
+    undo(input: {
+        base: Revision;
+    }): Promise<Commit>;
+    redo(input: {
+        base: Revision;
+    }): Promise<Commit>;
+    snapshot(): Promise<SourceSnapshot>;
+    markSaved(input: {
+        revision: Revision;
+    }): Promise<void>;
+    refresh(input: {
+        base: Revision;
+        source: string | Uint8Array;
+    }): Promise<Commit>;
+    exportDocx(): Promise<Uint8Array>;
+    dispose(): void;
+}
+export type LineHit = {
+    kind: 'editable';
+    anchor: Anchor;
+    displayOffset: DisplayUtf16;
+    x: number;
+} | {
+    kind: 'atomic';
+    reason: ReadOnlyReason;
+    role?: GeneratedRole;
+    before?: Anchor;
+    after?: Anchor;
+} | {
+    kind: 'unmapped';
+};
+export declare function locateLineSource(line: TextLine, xPt: number): LineHit;
+export declare function lineCaretX(line: TextLine, anchor: Anchor): number | null;
+export declare function openEditorWith(worker: Endpoint, options: OpenEditorOptions): Promise<EditorSession>;