@arbidocs/react 0.4.8 → 0.4.10

package/dist/artifacts/index.d.cts

@@ -1,7 +1,9 @@
 import { RedlineWithRegions, RedlineRegion } from './redline-core.cjs';
 export { RegionKind, buildHybridRedlineMarkdown, buildHybridRedlineWithRegions, revertRedlineRegion } from './redline-core.cjs';
 import * as _tanstack_react_query from '@tanstack/react-query';
+export { c as cleanDraftMarkdown, p as promoteBoldTitle, r as repairParsedTitle, s as stripAgentPreamble, u as unescapeMarkdown, a as unwrapCitationLinks } from '../stored-markdown-DMwFzWhc.cjs';
 import { FC, ComponentPropsWithoutRef, ReactNode } from 'react';
+import { ArtifactEvent } from '@arbidocs/sdk/browser';
 
 /**
  * Where a redline is computed. The default runs on the calling thread; a host with large
@@ -87,10 +89,19 @@ declare function toArtifactVersions(chain: readonly VersionedDoc[]): ArtifactVer
  * (the lineage is just this document, or it is unknown), so unversioned documents stay unlabelled.
  */
 declare function versionLabel(versions: readonly ArtifactVersion[], docId: string | null | undefined): string | null;
-/** Join parsed chunks into one markdown text (blank line between chunks). */
+/**
+ * Join parsed chunks into one markdown text (blank line between chunks).
+ *
+ * `unescape: true` for an artifact stored from markdown: the backend's parse of a `.md` escapes
+ * markdown punctuation, which `unescapeMarkdown` undoes (see its rule), and mangles its title
+ * (`repairParsedTitle`). Leave it off for the parse
+ * of a PDF or Word file.
+ */
 declare function flattenChunks(chunks: readonly {
     content?: string | null;
-}[] | null | undefined): string;
+}[] | null | undefined, options?: {
+    unescape?: boolean;
+}): string;
 /** Is `id` a real, saved document id? Local drafts have placeholder ids and no backend document. */
 declare function isDocumentId(id: string | null | undefined): id is string;
 
@@ -173,13 +184,56 @@ interface ArtifactEditSession {
  */
 declare function useArtifactEditSession(options: ArtifactEditSessionOptions): ArtifactEditSession;
 
-/** The saved markdown of a document (its parsed chunks, joined). */
-declare function useArtifactText(docId: string | null | undefined, options?: {
-    enabled?: boolean;
-}): {
+/**
+ * Where the text of a stored artifact is:
+ *  - `loading`: the first request is in flight (or there is no document yet);
+ *  - `parsing`: the backend has not finished parsing the upload (the endpoint answers 404, 422 or
+ *    500, or an empty parse, for a few seconds after an upload) and the hook is retrying;
+ *  - `ready`: the text is here (an empty document is `ready` with `text: null`);
+ *  - `error`: the retries ran out, or the request was refused (401/403).
+ */
+type ArtifactTextStatus = 'loading' | 'parsing' | 'ready' | 'error';
+/** How long `useArtifactText` keeps asking while a document is still being parsed. */
+interface ArtifactTextRetry {
+    /** Retries after the first request. Default 12. */
+    attempts?: number;
+    /** Delay before the first retry; it grows by 1.6x each time. Default 1000 ms. */
+    baseDelayMs?: number;
+    /** Cap for one delay. Default 5000 ms (12 retries are about 50 s in all). */
+    maxDelayMs?: number;
+}
+declare const DEFAULT_ARTIFACT_TEXT_RETRY: Required<ArtifactTextRetry>;
+interface ArtifactText {
+    /**
+     * The markdown, clean: `undefined` while `loading` or `parsing`, `null` when there is none (an
+     * empty document, or `error`).
+     */
     text: string | null | undefined;
+    /** `status` is `loading` or `parsing`. */
     isLoading: boolean;
-};
+    status: ArtifactTextStatus;
+    /** The last request error while `parsing` or after `error`. */
+    error: Error | null;
+    /** Ask again now (after an `error`). */
+    retry: () => void;
+}
+/**
+ * The saved markdown of an artifact version (its parsed chunks, joined and unescaped).
+ *
+ * A freshly uploaded document is parsed asynchronously, and for roughly 3 to 20 seconds the parsed
+ * content endpoint answers 404, 422 or 500 (or an empty parse). The hook therefore retries with a
+ * growing delay (see `ArtifactTextRetry`) and reports `status: 'parsing'` meanwhile, so a host can
+ * show "Preparing editor..." instead of opening an editor on an empty baseline. After the last
+ * retry the status is `error`; `retry()` starts a new round.
+ *
+ * The text is run through `unescapeMarkdown`: an artifact is always stored from markdown, and the
+ * backend's parse of a `.md` escapes its punctuation.
+ */
+declare function useArtifactText(docId: string | null | undefined, options?: {
+    enabled?: boolean;
+    retry?: ArtifactTextRetry;
+}): ArtifactText;
+
 /** The version lineage of an artifact in a workspace, oldest first. */
 declare function useArtifactVersions(workspaceId: string | undefined, docId: string | null | undefined): ArtifactVersion[];
 interface SaveArtifactVersionInput {
@@ -236,6 +290,13 @@ interface ArtifactSessionView {
     onCompare: () => void;
     onStopCompare: () => void;
     onToggleTrackChanges: () => void;
+    /**
+     * Whether the text is ready. `ArtifactEditor` renders "Preparing editor..." while it is
+     * `loading` or `parsing` (a fresh upload is parsed for a few seconds) and an error with Retry.
+     */
+    status: ArtifactTextStatus;
+    /** Ask for the text again after an `error`. */
+    onRetry: () => void;
 }
 interface ArtifactSession extends ArtifactEditSession {
     /** The open document: the new real id once a local draft has been saved. */
@@ -243,6 +304,8 @@ interface ArtifactSession extends ArtifactEditSession {
     /** The open version is an unsaved local draft (no backend document yet). */
     isLocal: boolean;
     isLoading: boolean;
+    /** See `ArtifactTextStatus`. */
+    status: ArtifactTextStatus;
     versions: ArtifactVersion[];
     /** "v2" for any version in the lineage. */
     labelOf: (id: string | null | undefined) => string | null;
@@ -289,4 +352,53 @@ interface ArtifactRedlineComponents {
  */
 declare function renderArtifactMarkdown(markdown: string, components?: ArtifactRedlineComponents): ReactNode;
 
-export { type ArtifactEditSession, type ArtifactEditSessionOptions, type ArtifactRedlineComponents, type ArtifactSaveResult, type ArtifactSession, type ArtifactSessionOptions, type ArtifactSessionView, type ArtifactVersion, type RedlineEngine, RedlineRegion, type RedlineState, RedlineWithRegions, type SaveArtifactVersionInput, type UseRedlineOptions, type UseRedlineResult, type VersionedDoc, buildVersionChain, flattenChunks, isDocumentId, mainThreadRedlineEngine, renderArtifactMarkdown, toArtifactVersions, useArtifactEditSession, useArtifactSession, useArtifactText, useArtifactVersions, useRedline, useSaveArtifactVersion, versionLabel };
+/**
+ * Where a drafted artifact is in its STREAM -> PERSIST -> EDIT life:
+ *  - `streaming`: the agent is still working (or has produced nothing final): show the live canvas;
+ *  - `persisting`: the finished draft is being stored as version 1 of the artifact;
+ *  - `parsing`: stored; the backend is still parsing it, so there is no editable text yet;
+ *  - `ready`: the text is readable: mount the editor on `docId`;
+ *  - `error`: storing failed or the parse never produced text (`retry()` starts over).
+ */
+type StreamedArtifactPhase = 'streaming' | 'persisting' | 'parsing' | 'ready' | 'error';
+interface UseStreamedArtifactOptions {
+    /** The artifacts of the agent run (`useConnectedAiTask().artifacts`). */
+    artifacts: ArtifactEvent[];
+    workspaceId: string | undefined;
+    /**
+     * The run has stopped: not busy and not failed. Nothing is stored before this, so a draft that
+     * is still streaming is never persisted half-written.
+     */
+    settled: boolean;
+    /** Make the stored markdown from the streamed content. Defaults to `cleanDraftMarkdown`. */
+    clean?: (streamed: string) => string;
+    /** Processing config for the stored version. */
+    configId?: string | null;
+    /** How long to wait for the parse (see `useArtifactText`). */
+    parseRetry?: ArtifactTextRetry;
+}
+interface StreamedArtifact {
+    phase: StreamedArtifactPhase;
+    /** The finished streamed artifact (its `title` names the stored versions). */
+    artifact: ArtifactEvent | undefined;
+    /** The backend document to edit, once there is one (while `parsing` and `ready`). */
+    docId: string | undefined;
+    error: Error | null;
+    /** After an `error`: store again or ask for the parse again. */
+    retry: () => void;
+}
+/**
+ * The lifecycle of an agent-drafted artifact, so a host passes the stream and renders the phase.
+ *
+ * While the agent streams, the draft lives only on the canvas. Once the run is `settled` and the
+ * draft is complete, a draft that is not yet a backend document is cleaned (`cleanDraftMarkdown`)
+ * and stored ONCE as the artifact's first version (`wpType: 'artifact'`); a draft that already is a
+ * backend document passes through. The hook then waits for the parse (`useArtifactText`, which
+ * retries) and reports `ready` with the `docId` to open in an editor.
+ *
+ * Needs an `<ArbiProvider>` and a workspace. `@arbidocs/blocks/connect` has the whole thing as a
+ * component (`StreamedArtifact`).
+ */
+declare function useStreamedArtifact({ artifacts, workspaceId, settled, clean, configId, parseRetry, }: UseStreamedArtifactOptions): StreamedArtifact;
+
+export { type ArtifactEditSession, type ArtifactEditSessionOptions, type ArtifactRedlineComponents, type ArtifactSaveResult, type ArtifactSession, type ArtifactSessionOptions, type ArtifactSessionView, type ArtifactText, type ArtifactTextRetry, type ArtifactTextStatus, type ArtifactVersion, DEFAULT_ARTIFACT_TEXT_RETRY, type RedlineEngine, RedlineRegion, type RedlineState, RedlineWithRegions, type SaveArtifactVersionInput, type StreamedArtifact, type StreamedArtifactPhase, type UseRedlineOptions, type UseRedlineResult, type UseStreamedArtifactOptions, type VersionedDoc, buildVersionChain, flattenChunks, isDocumentId, mainThreadRedlineEngine, renderArtifactMarkdown, toArtifactVersions, useArtifactEditSession, useArtifactSession, useArtifactText, useArtifactVersions, useRedline, useSaveArtifactVersion, useStreamedArtifact, versionLabel };

package/dist/artifacts/index.d.ts

@@ -1,7 +1,9 @@
 import { RedlineWithRegions, RedlineRegion } from './redline-core.js';
 export { RegionKind, buildHybridRedlineMarkdown, buildHybridRedlineWithRegions, revertRedlineRegion } from './redline-core.js';
 import * as _tanstack_react_query from '@tanstack/react-query';
+export { c as cleanDraftMarkdown, p as promoteBoldTitle, r as repairParsedTitle, s as stripAgentPreamble, u as unescapeMarkdown, a as unwrapCitationLinks } from '../stored-markdown-DMwFzWhc.js';
 import { FC, ComponentPropsWithoutRef, ReactNode } from 'react';
+import { ArtifactEvent } from '@arbidocs/sdk/browser';
 
 /**
  * Where a redline is computed. The default runs on the calling thread; a host with large
@@ -87,10 +89,19 @@ declare function toArtifactVersions(chain: readonly VersionedDoc[]): ArtifactVer
  * (the lineage is just this document, or it is unknown), so unversioned documents stay unlabelled.
  */
 declare function versionLabel(versions: readonly ArtifactVersion[], docId: string | null | undefined): string | null;
-/** Join parsed chunks into one markdown text (blank line between chunks). */
+/**
+ * Join parsed chunks into one markdown text (blank line between chunks).
+ *
+ * `unescape: true` for an artifact stored from markdown: the backend's parse of a `.md` escapes
+ * markdown punctuation, which `unescapeMarkdown` undoes (see its rule), and mangles its title
+ * (`repairParsedTitle`). Leave it off for the parse
+ * of a PDF or Word file.
+ */
 declare function flattenChunks(chunks: readonly {
     content?: string | null;
-}[] | null | undefined): string;
+}[] | null | undefined, options?: {
+    unescape?: boolean;
+}): string;
 /** Is `id` a real, saved document id? Local drafts have placeholder ids and no backend document. */
 declare function isDocumentId(id: string | null | undefined): id is string;
 
@@ -173,13 +184,56 @@ interface ArtifactEditSession {
  */
 declare function useArtifactEditSession(options: ArtifactEditSessionOptions): ArtifactEditSession;
 
-/** The saved markdown of a document (its parsed chunks, joined). */
-declare function useArtifactText(docId: string | null | undefined, options?: {
-    enabled?: boolean;
-}): {
+/**
+ * Where the text of a stored artifact is:
+ *  - `loading`: the first request is in flight (or there is no document yet);
+ *  - `parsing`: the backend has not finished parsing the upload (the endpoint answers 404, 422 or
+ *    500, or an empty parse, for a few seconds after an upload) and the hook is retrying;
+ *  - `ready`: the text is here (an empty document is `ready` with `text: null`);
+ *  - `error`: the retries ran out, or the request was refused (401/403).
+ */
+type ArtifactTextStatus = 'loading' | 'parsing' | 'ready' | 'error';
+/** How long `useArtifactText` keeps asking while a document is still being parsed. */
+interface ArtifactTextRetry {
+    /** Retries after the first request. Default 12. */
+    attempts?: number;
+    /** Delay before the first retry; it grows by 1.6x each time. Default 1000 ms. */
+    baseDelayMs?: number;
+    /** Cap for one delay. Default 5000 ms (12 retries are about 50 s in all). */
+    maxDelayMs?: number;
+}
+declare const DEFAULT_ARTIFACT_TEXT_RETRY: Required<ArtifactTextRetry>;
+interface ArtifactText {
+    /**
+     * The markdown, clean: `undefined` while `loading` or `parsing`, `null` when there is none (an
+     * empty document, or `error`).
+     */
     text: string | null | undefined;
+    /** `status` is `loading` or `parsing`. */
     isLoading: boolean;
-};
+    status: ArtifactTextStatus;
+    /** The last request error while `parsing` or after `error`. */
+    error: Error | null;
+    /** Ask again now (after an `error`). */
+    retry: () => void;
+}
+/**
+ * The saved markdown of an artifact version (its parsed chunks, joined and unescaped).
+ *
+ * A freshly uploaded document is parsed asynchronously, and for roughly 3 to 20 seconds the parsed
+ * content endpoint answers 404, 422 or 500 (or an empty parse). The hook therefore retries with a
+ * growing delay (see `ArtifactTextRetry`) and reports `status: 'parsing'` meanwhile, so a host can
+ * show "Preparing editor..." instead of opening an editor on an empty baseline. After the last
+ * retry the status is `error`; `retry()` starts a new round.
+ *
+ * The text is run through `unescapeMarkdown`: an artifact is always stored from markdown, and the
+ * backend's parse of a `.md` escapes its punctuation.
+ */
+declare function useArtifactText(docId: string | null | undefined, options?: {
+    enabled?: boolean;
+    retry?: ArtifactTextRetry;
+}): ArtifactText;
+
 /** The version lineage of an artifact in a workspace, oldest first. */
 declare function useArtifactVersions(workspaceId: string | undefined, docId: string | null | undefined): ArtifactVersion[];
 interface SaveArtifactVersionInput {
@@ -236,6 +290,13 @@ interface ArtifactSessionView {
     onCompare: () => void;
     onStopCompare: () => void;
     onToggleTrackChanges: () => void;
+    /**
+     * Whether the text is ready. `ArtifactEditor` renders "Preparing editor..." while it is
+     * `loading` or `parsing` (a fresh upload is parsed for a few seconds) and an error with Retry.
+     */
+    status: ArtifactTextStatus;
+    /** Ask for the text again after an `error`. */
+    onRetry: () => void;
 }
 interface ArtifactSession extends ArtifactEditSession {
     /** The open document: the new real id once a local draft has been saved. */
@@ -243,6 +304,8 @@ interface ArtifactSession extends ArtifactEditSession {
     /** The open version is an unsaved local draft (no backend document yet). */
     isLocal: boolean;
     isLoading: boolean;
+    /** See `ArtifactTextStatus`. */
+    status: ArtifactTextStatus;
     versions: ArtifactVersion[];
     /** "v2" for any version in the lineage. */
     labelOf: (id: string | null | undefined) => string | null;
@@ -289,4 +352,53 @@ interface ArtifactRedlineComponents {
  */
 declare function renderArtifactMarkdown(markdown: string, components?: ArtifactRedlineComponents): ReactNode;
 
-export { type ArtifactEditSession, type ArtifactEditSessionOptions, type ArtifactRedlineComponents, type ArtifactSaveResult, type ArtifactSession, type ArtifactSessionOptions, type ArtifactSessionView, type ArtifactVersion, type RedlineEngine, RedlineRegion, type RedlineState, RedlineWithRegions, type SaveArtifactVersionInput, type UseRedlineOptions, type UseRedlineResult, type VersionedDoc, buildVersionChain, flattenChunks, isDocumentId, mainThreadRedlineEngine, renderArtifactMarkdown, toArtifactVersions, useArtifactEditSession, useArtifactSession, useArtifactText, useArtifactVersions, useRedline, useSaveArtifactVersion, versionLabel };
+/**
+ * Where a drafted artifact is in its STREAM -> PERSIST -> EDIT life:
+ *  - `streaming`: the agent is still working (or has produced nothing final): show the live canvas;
+ *  - `persisting`: the finished draft is being stored as version 1 of the artifact;
+ *  - `parsing`: stored; the backend is still parsing it, so there is no editable text yet;
+ *  - `ready`: the text is readable: mount the editor on `docId`;
+ *  - `error`: storing failed or the parse never produced text (`retry()` starts over).
+ */
+type StreamedArtifactPhase = 'streaming' | 'persisting' | 'parsing' | 'ready' | 'error';
+interface UseStreamedArtifactOptions {
+    /** The artifacts of the agent run (`useConnectedAiTask().artifacts`). */
+    artifacts: ArtifactEvent[];
+    workspaceId: string | undefined;
+    /**
+     * The run has stopped: not busy and not failed. Nothing is stored before this, so a draft that
+     * is still streaming is never persisted half-written.
+     */
+    settled: boolean;
+    /** Make the stored markdown from the streamed content. Defaults to `cleanDraftMarkdown`. */
+    clean?: (streamed: string) => string;
+    /** Processing config for the stored version. */
+    configId?: string | null;
+    /** How long to wait for the parse (see `useArtifactText`). */
+    parseRetry?: ArtifactTextRetry;
+}
+interface StreamedArtifact {
+    phase: StreamedArtifactPhase;
+    /** The finished streamed artifact (its `title` names the stored versions). */
+    artifact: ArtifactEvent | undefined;
+    /** The backend document to edit, once there is one (while `parsing` and `ready`). */
+    docId: string | undefined;
+    error: Error | null;
+    /** After an `error`: store again or ask for the parse again. */
+    retry: () => void;
+}
+/**
+ * The lifecycle of an agent-drafted artifact, so a host passes the stream and renders the phase.
+ *
+ * While the agent streams, the draft lives only on the canvas. Once the run is `settled` and the
+ * draft is complete, a draft that is not yet a backend document is cleaned (`cleanDraftMarkdown`)
+ * and stored ONCE as the artifact's first version (`wpType: 'artifact'`); a draft that already is a
+ * backend document passes through. The hook then waits for the parse (`useArtifactText`, which
+ * retries) and reports `ready` with the `docId` to open in an editor.
+ *
+ * Needs an `<ArbiProvider>` and a workspace. `@arbidocs/blocks/connect` has the whole thing as a
+ * component (`StreamedArtifact`).
+ */
+declare function useStreamedArtifact({ artifacts, workspaceId, settled, clean, configId, parseRetry, }: UseStreamedArtifactOptions): StreamedArtifact;
+
+export { type ArtifactEditSession, type ArtifactEditSessionOptions, type ArtifactRedlineComponents, type ArtifactSaveResult, type ArtifactSession, type ArtifactSessionOptions, type ArtifactSessionView, type ArtifactText, type ArtifactTextRetry, type ArtifactTextStatus, type ArtifactVersion, DEFAULT_ARTIFACT_TEXT_RETRY, type RedlineEngine, RedlineRegion, type RedlineState, RedlineWithRegions, type SaveArtifactVersionInput, type StreamedArtifact, type StreamedArtifactPhase, type UseRedlineOptions, type UseRedlineResult, type UseStreamedArtifactOptions, type VersionedDoc, buildVersionChain, flattenChunks, isDocumentId, mainThreadRedlineEngine, renderArtifactMarkdown, toArtifactVersions, useArtifactEditSession, useArtifactSession, useArtifactText, useArtifactVersions, useRedline, useSaveArtifactVersion, useStreamedArtifact, versionLabel };

package/dist/artifacts/index.js

@@ -1,11 +1,12 @@
-import { useParsedDocument, useDocuments, arbiQueryKeys } from '../chunk-KWCHIAQ5.js';
+import { repairParsedTitle, unescapeMarkdown, arbiQueryKeys, useDocuments, cleanDraftMarkdown } from '../chunk-UV5ZEUNV.js';
+export { cleanDraftMarkdown, promoteBoldTitle, repairParsedTitle, stripAgentPreamble, unescapeMarkdown, unwrapCitationLinks } from '../chunk-UV5ZEUNV.js';
 import { revertRedlineRegion, buildHybridRedlineWithRegions, buildHybridRedlineMarkdown } from '../chunk-RKWNX32A.js';
 export { buildHybridRedlineMarkdown, buildHybridRedlineWithRegions, revertRedlineRegion } from '../chunk-RKWNX32A.js';
-import { MarkdownRenderer } from '../chunk-77G7DSUW.js';
-import '../chunk-SN5YV6FF.js';
 import { useArbi } from '../chunk-J4MX2W4H.js';
+import { MarkdownRenderer } from '../chunk-TGGQGFS3.js';
+import '../chunk-SN5YV6FF.js';
 import { useState, useRef, useEffect, useCallback, useMemo } from 'react';
-import { useQueryClient, useMutation } from '@tanstack/react-query';
+import { useQuery, useQueryClient, useMutation } from '@tanstack/react-query';
 import { jsx } from 'react/jsx-runtime';
 
 // src/artifacts/redline-engine.ts
@@ -129,8 +130,9 @@ function versionLabel(versions, docId) {
   const index = versions.findIndex((v) => v.id === docId);
   return index === -1 ? null : `v${index + 1}`;
 }
-function flattenChunks(chunks) {
-  return (chunks ?? []).map((c) => (c.content ?? "").trim()).join("\n\n");
+function flattenChunks(chunks, options) {
+  const text = (chunks ?? []).map((c) => (c.content ?? "").trim()).join("\n\n");
+  return options?.unescape ? repairParsedTitle(unescapeMarkdown(text)) : text;
 }
 var DOC_ID = /^doc/;
 function isDocumentId(id) {
@@ -311,19 +313,71 @@ function useArtifactEditSession(options) {
     ]
   );
 }
+var DEFAULT_ARTIFACT_TEXT_RETRY = {
+  attempts: 12,
+  baseDelayMs: 1e3,
+  maxDelayMs: 5e3
+};
+var NotParsedYetError = class extends Error {
+  constructor() {
+    super("The document has no parsed text yet");
+  }
+};
+var isRefusal = (error) => {
+  const status = error;
+  const code = status?.status ?? status?.response?.status;
+  return code === 401 || code === 403;
+};
 function useArtifactText(docId, options) {
-  const real = isDocumentId(docId);
-  const { data, isLoading, isError } = useParsedDocument(real ? docId : void 0, "marker", {
-    enabled: (options?.enabled ?? true) && real
+  const arbi = useArbi();
+  const { attempts, baseDelayMs, maxDelayMs } = {
+    ...DEFAULT_ARTIFACT_TEXT_RETRY,
+    ...options?.retry
+  };
+  const enabled = (options?.enabled ?? true) && isDocumentId(docId) && arbi.hasWorkspace;
+  const query = useQuery({
+    // Under the shared `parsedDoc` key, so a document's invalidation reaches it too.
+    queryKey: [...arbiQueryKeys.parsedDoc(docId ?? "", "marker"), "artifact-text"],
+    queryFn: async () => {
+      const parsed = await arbi.documents.getParsedContent(docId, "marker");
+      if (!parsed.chunks?.some((c) => c.content?.trim())) throw new NotParsedYetError();
+      return flattenChunks(parsed.chunks, { unescape: true });
+    },
+    enabled,
+    retry: (failureCount, error) => !isRefusal(error) && failureCount < attempts,
+    retryDelay: (failureCount) => Math.min(baseDelayMs * 1.6 ** failureCount, maxDelayMs)
   });
-  const text = useMemo(() => {
-    if (!real) return void 0;
-    if (isError) return null;
-    if (!data) return void 0;
-    return data.chunks?.length ? flattenChunks(data.chunks) : null;
-  }, [real, data, isError]);
-  return { text, isLoading: real && isLoading };
+  const { refetch } = query;
+  const retry = useCallback(() => void refetch(), [refetch]);
+  return useMemo(() => {
+    const error = query.error;
+    const neverParsed = error instanceof NotParsedYetError;
+    let status = "loading";
+    if (!enabled) status = "loading";
+    else if (query.isSuccess || query.isError && neverParsed) status = "ready";
+    else if (query.isError) status = "error";
+    else if (query.failureCount > 0) status = "parsing";
+    const text = !enabled ? void 0 : query.isSuccess ? query.data : status === "ready" || status === "error" ? null : void 0;
+    return {
+      text,
+      isLoading: enabled && (status === "loading" || status === "parsing"),
+      status,
+      error: status === "ready" ? null : error ?? query.failureReason ?? null,
+      retry
+    };
+  }, [
+    enabled,
+    query.isSuccess,
+    query.isError,
+    query.data,
+    query.error,
+    query.failureCount,
+    query.failureReason,
+    retry
+  ]);
 }
+
+// src/artifacts/useArtifactSession.ts
 function useArtifactVersions(workspaceId, docId) {
   const { data: documents } = useDocuments(workspaceId);
   return useMemo(
@@ -378,7 +432,7 @@ function useArtifactSession(options) {
     },
     [onCompareChange]
   );
-  const { text, isLoading } = useArtifactText(docId);
+  const { text, isLoading, status, retry } = useArtifactText(docId);
   const versions = useArtifactVersions(workspaceId, isLocal ? null : docId);
   const { text: compareText, isLoading: compareLoading } = useArtifactText(activeCompareId, {
     enabled: !!activeCompareId
@@ -427,6 +481,7 @@ function useArtifactSession(options) {
       docId,
       isLocal,
       isLoading,
+      status,
       versions,
       labelOf: (id) => versionLabel(versions, id),
       view: {
@@ -445,7 +500,10 @@ function useArtifactSession(options) {
         onSave: () => void session.save(),
         onCompare: () => session.compare(),
         onStopCompare: session.stopCompare,
-        onToggleTrackChanges: () => session.setShowTrackChanges(!session.showTrackChanges)
+        onToggleTrackChanges: () => session.setShowTrackChanges(!session.showTrackChanges),
+        // A local draft has its text already: it is ready.
+        status: isLocal ? "ready" : status,
+        onRetry: retry
       },
       editorProps: {
         markdown: session.content,
@@ -457,13 +515,64 @@ function useArtifactSession(options) {
         onRevert: (regionId) => void session.revertRegion(regionId)
       }
     }),
-    [session, redline, isLoading, isLocal, versions, docId]
+    [session, redline, isLoading, status, retry, isLocal, versions, docId]
   );
 }
 function renderArtifactMarkdown(markdown, components) {
   return /* @__PURE__ */ jsx(MarkdownRenderer, { components, children: markdown });
 }
+function useStreamedArtifact({
+  artifacts,
+  workspaceId,
+  settled,
+  clean = cleanDraftMarkdown,
+  configId,
+  parseRetry
+}) {
+  const artifact = artifacts.find((a) => a.is_complete);
+  const { mutateAsync } = useSaveArtifactVersion();
+  const [saved, setSaved] = useState(null);
+  const [saveError, setSaveError] = useState(null);
+  const [attempt, setAttempt] = useState(0);
+  const started = useRef(null);
+  const content = artifact?.content ?? "";
+  const title = artifact?.title ?? "Draft";
+  const passThrough = !!artifact && isDocumentId(artifact.doc_ext_id);
+  const needsSave = settled && !!artifact && !passThrough && !!content.trim() && !!workspaceId;
+  useEffect(() => {
+    const key = `${attempt}:${content}`;
+    if (!needsSave || started.current === key) return;
+    started.current = key;
+    setSaveError(null);
+    mutateAsync({
+      title,
+      content: clean(content),
+      workspaceId,
+      configId,
+      wpType: "artifact"
+    }).then((r) => {
+      if (r.docId) setSaved({ content, docId: r.docId });
+      else setSaveError(new Error("The draft was stored but the server returned no document id"));
+    }).catch((e) => setSaveError(e instanceof Error ? e : new Error(String(e))));
+  }, [needsSave, content, title, workspaceId, configId, attempt, mutateAsync]);
+  const docId = !artifact ? void 0 : passThrough ? artifact.doc_ext_id : saved?.content === content ? saved.docId : void 0;
+  const text = useArtifactText(docId, { enabled: settled, retry: parseRetry });
+  const { retry: retryText } = text;
+  const retry = useCallback(() => {
+    if (saveError) setAttempt((n) => n + 1);
+    else retryText();
+  }, [saveError, retryText]);
+  let phase;
+  if (!settled || !artifact) phase = "streaming";
+  else if (saveError) phase = "error";
+  else if (!docId) phase = needsSave ? "persisting" : "streaming";
+  else if (text.status === "ready" && text.text) phase = "ready";
+  else if (text.status === "error" || text.status === "ready") phase = "error";
+  else phase = "parsing";
+  const error = phase !== "error" ? null : saveError ?? text.error ?? new Error("The document has no text to edit");
+  return { phase, artifact, docId, error, retry };
+}
 
-export { buildVersionChain, flattenChunks, isDocumentId, mainThreadRedlineEngine, renderArtifactMarkdown, toArtifactVersions, useArtifactEditSession, useArtifactSession, useArtifactText, useArtifactVersions, useRedline, useSaveArtifactVersion, versionLabel };
+export { DEFAULT_ARTIFACT_TEXT_RETRY, buildVersionChain, flattenChunks, isDocumentId, mainThreadRedlineEngine, renderArtifactMarkdown, toArtifactVersions, useArtifactEditSession, useArtifactSession, useArtifactText, useArtifactVersions, useRedline, useSaveArtifactVersion, useStreamedArtifact, versionLabel };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map