@pointyink/rogue 0.1.1 → 0.2.0

package/types/suggestions.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @typedef {{ id: string, author_id: string, start_id: string, end_id: string,
+ *   replacement: string, status: string, created_at: string, updated_at: string }} Suggestion
+ * @typedef {Suggestion & { range: import('./comments.js').DomRange | null }} ResolvedSuggestion
+ */
+/**
+ * Resolve a suggestion's node-id anchor to a live DOM range with fencepost
+ * semantics. Unlike comments, a suggestion brackets a *region*: if a boundary
+ * char is edited away, the range steps inward to the nearest surviving visible
+ * node (next_vis for the left edge, prev_vis for the right) rather than going
+ * stale. Null only when the region between the ids has fully collapsed.
+ *
+ * @param {import('./comments.js').CrdtSurface} crdt
+ * @param {import('./comments.js').RopeSurface} rope
+ * @param {string} startId @param {string} endId
+ * @returns {import('./comments.js').DomRange | null}
+ */
+export function resolveSuggestionAnchor(crdt: import("./comments.js").CrdtSurface, rope: import("./comments.js").RopeSurface, startId: string, endId: string): import("./comments.js").DomRange | null;
+/**
+ * @typedef {{
+ *   crdt: import('./comments.js').CrdtSurface,
+ *   rope: import('./comments.js').RopeSurface,
+ *   baseUrl: string,
+ *   fetchFn?: import('./comments.js').CommentsFetcher,
+ *   rerender?: (suggestions: ResolvedSuggestion[]) => void,
+ *   onError?: (error: Error) => void,
+ *   markUserEdit?: () => void,
+ *   getSelectionRange?: () => import('./comments.js').DomRange | null,
+ * }} SuggestionsOptions
+ */
+/**
+ * @typedef {{
+ *   load: () => Promise<ResolvedSuggestion[]>,
+ *   suggestions: () => ResolvedSuggestion[],
+ *   create: (replacement: string) => Promise<void>,
+ *   accept: (suggestionId: string) => Promise<void>,
+ *   reject: (suggestionId: string) => Promise<void>,
+ *   handleDocumentChange: (range: { minIx: number, maxIx: number } | null) => void,
+ *   handleRemoteChange: () => Promise<ResolvedSuggestion[]>,
+ *   destroy: () => void,
+ * }} Suggestions
+ */
+/**
+ * @param {SuggestionsOptions} options
+ * @returns {Suggestions}
+ */
+export function createSuggestions({ crdt, rope, baseUrl, fetchFn, rerender, onError, markUserEdit, getSelectionRange }: SuggestionsOptions): Suggestions;
+export type Suggestion = {
+    id: string;
+    author_id: string;
+    start_id: string;
+    end_id: string;
+    replacement: string;
+    status: string;
+    created_at: string;
+    updated_at: string;
+};
+export type ResolvedSuggestion = Suggestion & {
+    range: import("./comments.js").DomRange | null;
+};
+export type SuggestionsOptions = {
+    crdt: import("./comments.js").CrdtSurface;
+    rope: import("./comments.js").RopeSurface;
+    baseUrl: string;
+    fetchFn?: import("./comments.js").CommentsFetcher;
+    rerender?: (suggestions: ResolvedSuggestion[]) => void;
+    onError?: (error: Error) => void;
+    markUserEdit?: () => void;
+    getSelectionRange?: () => import("./comments.js").DomRange | null;
+};
+export type Suggestions = {
+    load: () => Promise<ResolvedSuggestion[]>;
+    suggestions: () => ResolvedSuggestion[];
+    create: (replacement: string) => Promise<void>;
+    accept: (suggestionId: string) => Promise<void>;
+    reject: (suggestionId: string) => Promise<void>;
+    handleDocumentChange: (range: {
+        minIx: number;
+        maxIx: number;
+    } | null) => void;
+    handleRemoteChange: () => Promise<ResolvedSuggestion[]>;
+    destroy: () => void;
+};

package/types/sync-client.d.ts

@@ -2,7 +2,7 @@
  * @param {SyncClientOptions} options
  * @returns {SyncClient}
  */
-export function createSyncClient({ wsUrl, docId, mergeOp, getToken, onStatus, onReady }: SyncClientOptions): SyncClient;
+export function createSyncClient({ wsUrl, docId, mergeOp, getToken, onStatus, onReady, onSyncStart, onProgress, onCommentChanged, onSuggestionChanged, onDocDeleted }: SyncClientOptions): SyncClient;
 export type SyncStatus = "connecting" | "connected" | "disconnected";
 export type SyncClientOptions = {
     wsUrl: string;
@@ -11,9 +11,21 @@ export type SyncClientOptions = {
     getToken: () => Promise<string>;
     onStatus?: (status: SyncStatus) => void;
     onReady?: () => void;
+    onSyncStart?: (bytes: number) => void;
+    onProgress?: (progress: number) => void;
+    onCommentChanged?: (info: {
+        comment_id: string;
+        op: string;
+    }) => void;
+    onSuggestionChanged?: (info: {
+        suggestion_id: string;
+        op: string;
+    }) => void;
+    onDocDeleted?: (docId: string) => void;
 };
 export type SyncClient = {
     send: (payload: Uint8Array) => void;
+    sendDelete: () => void;
     destroy: () => void;
     isReady: () => boolean;
 };

package/types/sync.d.ts

@@ -1,16 +1,15 @@
 /**
- * Whether an HTML string round-trips through the browser parser unchanged.
- * Parsed in an inert <template> (fragment semantics), so context-sensitive
- * fragments (<td>, <tr>, <li>) survive where a <div> would drop them — a
- * nested/unbalanced tag still comes back different and is caught. Raw innerHTML
- * is used instead of the rope+scrub serialization because the CRDT render is
- * already clean (scrubbed + escaped), so the two agree, and the template
- * round-trip is much cheaper than rebuilding a rope. Exported for direct tests.
+ * Whether an HTML string survives a browser-parse round-trip unchanged. `context`
+ * is an element whose *tag* supplies the parse context — pass the region's parent
+ * so `<td>`/`<tr>`/`<li>` parse in their real context (a bare `<div>` would drop
+ * table internals). Omitted → a bare `<div>`. Raw innerHTML is used (not the
+ * rope+scrub serialization) because the CRDT render is already clean (scrubbed +
+ * escaped). Exported for direct tests.
  * @param {string} html
- * @param {Document} [doc]
+ * @param {Element} [context]
  * @returns {boolean}
  */
-export function roundTrips(html: string, doc?: Document): boolean;
+export function validHtml(html: string, context?: Element): boolean;
 /**
  * The vis-index span a reference node contributes to a scoped-sync range, robust
  * to the DOM churning mid-batch (see localRegion):
@@ -44,6 +43,29 @@ export function nodeSpan(rope: NonNullable<ReturnType<typeof buildRope>>, node:
  *   undo, presence, and cursor attribution key off it — or to coordinate ids
  *   server-side so concurrent replicas never collide (the u16 space is ~65k).
  * @property {(payload: Uint8Array) => void} [onCommit]
+ * @property {number} [maxOpBytes = 8388608] Hard cap on a single committed op
+ *   batch (one edit = one wire frame). An edit whose inserts exceed this is
+ *   rejected — `onOpTooLarge` fires and the DOM is reverted to the CRDT — so a
+ *   pathological paste (or programmatic insert) can't blow the server's read
+ *   limit. The server (WS_MAX_MESSAGE_SIZE) remains the precise backstop; this
+ *   guard is the friendly first line for any host, whether or not it uses the
+ *   engine's own paste listener.
+ * @property {(bytes: number, limit: number) => void} [onOpTooLarge] Called when
+ *   an edit is rejected for exceeding `maxOpBytes`.
+ * @property {() => void} [onDocTooLarge] Called when an edit can't be applied
+ *   because the document has reached its storage capacity. The edit is reverted
+ *   (the CRDT is left untouched).
+ * @property {(error: import('./crdt_error.js').CrdtError) => void} [onError]
+ *   Called when an operation fails for a reason other than the known limits
+ *   above — receives the structured error the WASM wrote into its output buffer
+ *   (`{ type, name, desc? }`, see CrdtErrorKind), so a host can log or toast it.
+ *   `out_of_memory` on the local commit path continues to route through
+ *   `onDocTooLarge`.
+ * @property {(range: { minIx: number, maxIx: number } | null) => void} [onChange]
+ *   Called after the document's visible text changes (local edits, remote ops,
+ *   undo/redo) with the affected vis-index range, or null when it can't be
+ *   localized. Internal to the rogue layer — comments.js uses it to re-resolve
+ *   anchored ranges; hosts generally don't need it.
  * @property {false | { maxBytes?: number, onRejected?: (bytes: number, limit: number) => void }} [paste]
  *   Paste handling. `false` skips the engine's own paste listener — hosts like
  *   TinyMCE have their own paste-clean pipeline, so running both would double-insert.
@@ -76,6 +98,9 @@ export function nodeSpan(rope: NonNullable<ReturnType<typeof buildRope>>, node:
  *   drainParked: () => void,
  *   setSyncDebug: (on: boolean) => void,
  *   markUserEdit: () => void,
+ *   reserve: (nodes: number) => void,
+ *   crdt: import('./comments.js').CrdtSurface,
+ *   rope: import('./dom_rope.js').DomRope,
  *   destroy: () => void,
  * }} RogueNode
  */
@@ -83,7 +108,7 @@ export function nodeSpan(rope: NonNullable<ReturnType<typeof buildRope>>, node:
  * @param {RogueNodeOptions} options
  * @returns {Promise<RogueNode>}
  */
-export function createRogueNode({ element: editorRoot, replicaId, onCommit, paste, doc, win, serializeNode, omitNode, unwrapNode, }: RogueNodeOptions): Promise<RogueNode>;
+export function createRogueNode({ element: editorRoot, replicaId, onCommit, maxOpBytes, onOpTooLarge, onDocTooLarge, onError, onChange, paste, doc, win, serializeNode, omitNode, unwrapNode, }: RogueNodeOptions): Promise<RogueNode>;
 export type RogueNodeOptions = {
     /**
      * The container the engine renders into and
@@ -101,6 +126,45 @@ export type RogueNodeOptions = {
      */
     replicaId?: number | undefined;
     onCommit?: ((payload: Uint8Array) => void) | undefined;
+    /**
+     * Hard cap on a single committed op
+     * batch (one edit = one wire frame). An edit whose inserts exceed this is
+     * rejected — `onOpTooLarge` fires and the DOM is reverted to the CRDT — so a
+     * pathological paste (or programmatic insert) can't blow the server's read
+     * limit. The server (WS_MAX_MESSAGE_SIZE) remains the precise backstop; this
+     * guard is the friendly first line for any host, whether or not it uses the
+     * engine's own paste listener.
+     */
+    maxOpBytes?: number | undefined;
+    /**
+     * Called when
+     * an edit is rejected for exceeding `maxOpBytes`.
+     */
+    onOpTooLarge?: ((bytes: number, limit: number) => void) | undefined;
+    /**
+     * Called when an edit can't be applied
+     * because the document has reached its storage capacity. The edit is reverted
+     * (the CRDT is left untouched).
+     */
+    onDocTooLarge?: (() => void) | undefined;
+    /**
+     * Called when an operation fails for a reason other than the known limits
+     * above — receives the structured error the WASM wrote into its output buffer
+     * (`{ type, name, desc? }`, see CrdtErrorKind), so a host can log or toast it.
+     * `out_of_memory` on the local commit path continues to route through
+     * `onDocTooLarge`.
+     */
+    onError?: ((error: import("./crdt_error.js").CrdtError) => void) | undefined;
+    /**
+     * Called after the document's visible text changes (local edits, remote ops,
+     * undo/redo) with the affected vis-index range, or null when it can't be
+     * localized. Internal to the rogue layer — comments.js uses it to re-resolve
+     * anchored ranges; hosts generally don't need it.
+     */
+    onChange?: ((range: {
+        minIx: number;
+        maxIx: number;
+    } | null) => void) | undefined;
     /**
      * Paste handling. `false` skips the engine's own paste listener — hosts like
      * TinyMCE have their own paste-clean pipeline, so running both would double-insert.
@@ -149,6 +213,9 @@ export type RogueNode = {
     drainParked: () => void;
     setSyncDebug: (on: boolean) => void;
     markUserEdit: () => void;
+    reserve: (nodes: number) => void;
+    crdt: import("./comments.js").CrdtSurface;
+    rope: import("./dom_rope.js").DomRope;
     destroy: () => void;
 };
 import { buildRope } from "./dom_rope.js";