@artkit-ai/react 0.1.0 → 0.2.0

package/dist/editor-session.d.ts

@@ -1,184 +1,96 @@
-import { type Artifact, ArtifactError, type ArtifactRegistry, type ChangeSummary, type CommitResult, type EmitOptions } from '@artkit-ai/core';
-/** The editable part of an artifact: content plus the envelope fields operations can change. */
-export interface EnvelopeState {
-    content: unknown;
-    title: string;
-    themeId: string;
-    locale: string;
-}
-export interface SendRequest {
+import { type Artifact, type ArtifactRegistry, type ChangeSummary, type LintIssue } from '@artkit-ai/core';
+/**
+ * Local draft of one artifact (spec §11.6). The editor never talks to the server while the user edits: every batch is
+ * applied here, with the same pure engine as the server (`applyOperations`), and kept until the application saves.
+ * Saving is the application's decision: the editor emits the draft and the application persists it (or not).
+ */
+export interface DraftSnapshot {
+    /** Version of the artifact the draft started from (the last one the application loaded or saved). */
     baseVersion: number;
-    operations: unknown[];
-    idempotencyKey: string;
-}
-export interface EditorSessionOptions {
-    registry: ArtifactRegistry;
-    /** Last confirmed version. */
+    /** The draft as the user sees it. */
     artifact: Artifact;
-    /** Commits a batch (usually `client.apply`). */
-    send(request: SendRequest): Promise<CommitResult>;
-    /** Loads the latest version, or a specific one, after a conflict or a rebased commit. */
-    load(version?: number): Promise<Artifact>;
-    /** Typing operations emitted within this window become one batch (default 600 ms). */
-    groupingWindowMs?: number;
-    /** Upper bound for one typing batch while the user keeps typing (default 5 s). */
-    maxGroupingMs?: number;
-    /** Undo entries kept (default 100). */
-    maxUndo?: number;
-    /** Locale of error messages produced locally. */
-    locale?: string;
-    createKey?(): string;
-    onCommitted?(result: CommitResult): void;
-}
-export type SessionStatus = 'idle' | 'editing' | 'saving' | 'conflict';
-export interface SessionConflict {
-    /**
-     * `server`: the server answered VERSION_CONFLICT; `rebase`: a newer version arrived and the pending
-     * operations no longer apply on it; `undo`/`redo`: the artifact changed after the edit being undone.
-     */
-    reason: 'server' | 'rebase' | 'undo' | 'redo';
-    /** What changed in the newer version, for the conflict diff. */
-    changes: ChangeSummary[];
-    /** The local operations that would be reapplied. */
+    /** Operations applied since `baseVersion`, in order. */
     operations: unknown[];
-    latest: Artifact;
-}
-export type SessionEvent = {
-    type: 'saved';
-    version: number;
-} | {
-    type: 'undone';
-    version: number;
-} | {
-    type: 'redone';
-    version: number;
-} | {
-    type: 'rebased';
-    version: number;
-} | {
-    type: 'rejected';
-    error: ArtifactError;
-} | {
-    type: 'rolled_back';
-    error: ArtifactError;
-} | {
-    type: 'conflict';
-    reason: SessionConflict['reason'];
-} | {
-    type: 'conflict_resolved';
-    choice: ConflictChoice;
-};
-export type ConflictChoice = 'keep-theirs' | 'reapply';
-export interface EditorSessionState {
-    confirmed: Artifact;
-    /** Optimistic state: confirmed version plus every unconfirmed local operation. */
-    view: EnvelopeState;
-    status: SessionStatus;
-    /** Local operations not confirmed yet (buffered, queued or in flight). */
+    /** True when the draft differs from the base. */
     dirty: boolean;
     canUndo: boolean;
     canRedo: boolean;
-    error?: ArtifactError;
-    conflict?: SessionConflict;
-    /** Set after a LOCKED rejection; editing stays disabled until then. */
-    lockedUntil?: string;
-    /** Last notable event, with a sequence number so hosts can announce each one once. */
-    event?: SessionEvent & {
-        seq: number;
+    /** An edit is being applied. */
+    pending: boolean;
+    /** Last rejected batch, cleared by the next accepted one. */
+    error?: {
+        code: string;
+        message: string;
+        issues: {
+            path: string;
+            message: string;
+            hint?: string;
+        }[];
     };
+    /** Lint issues of the draft. */
+    lint: LintIssue[];
+    /** Changes of the last accepted batch. */
+    changes: ChangeSummary[];
 }
-export declare function envelopeOf(artifact: Pick<Artifact, 'content' | 'title' | 'themeId' | 'locale'>): EnvelopeState;
-/**
- * Operations that turn `from` into `to`. Kinds do not provide inverse operations, so undo and redo send
- * `replace_content` with the snapshot (plus envelope operations); the commit still becomes a new version
- * (spec §8.5).
- */
-export declare function operationsBetween(from: EnvelopeState, to: EnvelopeState): unknown[];
-/**
- * Framework-free editing session behind `ArtifactEditor` (spec §13.6): batching of typing operations,
- * optimistic apply with the kind's own logic, rollback on rejection, local undo/redo over the user's own
- * batches, rebase of pending operations on newer versions, conflict resolution and lock handling.
- *
- * Batches are sent one at a time, each against the version the previous one produced.
- */
-export declare class EditorSession {
-    private readonly options;
-    private readonly windowMs;
-    private readonly maxGroupingMs;
+export interface DraftSessionOptions {
+    registry: ArtifactRegistry;
+    artifact: Artifact;
+    /** Locale of the model-facing messages produced by the engine (pt-BR or en). */
+    locale?: string;
+    /** Times within which consecutive typing batches share one undo step. */
+    coalesceMs?: number;
+    /** Undo steps kept in memory. */
+    maxUndo?: number;
+    now?: () => number;
+}
+export interface EmitOptions {
+    /** Continuous gestures (typing, dragging) share one undo step; discrete changes always get their own. */
+    kind?: 'typing' | 'continuous' | 'discrete';
+}
+type Listener = () => void;
+/** Draft of one artifact with local undo and redo. Batches are applied in order, one at a time. */
+export declare class DraftSession {
+    private readonly registry;
+    private readonly locale;
+    private readonly coalesceMs;
     private readonly maxUndo;
-    private confirmed;
-    private view;
-    private buffer;
-    private bufferStartedAt;
-    private timer;
-    private lockTimer;
-    private queue;
-    private inflight;
+    private readonly now;
+    private base;
+    private current;
     private undoStack;
     private redoStack;
+    private queue;
+    private pending;
     private error;
-    private conflict;
-    private lockedUntil;
-    private deferredRemote;
-    private event;
-    private seq;
-    private disposed;
-    private readonly listeners;
-    private idleWaiters;
+    private lint;
+    private changes;
     private snapshot;
-    constructor(options: EditorSessionOptions);
-    subscribe: (listener: () => void) => (() => void);
-    getSnapshot: () => EditorSessionState;
-    /** Resolves once nothing is buffered, queued or in flight (or a conflict is waiting for the user). */
-    whenIdle(): Promise<void>;
-    private isIdle;
-    private buildSnapshot;
-    private notify;
-    private announce;
-    private isLocked;
-    private applyLocal;
-    private pendingOperations;
-    /**
-     * Recomputes the optimistic view from the confirmed version. When the unconfirmed operations no
-     * longer apply, they move into a `rebase` conflict and the view falls back to the confirmed version.
-     */
-    private rebaseView;
-    private changesBetween;
-    /**
-     * Called by the kind editor. Operations are applied optimistically right away; invalid ones are
-     * rejected locally (returns false) and never reach the server.
-     */
-    emit: (operations: unknown[], options?: EmitOptions) => boolean;
-    /** Sends buffered typing operations now (e.g. on blur or before navigation). */
-    flush(): void;
-    private key;
-    private schedule;
-    private clearTimer;
-    private flushBuffer;
-    undo: () => void;
-    redo: () => void;
-    dismissError: () => void;
-    private pump;
-    private resolveHistoryCommand;
-    private onCommitted;
-    /** Incorporates a version that arrived while a request was in flight. */
-    private applyDeferred;
-    private pushUndo;
-    private onRejected;
-    private setLocked;
+    private readonly listeners;
+    private disposed;
+    constructor(options: DraftSessionOptions);
+    /** The current snapshot. Its identity changes only when the state changes. */
+    getSnapshot: () => DraftSnapshot;
+    subscribe: (listener: Listener) => (() => void);
     /**
-     * A version arrived from outside the session (refetch, agent commit, prop). Pending local operations
-     * are rebased on it; when they no longer apply, a `rebase` conflict asks the user what to keep.
+     * Applies a batch to the draft. Resolves to `true` when the batch was accepted. A rejected batch leaves the draft
+     * untouched and sets `snapshot.error`.
      */
-    receive: (artifact: Artifact) => void;
-    private incorporate;
-    resolveConflict: (choice: ConflictChoice) => void;
+    apply(operations: unknown[], options?: EmitOptions): Promise<boolean>;
+    /** Steps back one edit (local). Returns false when there is nothing to undo. */
+    undo(): boolean;
+    /** Steps forward after an undo. Returns false when there is nothing to redo. */
+    redo(): boolean;
     /**
-     * Stops timers and listeners. Buffered typing is still sent unless `discard` is set, so closing the
-     * editor right after typing does not lose the last keystrokes.
+     * Adopts an artifact loaded or saved by the application. A clean draft follows the new artifact. A draft that has
+     * changes keeps its content, and the base moves to the new version so the next save is a complete one.
      */
-    dispose(options?: {
-        discard?: boolean;
-    }): void;
+    load(artifact: Artifact): void;
+    /** Stops the session: later batches are ignored and listeners are dropped. */
+    dispose(): void;
+    private restore;
+    private lintOf;
+    private publish;
+    private buildSnapshot;
 }
+export {};
 //# sourceMappingURL=editor-session.d.ts.map

package/dist/editor-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"editor-session.d.ts","sourceRoot":"","sources":["../src/editor-session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"editor-session.d.ts","sourceRoot":"","sources":["../src/editor-session.ts"],"names":[],"mappings":"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"}