@artkit-ai/react 0.0.0-stage → 0.2.0

package/src/editor-session.ts

@@ -0,0 +1,260 @@
+import {
+  type Artifact,
+  ArtifactError,
+  type ArtifactRegistry,
+  applyOperations,
+  type ChangeSummary,
+  isArtifactError,
+  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;
+  /** The draft as the user sees it. */
+  artifact: Artifact;
+  /** Operations applied since `baseVersion`, in order. */
+  operations: unknown[];
+  /** True when the draft differs from the base. */
+  dirty: boolean;
+  canUndo: boolean;
+  canRedo: boolean;
+  /** 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 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;
+}
+
+interface Step {
+  artifact: Artifact;
+  operations: unknown[];
+  at: number;
+  typing: boolean;
+}
+
+export interface EmitOptions {
+  /** Continuous gestures (typing, dragging) share one undo step; discrete changes always get their own. */
+  kind?: 'typing' | 'continuous' | 'discrete';
+}
+
+type Listener = () => void;
+
+const DEFAULT_COALESCE_MS = 1000;
+const DEFAULT_MAX_UNDO = 200;
+
+/** Draft of one artifact with local undo and redo. Batches are applied in order, one at a time. */
+export class DraftSession {
+  private readonly registry: ArtifactRegistry;
+  private readonly locale: string;
+  private readonly coalesceMs: number;
+  private readonly maxUndo: number;
+  private readonly now: () => number;
+  private base: Artifact;
+  private current: Step;
+  private undoStack: Step[] = [];
+  private redoStack: Step[] = [];
+  private queue: Promise<unknown> = Promise.resolve();
+  private pending = 0;
+  private error: DraftSnapshot['error'];
+  private lint: LintIssue[];
+  private changes: ChangeSummary[] = [];
+  private snapshot: DraftSnapshot;
+  private readonly listeners = new Set<Listener>();
+  private disposed = false;
+
+  constructor(options: DraftSessionOptions) {
+    this.registry = options.registry;
+    this.locale = options.locale ?? 'en';
+    this.coalesceMs = options.coalesceMs ?? DEFAULT_COALESCE_MS;
+    this.maxUndo = options.maxUndo ?? DEFAULT_MAX_UNDO;
+    this.now = options.now ?? (() => Date.now());
+    this.base = options.artifact;
+    this.current = { artifact: options.artifact, operations: [], at: 0, typing: false };
+    this.lint = this.lintOf(options.artifact);
+    this.snapshot = this.buildSnapshot();
+  }
+
+  /** The current snapshot. Its identity changes only when the state changes. */
+  getSnapshot = (): DraftSnapshot => this.snapshot;
+
+  subscribe = (listener: Listener): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  /**
+   * 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`.
+   */
+  apply(operations: unknown[], options: EmitOptions = {}): Promise<boolean> {
+    if (operations.length === 0) return Promise.resolve(true);
+    this.pending += 1;
+    this.publish();
+    const run = this.queue.then(async () => {
+      if (this.disposed) return false;
+      const typing = options.kind === 'typing' || options.kind === 'continuous';
+      try {
+        const result = await applyOperations(this.registry, this.current.artifact, operations, {
+          locale: this.locale,
+        });
+        const next: Artifact = {
+          ...this.current.artifact,
+          formatVersion: result.formatVersion,
+          title: result.title,
+          locale: result.locale,
+          themeId: result.themeId,
+          content: result.content,
+        };
+        const now = this.now();
+        const coalesce = typing && this.current.typing && now - this.current.at <= this.coalesceMs;
+        if (!coalesce) {
+          this.undoStack.push(this.current);
+          if (this.undoStack.length > this.maxUndo) this.undoStack.shift();
+        }
+        this.redoStack = [];
+        this.current = {
+          artifact: next,
+          operations: [...this.current.operations, ...operations],
+          at: now,
+          typing,
+        };
+        this.lint = result.lint;
+        this.changes = result.diff;
+        this.error = undefined;
+        return true;
+      } catch (error) {
+        this.error = errorOf(error);
+        return false;
+      }
+    });
+    this.queue = run.finally(() => {
+      this.pending -= 1;
+      this.publish();
+    });
+    return run.then((accepted) => {
+      this.publish();
+      return accepted;
+    });
+  }
+
+  /** Steps back one edit (local). Returns false when there is nothing to undo. */
+  undo(): boolean {
+    const previous = this.undoStack.pop();
+    if (!previous) return false;
+    this.redoStack.push(this.current);
+    this.restore(previous);
+    return true;
+  }
+
+  /** Steps forward after an undo. Returns false when there is nothing to redo. */
+  redo(): boolean {
+    const next = this.redoStack.pop();
+    if (!next) return false;
+    this.undoStack.push(this.current);
+    this.restore(next);
+    return true;
+  }
+
+  /**
+   * 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.
+   */
+  load(artifact: Artifact): void {
+    if (artifact.id !== this.base.id) throw new ArtifactError('INVALID_OPERATION', 'Load the same artifact.');
+    const clean = !this.buildSnapshot().dirty;
+    const sameContent = JSON.stringify(artifact.content) === JSON.stringify(this.current.artifact.content);
+    this.base = artifact;
+    if (clean || sameContent) {
+      this.current = { artifact, operations: [], at: 0, typing: false };
+      this.undoStack = [];
+      this.redoStack = [];
+      this.lint = this.lintOf(artifact);
+      this.changes = [];
+    }
+    this.publish();
+  }
+
+  /** Stops the session: later batches are ignored and listeners are dropped. */
+  dispose(): void {
+    this.disposed = true;
+    this.listeners.clear();
+  }
+
+  private restore(step: Step): void {
+    this.current = step;
+    this.lint = this.lintOf(step.artifact);
+    this.changes = [];
+    this.error = undefined;
+    this.publish();
+  }
+
+  private lintOf(artifact: Artifact): LintIssue[] {
+    const adapter = this.registry.get(artifact.format, this.locale);
+    return adapter.lint(artifact.content as never, {
+      locale: artifact.locale,
+      theme: this.registry.theme(artifact.themeId, this.locale),
+    });
+  }
+
+  private publish(): void {
+    this.snapshot = this.buildSnapshot();
+    for (const listener of this.listeners) listener();
+  }
+
+  private buildSnapshot(): DraftSnapshot {
+    const dirty =
+      this.current.operations.length > 0 ||
+      JSON.stringify(this.current.artifact.content) !== JSON.stringify(this.base.content) ||
+      this.current.artifact.title !== this.base.title;
+    return {
+      baseVersion: this.base.version,
+      artifact: this.current.artifact,
+      operations: this.current.operations,
+      dirty,
+      canUndo: this.undoStack.length > 0,
+      canRedo: this.redoStack.length > 0,
+      pending: this.pending > 0,
+      ...(this.error ? { error: this.error } : {}),
+      lint: this.lint,
+      changes: this.changes,
+    };
+  }
+}
+
+function errorOf(error: unknown): NonNullable<DraftSnapshot['error']> {
+  if (isArtifactError(error)) {
+    const payload = error.toPayload();
+    return {
+      code: payload.error.code,
+      message: payload.error.message,
+      issues: payload.error.issues ?? [],
+    };
+  }
+  return {
+    code: 'INTERNAL_ERROR',
+    message: error instanceof Error ? error.message : String(error),
+    issues: [],
+  };
+}

package/src/hooks.ts

@@ -0,0 +1,296 @@
+import {
+  type AnyArtifactExporter,
+  type Artifact,
+  ArtifactError,
+  type CommitResult,
+  isArtifactError,
+  silentLogger,
+  slugify,
+} from '@artkit-ai/core';
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import type { CacheEntry } from './cache.js';
+import type { ClientExportResult } from './client.js';
+import { useArtkit } from './context.js';
+import { triggerDownload } from './download.js';
+
+const NO_ENTRY: CacheEntry = Object.freeze({ loading: false }) as CacheEntry;
+const noop = () => {};
+const noSubscription = () => noop;
+
+function toArtifactError(error: unknown): ArtifactError {
+  if (isArtifactError(error)) return error;
+  return new ArtifactError('INTERNAL_ERROR', 'Internal error while processing the request.', {
+    cause: error,
+  });
+}
+
+export interface UseArtifactOptions {
+  /** Already-known artifact (e.g. from a chat message), shown immediately and cached. */
+  initial?: Artifact;
+  /** Revalidate the latest version on mount (default true). */
+  revalidate?: boolean;
+}
+
+export interface UseArtifactResult {
+  artifact: Artifact | undefined;
+  error: unknown;
+  loading: boolean;
+  /** Fetches the latest version again (specific versions never change). */
+  refresh(): Promise<Artifact | undefined>;
+}
+
+/** Loads an artifact through the client with a shared cache (spec §13.2). Pass undefined to skip. */
+export function useArtifact(id: string | undefined, options: UseArtifactOptions = {}): UseArtifactResult {
+  const { cache } = useArtkit();
+  const { initial, revalidate = true } = options;
+  const subscribe = useCallback(
+    (listener: () => void) => (id ? cache.subscribe(id, listener) : noop),
+    [cache, id],
+  );
+  const read = () => (id ? cache.entry(id) : NO_ENTRY);
+  const entry = useSyncExternalStore(id ? subscribe : noSubscription, read, read);
+
+  useEffect(() => {
+    if (initial && initial.id === id) cache.put(initial);
+  }, [cache, id, initial]);
+
+  useEffect(() => {
+    if (!id) return;
+    cache.load(id, revalidate).catch(noop);
+  }, [cache, id, revalidate]);
+
+  const usableInitial = initial && initial.id === id ? initial : undefined;
+  const artifact =
+    entry.artifact && (!usableInitial || entry.artifact.version >= usableInitial.version)
+      ? entry.artifact
+      : (usableInitial ?? entry.artifact);
+  const refresh = useCallback(async () => {
+    if (!id) return undefined;
+    return cache.load(id, true);
+  }, [cache, id]);
+
+  return {
+    artifact,
+    error: artifact ? undefined : entry.error,
+    loading: !artifact && !entry.error && id !== undefined,
+    refresh,
+  };
+}
+
+/** Latest known version of an artifact in the cache, updated when commits arrive. */
+export function useLatestVersion(id: string | undefined): number | undefined {
+  const { cache } = useArtkit();
+  const subscribe = useCallback(
+    (listener: () => void) => (id ? cache.subscribe(id, listener) : noop),
+    [cache, id],
+  );
+  const read = () => (id ? cache.latest(id)?.version : undefined);
+  return useSyncExternalStore(subscribe, read, read);
+}
+
+export interface ApplyConflict {
+  operations: unknown[];
+  baseVersion: number;
+  currentVersion?: number;
+}
+
+export interface ApplyOptions {
+  /** Defaults to the latest cached version (loaded when unknown). */
+  baseVersion?: number;
+}
+
+export interface UseApplyOperationsResult {
+  apply(operations: unknown[], options?: ApplyOptions): Promise<CommitResult>;
+  pending: boolean;
+  error: ArtifactError | undefined;
+  /** Set on VERSION_CONFLICT: what changed since the base, and the operations that were refused. */
+  conflict: ApplyConflict | undefined;
+  /** Sends the refused operations again on the latest version. */
+  retry(): Promise<CommitResult>;
+  reset(): void;
+}
+
+/** Sends operations with `baseVersion` and surfaces conflicts (spec §13.2). */
+export function useApplyOperations(id: string): UseApplyOperationsResult {
+  const { client, cache } = useArtkit();
+  const [state, setState] = useState<{ pending: boolean; error?: ArtifactError; conflict?: ApplyConflict }>({
+    pending: false,
+  });
+  const conflictRef = useRef<ApplyConflict | undefined>(undefined);
+
+  const apply = useCallback(
+    async (operations: unknown[], options: ApplyOptions = {}) => {
+      setState({ pending: true });
+      let baseVersion = options.baseVersion;
+      try {
+        baseVersion ??= cache.latest(id)?.version ?? (await cache.load(id)).version;
+        const result = await client.apply(id, { baseVersion, operations });
+        cache.put(result.artifact);
+        conflictRef.current = undefined;
+        setState({ pending: false });
+        return result;
+      } catch (caught) {
+        const error = toArtifactError(caught);
+        let conflict: ApplyConflict | undefined;
+        if (error.code === 'VERSION_CONFLICT') {
+          const current = error.details.currentVersion;
+          conflict = {
+            operations,
+            baseVersion: baseVersion ?? 0,
+            ...(typeof current === 'number' ? { currentVersion: current } : {}),
+          };
+          cache.load(id, true).catch(noop);
+        }
+        conflictRef.current = conflict;
+        setState({ pending: false, error, ...(conflict ? { conflict } : {}) });
+        throw error;
+      }
+    },
+    [client, cache, id],
+  );
+
+  const retry = useCallback(async () => {
+    const conflict = conflictRef.current;
+    if (!conflict) throw new ArtifactError('NOT_FOUND', 'There is no conflicting batch to retry.');
+    const latest = await cache.load(id, true);
+    return apply(conflict.operations, { baseVersion: latest.version });
+  }, [apply, cache, id]);
+
+  const reset = useCallback(() => {
+    conflictRef.current = undefined;
+    setState({ pending: false });
+  }, []);
+
+  return { apply, pending: state.pending, error: state.error, conflict: state.conflict, retry, reset };
+}
+
+export interface ExportOptions {
+  /** Triggers a browser download (default true). */
+  download?: boolean;
+  options?: Record<string, unknown>;
+  /** `auto` (default) exports in the browser when a browser-capable exporter is loaded. */
+  prefer?: 'auto' | 'browser' | 'server';
+  signal?: AbortSignal;
+}
+
+export interface UseArtifactExportResult {
+  exportArtifact(format: string, options?: ExportOptions): Promise<ClientExportResult>;
+  pending: string | undefined;
+  error: ArtifactError | undefined;
+  warnings: string[];
+  /** Formats available for the artifact's kind (server formats plus browser exporters). */
+  formats: string[];
+  /** Loads the kind's browser exporters so `formats` includes them. */
+  loadFormats(): Promise<void>;
+}
+
+/**
+ * Exports in the browser when a loaded exporter with runtime `any`/`browser` handles the format, else
+ * through the client (spec §13.2), and triggers a download.
+ */
+export function useArtifactExport(id: string, format?: string): UseArtifactExportResult {
+  const ctx = useArtkit();
+  const { client, cache, registry } = ctx;
+  const [pending, setPending] = useState<string | undefined>(undefined);
+  const [error, setError] = useState<ArtifactError | undefined>(undefined);
+  const [warnings, setWarnings] = useState<string[]>([]);
+  const [loaded, setLoaded] = useState<AnyArtifactExporter[]>([]);
+  const knownFormat = format ?? cache.latest(id)?.format;
+
+  const browserExporters = useCallback(
+    async (artifactKind: string): Promise<AnyArtifactExporter[]> => {
+      const fromRegistry = registry.exporters(artifactKind).filter((exporter) => exporter.runtime !== 'node');
+      if (!ctx.hasExporters(artifactKind)) return fromRegistry;
+      const lazy = (await ctx.loadExporters(artifactKind)).filter(
+        (exporter) => exporter.format === artifactKind && exporter.runtime !== 'node',
+      );
+      return [...lazy, ...fromRegistry];
+    },
+    [ctx, registry],
+  );
+
+  const loadFormats = useCallback(async () => {
+    if (!knownFormat) return;
+    try {
+      setLoaded(await browserExporters(knownFormat));
+    } catch {
+      // Without browser exporters the server formats still work.
+    }
+  }, [browserExporters, knownFormat]);
+
+  const formats = useMemo(() => {
+    if (!knownFormat) return [];
+    const set = new Set<string>(ctx.exportFormats[knownFormat] ?? []);
+    for (const exporter of registry.exporters(knownFormat))
+      if (exporter.runtime !== 'node') set.add(exporter.target);
+    for (const exporter of loaded) set.add(exporter.target);
+    return [...set];
+  }, [ctx.exportFormats, knownFormat, loaded, registry]);
+
+  const exportArtifact = useCallback(
+    async (format: string, options: ExportOptions = {}) => {
+      setPending(format);
+      setError(undefined);
+      setWarnings([]);
+      try {
+        const artifact = cache.latest(id) ?? (await cache.load(id));
+        let result: ClientExportResult | undefined;
+        if (options.prefer !== 'server') {
+          const exporter = (await browserExporters(artifact.format).catch(() => [])).find(
+            (candidate) => candidate.target === format,
+          );
+          if (exporter) {
+            const collected: string[] = [];
+            let bytes: Uint8Array;
+            try {
+              bytes = await exporter.export(artifact.content, {
+                title: artifact.title,
+                theme: ctx.themeFor(artifact.themeId),
+                locale: artifact.locale,
+                assets: ctx.assets ?? {
+                  resolve: (ref) =>
+                    Promise.reject(
+                      new ArtifactError('NOT_FOUND', `Asset not available in the browser: ${ref}.`),
+                    ),
+                },
+                logger: silentLogger,
+                warn: (message) => collected.push(message),
+                ...(options.signal ? { signal: options.signal } : {}),
+                ...(options.options ? { options: options.options } : {}),
+              });
+            } catch (cause) {
+              throw isArtifactError(cause)
+                ? cause
+                : new ArtifactError('EXPORT_FAILED', `Failed to export to ${format}.`, { cause });
+            }
+            result = {
+              bytes,
+              mimeType: exporter.mimeType,
+              filename: `${slugify(artifact.title)}.${exporter.extension}`,
+              warnings: collected,
+            };
+          } else if (options.prefer === 'browser') {
+            throw new ArtifactError('EXPORT_FAILED', `No browser exporter for format ${format}.`);
+          }
+        }
+        result ??= await client.export(id, {
+          format,
+          ...(options.options ? { options: options.options } : {}),
+          ...(options.signal ? { signal: options.signal } : {}),
+        });
+        setWarnings(result.warnings);
+        if (options.download !== false) triggerDownload(result);
+        return result;
+      } catch (caught) {
+        const failure = toArtifactError(caught);
+        setError(failure);
+        throw failure;
+      } finally {
+        setPending(undefined);
+      }
+    },
+    [browserExporters, cache, client, ctx, id],
+  );
+
+  return { exportArtifact, pending, error, warnings, formats, loadFormats };
+}