@kedataindo/docflow-core 0.0.4 → 0.0.6

package/dist/index.cjs

@@ -31,12 +31,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   BlockAttributesExtension: () => BlockAttributesExtension,
+  CONTEXT_CHAR_CAP: () => CONTEXT_CHAR_CAP,
   EditorContextExtension: () => EditorContextExtension,
   FontSizeExtension: () => FontSizeExtension,
+  LOCAL_STORAGE_KEY: () => LOCAL_STORAGE_KEY,
   PAGE_SIZES: () => PAGE_SIZES,
   PaginationPlus: () => PaginationPlus,
   SearchAndReplaceExtension: () => SearchAndReplaceExtension,
   SubdocumentProvider: () => SubdocumentProvider,
+  buildAIPrompt: () => buildAIPrompt,
   clearSearch: () => clearSearch,
   collaborationExtensions: () => collaborationExtensions,
   collectExtensions: () => collectExtensions,
@@ -46,6 +49,10 @@ __export(index_exports, {
   definePlugin: () => definePlugin,
   findMatches: () => findMatches,
   getSearchState: () => getSearchState,
+  httpKeyStorage: () => httpKeyStorage,
+  localStorageKeyStorage: () => localStorageKeyStorage,
+  memoryKeyStorage: () => memoryKeyStorage,
+  openaiCompatibleProvider: () => openaiCompatibleProvider,
   replaceAll: () => replaceAll,
   replaceCurrent: () => replaceCurrent,
   resolveAction: () => resolveAction,
@@ -53,7 +60,10 @@ __export(index_exports, {
   searchAndReplaceKey: () => searchAndReplaceKey,
   searchNext: () => searchNext,
   searchPrev: () => searchPrev,
-  setSearchQuery: () => setSearchQuery
+  setSearchQuery: () => setSearchQuery,
+  toAIStreamFn: () => toAIStreamFn,
+  trimContextAfter: () => trimContextAfter,
+  trimContextBefore: () => trimContextBefore
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1953,15 +1963,281 @@ var SubdocumentProvider = class {
     this.activeQueue.length = 0;
   }
 };
+
+// src/ai/prompts.ts
+var CONTEXT_CHAR_CAP = 1500;
+var ONLY_RESULT = "Return ONLY the resulting text \u2014 no preamble, no explanation, no commentary, no markdown fences.";
+var SYSTEM_PROMPTS = {
+  rewrite: `You are a writing assistant. Rewrite the selected text to improve clarity, flow, and style while preserving its meaning. ${ONLY_RESULT}`,
+  summarize: `You are a writing assistant. Summarize the selected text concisely, keeping every key point. ${ONLY_RESULT}`,
+  grammar: `You are a writing assistant. Fix grammar, spelling, and punctuation in the selected text without changing its meaning or voice. ${ONLY_RESULT}`,
+  tone: `You are a writing assistant. Adjust the tone of the selected text as instructed while preserving its content. ${ONLY_RESULT}`,
+  translate: `You are a writing assistant. Translate the selected text as instructed, preserving structure and formatting. ${ONLY_RESULT}`,
+  expand: `You are a writing assistant. Expand the selected text with relevant detail, staying on topic and matching the existing style. ${ONLY_RESULT}`,
+  shorten: `You are a writing assistant. Shorten the selected text, keeping its essential meaning. ${ONLY_RESULT}`,
+  generate: `You are a writing assistant embedded in a document editor. Write the text the user asks for so it fits the surrounding context. ${ONLY_RESULT}`,
+  chat: "You are a helpful writing assistant embedded in a document editor. Answer the user\u2019s question. Use the provided document context when it is relevant; say so when it is not enough to answer."
+};
+function trimContextBefore(text) {
+  return text.length > CONTEXT_CHAR_CAP ? `\u2026${text.slice(-CONTEXT_CHAR_CAP)}` : text;
+}
+function trimContextAfter(text) {
+  return text.length > CONTEXT_CHAR_CAP ? `${text.slice(0, CONTEXT_CHAR_CAP)}\u2026` : text;
+}
+function quote(label, text) {
+  return `${label}:
+"""${text}"""`;
+}
+function contextSection(req) {
+  const parts = [];
+  if (req.context) {
+    const before = trimContextBefore(req.context.before ?? "");
+    const after = trimContextAfter(req.context.after ?? "");
+    if (before) parts.push(quote("Text before", before));
+    if (after) parts.push(quote("Text after", after));
+  }
+  return parts;
+}
+function buildAIPrompt(req) {
+  let system;
+  const userParts = [];
+  switch (req.action) {
+    case "rewrite":
+    case "summarize":
+    case "grammar":
+    case "expand":
+    case "shorten":
+      system = SYSTEM_PROMPTS[req.action];
+      userParts.push(quote("Selected text", req.selection ?? ""));
+      break;
+    case "tone":
+      system = SYSTEM_PROMPTS.tone;
+      userParts.push(quote("Selected text", req.selection ?? ""));
+      userParts.push(`Target tone: ${req.prompt ?? "professional"}`);
+      break;
+    case "translate":
+      system = SYSTEM_PROMPTS.translate;
+      userParts.push(quote("Selected text", req.selection ?? ""));
+      userParts.push(`Target language: ${req.prompt ?? "English"}`);
+      break;
+    case "generate":
+      system = SYSTEM_PROMPTS.generate;
+      userParts.push(`Instruction: ${req.prompt ?? ""}`);
+      break;
+    case "chat":
+      system = SYSTEM_PROMPTS.chat;
+      if (req.selection) userParts.push(quote("Selected text", req.selection));
+      userParts.push(req.prompt ?? "");
+      break;
+    case "draft":
+      throw new Error(
+        "action 'draft' is not built via buildAIPrompt \u2014 use the aiDraft port (Phase 7E)"
+      );
+    default: {
+      const exhaustive = req.action;
+      throw new Error(`Unknown AI action: ${String(exhaustive)}`);
+    }
+  }
+  userParts.push(...contextSection(req));
+  return { system, prompt: userParts.filter(Boolean).join("\n\n") };
+}
+
+// src/ai/adapter.ts
+function toAIStreamFn(provider) {
+  return async function* aiStream(req, signal) {
+    const { system, prompt } = buildAIPrompt(req);
+    for await (const event of provider.complete({ system, prompt, signal })) {
+      if (event.type === "delta") {
+        yield event.text;
+      } else if (event.type === "done") {
+        return;
+      } else {
+        throw event.error;
+      }
+    }
+  };
+}
+
+// src/ai/keyStorage.ts
+function memoryKeyStorage(initial = null) {
+  let value = initial;
+  return {
+    async get() {
+      return value;
+    },
+    async set(next) {
+      value = next;
+    },
+    async clear() {
+      value = null;
+    }
+  };
+}
+var LOCAL_STORAGE_KEY = "docflow:ai-config";
+function localStorageKeyStorage(key2 = LOCAL_STORAGE_KEY, storage) {
+  const store = () => {
+    const s = storage ?? globalThis.localStorage;
+    if (!s) throw new Error("localStorageKeyStorage: no Storage available (SSR?)");
+    return s;
+  };
+  return {
+    async get() {
+      const raw = store().getItem(key2);
+      if (!raw) return null;
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return null;
+      }
+    },
+    async set(value) {
+      store().setItem(key2, JSON.stringify(value));
+    },
+    async clear() {
+      store().removeItem(key2);
+    }
+  };
+}
+function httpKeyStorage(urls) {
+  const doFetch = urls.fetchImpl ?? ((...args) => fetch(...args));
+  return {
+    async get() {
+      const res = await doFetch(urls.getUrl, { credentials: "include" });
+      if (res.status === 404) return null;
+      if (!res.ok) throw new Error(`AI config read failed: ${res.status}`);
+      return await res.json();
+    },
+    async set(value) {
+      const res = await doFetch(urls.setUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        credentials: "include",
+        body: JSON.stringify(value)
+      });
+      if (!res.ok) throw new Error(`AI config write failed: ${res.status}`);
+    },
+    async clear() {
+      const res = await doFetch(urls.deleteUrl, { method: "DELETE", credentials: "include" });
+      if (!res.ok && res.status !== 404) throw new Error(`AI config delete failed: ${res.status}`);
+    }
+  };
+}
+
+// src/ai/openaiCompatibleProvider.ts
+function authHeaders(auth) {
+  switch (auth.type) {
+    case "bearer":
+      return { Authorization: `Bearer ${auth.apiKey}` };
+    case "header":
+      return { [auth.name]: auth.value };
+    case "none":
+      return {};
+  }
+}
+function toError(err) {
+  return err instanceof Error ? err : new Error(String(err));
+}
+function openaiCompatibleProvider(config) {
+  const baseUrl = config.baseUrl.replace(/\/+$/, "");
+  return {
+    async *complete(req) {
+      const controller = new AbortController();
+      const onAbort = () => controller.abort();
+      const callerSignal = req.signal;
+      if (callerSignal) {
+        if (callerSignal.aborted) controller.abort();
+        else callerSignal.addEventListener("abort", onAbort, { once: true });
+      }
+      try {
+        const system = [config.systemPrompt, req.system].filter(Boolean).join("\n\n");
+        const messages = [];
+        if (system) messages.push({ role: "system", content: system });
+        messages.push({ role: "user", content: req.prompt });
+        let res;
+        try {
+          res = await fetch(`${baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...authHeaders(config.auth) },
+            body: JSON.stringify({ model: config.model, messages, stream: true }),
+            signal: controller.signal
+          });
+        } catch (err) {
+          if (controller.signal.aborted) return;
+          yield { type: "error", error: toError(err) };
+          return;
+        }
+        if (!res.ok) {
+          const detail = await res.text().catch(() => "");
+          yield {
+            type: "error",
+            error: new Error(
+              `AI provider responded ${res.status}${detail ? `: ${detail.slice(0, 200)}` : ""}`
+            )
+          };
+          return;
+        }
+        if (!res.body) {
+          yield { type: "error", error: new Error("AI provider response has no body") };
+          return;
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        let sawDone = false;
+        try {
+          for (; ; ) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            let sep;
+            while ((sep = buffer.indexOf("\n\n")) >= 0) {
+              const block = buffer.slice(0, sep);
+              buffer = buffer.slice(sep + 2);
+              for (const line of block.split("\n")) {
+                if (!line.startsWith("data:")) continue;
+                const data = line.slice("data:".length).trim();
+                if (data === "[DONE]") {
+                  sawDone = true;
+                  yield { type: "done" };
+                  return;
+                }
+                try {
+                  const json = JSON.parse(data);
+                  const text = json.choices?.[0]?.delta?.content;
+                  if (text) yield { type: "delta", text };
+                } catch {
+                }
+              }
+            }
+          }
+        } catch (err) {
+          if (!controller.signal.aborted) {
+            yield { type: "error", error: toError(err) };
+            return;
+          }
+        } finally {
+          reader.releaseLock();
+        }
+        if (!sawDone && !controller.signal.aborted) yield { type: "done" };
+      } finally {
+        callerSignal?.removeEventListener("abort", onAbort);
+        controller.abort();
+      }
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BlockAttributesExtension,
+  CONTEXT_CHAR_CAP,
   EditorContextExtension,
   FontSizeExtension,
+  LOCAL_STORAGE_KEY,
   PAGE_SIZES,
   PaginationPlus,
   SearchAndReplaceExtension,
   SubdocumentProvider,
+  buildAIPrompt,
   clearSearch,
   collaborationExtensions,
   collectExtensions,
@@ -1971,6 +2247,10 @@ var SubdocumentProvider = class {
   definePlugin,
   findMatches,
   getSearchState,
+  httpKeyStorage,
+  localStorageKeyStorage,
+  memoryKeyStorage,
+  openaiCompatibleProvider,
   replaceAll,
   replaceCurrent,
   resolveAction,
@@ -1978,5 +2258,8 @@ var SubdocumentProvider = class {
   searchAndReplaceKey,
   searchNext,
   searchPrev,
-  setSearchQuery
+  setSearchQuery,
+  toAIStreamFn,
+  trimContextAfter,
+  trimContextBefore
 });

package/dist/index.d.cts

@@ -203,12 +203,51 @@ interface CitationPort {
 }
 
 /**
- * Shared AI action types (Phase 7).
+ * The library's only knowledge of LLMs (pluggable AI provider — issue #119).
+ *
+ * `AIProvider` is a thin transport: one prompt in, a stream of events out.
+ * The library imports only this type — never an implementation. Hosts plug in
+ * `openaiCompatibleProvider` (the default we ship) or their own class wrapping
+ * an agent SDK, a proxy, or an in-process model. Agent orchestration, tool
+ * calling, RAG, and multi-turn memory live behind the host's endpoint, not in
+ * the library. See docs/plans/PLUGGABLE_AI_PROVIDER.md §4.1.
+ */
+type StreamEvent = {
+    type: 'delta';
+    text: string;
+} | {
+    type: 'done';
+    stopReason?: string;
+} | {
+    type: 'error';
+    error: Error;
+};
+interface AICompleteRequest {
+    system?: string;
+    prompt: string;
+    signal?: AbortSignal;
+}
+interface AIProvider {
+    complete(req: AICompleteRequest): AsyncIterable<StreamEvent>;
+}
+
+/**
+ * Shared AI action types (Phase 7; pluggable AI provider — issue #119).
  *
  * The library (aiPlugin) is provider-agnostic: it never names a URL or holds a
- * key. The app implements `AIStreamFn` (apps/web/src/ai/aiStream.ts) and injects
- * it; the server owns provider selection via env config.
+ * key. The host injects `aiStream` / `aiDraft` via `EditorOptions` — either a
+ * hand-written function or `toAIStreamFn(openaiCompatibleProvider({...}))`
+ * (see ./provider.ts, ./openaiCompatibleProvider.ts).
+ */
+
+/**
+ * Factory shape for hosts that hand the library a provider object rather than
+ * a plain function (plan §4.2). `toAIStreamFn` adapts an `AIProvider` to the
+ * `AIStreamFn` port, so both shapes are accepted at the boundary.
  */
+type AIProviderFactory = (config: {
+    signal?: AbortSignal;
+}) => AIProvider;
 type AIAction = 'rewrite' | 'summarize' | 'grammar' | 'tone' | 'translate' | 'expand' | 'shorten' | 'generate' | 'chat' | 'draft';
 interface AIActionRequest {
     action: AIAction;
@@ -455,4 +494,109 @@ declare class SubdocumentProvider {
     destroy(): void;
 }
 
-export { type AIAction, type AIActionRequest, type AIDraftCitation, type AIDraftEvent, type AIDraftFn, type AIStreamFn, type AwarenessState, BlockAttributesExtension, type CitationPort, type CollaborationOptions, type CollaborationSetup, type CslDate, type CslItemData, type CslName, type DocsEditor, type DocsEditorPlugin, EditorContextExtension, type EditorContextOptions, type EditorOptions, FontSizeExtension, type ImageUploadHandler, type ImageUploadResult, SearchAndReplaceExtension, type SearchMatch, type SearchState, type SlashCommand, type SubdocState, SubdocumentProvider, type SubdocumentProviderOptions, type ToolbarItem, clearSearch, collaborationExtensions, collectExtensions, createActionMap, createCollaboration, createEditor, definePlugin, findMatches, getSearchState, replaceAll, replaceCurrent, resolveAction, sanitizePastedHTML, searchAndReplaceKey, searchNext, searchPrev, setSearchQuery };
+declare function toAIStreamFn(provider: AIProvider): AIStreamFn;
+
+/**
+ * Per-action prompt assembly (pluggable AI provider — issue #119).
+ *
+ * Ported from the Phase 7 server proxy (`apps/server/src/ai/context.ts`) so
+ * the browser can call the LLM directly: the selection + BOUNDED surrounding
+ * text is sent — never the whole document (cost + privacy). Untrusted document
+ * text stays in the user prompt; instructions live in the system prompt
+ * (prompt-injection hygiene).
+ */
+
+/** Max characters of surrounding context sent on each side of the selection. */
+declare const CONTEXT_CHAR_CAP = 1500;
+/** Last `CONTEXT_CHAR_CAP` chars of the preceding text (nearest context wins). */
+declare function trimContextBefore(text: string): string;
+/** First `CONTEXT_CHAR_CAP` chars of the following text. */
+declare function trimContextAfter(text: string): string;
+/**
+ * Assemble the per-action system prompt + user prompt from a bounded request.
+ * `draft` is rejected: RAG-cited drafting goes through the `aiDraft` port,
+ * which owns its grounded-prompt assembly (Phase 7E).
+ */
+declare function buildAIPrompt(req: AIActionRequest): {
+    system: string;
+    prompt: string;
+};
+
+/**
+ * Where the AI provider's config (base URL + credentials + model) lives —
+ * the host decides (pluggable AI provider — issue #119, plan §4.4).
+ *
+ * The URL and the key are a pair and travel together. The library ships three
+ * reference implementations; hosts may write their own (e.g. keyed per-tenant
+ * in their own backend). No URL is hardcoded anywhere — `httpKeyStorage`
+ * receives its endpoints from the host, keeping the library backend-agnostic
+ * (docs/LIBRARY_CONTRACT.md rule 3).
+ */
+type Auth = {
+    type: 'bearer';
+    apiKey: string;
+} | {
+    type: 'header';
+    name: string;
+    value: string;
+} | {
+    type: 'none';
+};
+interface AIConfig {
+    baseUrl: string;
+    auth: Auth;
+    model: string;
+}
+interface KeyStorage {
+    get(): Promise<AIConfig | null>;
+    set(value: AIConfig): Promise<void>;
+    clear(): Promise<void>;
+}
+/** In-memory storage — for tests and SSR (no persistence). */
+declare function memoryKeyStorage(initial?: AIConfig | null): KeyStorage;
+declare const LOCAL_STORAGE_KEY = "docflow:ai-config";
+/**
+ * Browser `localStorage` persistence — for embedded apps that want the config
+ * kept client-side. Note: this stores AI *credentials*, not document data, so
+ * it is the host's deliberate choice, not a library persistence leak.
+ */
+declare function localStorageKeyStorage(key?: string, storage?: Storage): KeyStorage;
+interface HttpKeyStorageUrls {
+    /** GET → 200 with the AIConfig JSON body, or 404 when unset. */
+    getUrl: string;
+    /** POST with the AIConfig JSON body. */
+    setUrl: string;
+    /** DELETE to clear. */
+    deleteUrl: string;
+    /** Optional fetch override (tests, custom credentials mode). Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Server-backed storage — for our SaaS web app (`/api/ai/config`) and any
+ * embedded app that wants credentials kept on its own backend. Endpoints are
+ * host-supplied; the library never names a path.
+ */
+declare function httpKeyStorage(urls: HttpKeyStorageUrls): KeyStorage;
+
+/**
+ * Default `AIProvider` implementation (pluggable AI provider — issue #119,
+ * plan §4.3): OpenAI-shaped `POST {baseUrl}/chat/completions` with SSE
+ * streaming. Covers OpenAI, Azure-style gateways, Ollama, vLLM, and most
+ * OpenAI-compatible proxies.
+ *
+ * Cancellation-safe: closing the async iterator early (e.g. the user accepts
+ * or cancels mid-stream) aborts the in-flight `fetch`; an aborted `req.signal`
+ * ends the stream silently rather than yielding an error event.
+ */
+
+interface OpenAICompatibleConfig {
+    /** Base URL of the OpenAI-compatible endpoint, e.g. `https://api.openai.com/v1`. */
+    baseUrl: string;
+    auth: Auth;
+    model: string;
+    /** Prepended to every call's system prompt so hosts don't repeat it. */
+    systemPrompt?: string;
+}
+declare function openaiCompatibleProvider(config: OpenAICompatibleConfig): AIProvider;
+
+export { type AIAction, type AIActionRequest, type AICompleteRequest, type AIConfig, type AIDraftCitation, type AIDraftEvent, type AIDraftFn, type AIProvider, type AIProviderFactory, type AIStreamFn, type Auth, type AwarenessState, BlockAttributesExtension, CONTEXT_CHAR_CAP, type CitationPort, type CollaborationOptions, type CollaborationSetup, type CslDate, type CslItemData, type CslName, type DocsEditor, type DocsEditorPlugin, EditorContextExtension, type EditorContextOptions, type EditorOptions, FontSizeExtension, type HttpKeyStorageUrls, type ImageUploadHandler, type ImageUploadResult, type KeyStorage, LOCAL_STORAGE_KEY, type OpenAICompatibleConfig, SearchAndReplaceExtension, type SearchMatch, type SearchState, type SlashCommand, type StreamEvent, type SubdocState, SubdocumentProvider, type SubdocumentProviderOptions, type ToolbarItem, buildAIPrompt, clearSearch, collaborationExtensions, collectExtensions, createActionMap, createCollaboration, createEditor, definePlugin, findMatches, getSearchState, httpKeyStorage, localStorageKeyStorage, memoryKeyStorage, openaiCompatibleProvider, replaceAll, replaceCurrent, resolveAction, sanitizePastedHTML, searchAndReplaceKey, searchNext, searchPrev, setSearchQuery, toAIStreamFn, trimContextAfter, trimContextBefore };

package/dist/index.d.ts

@@ -203,12 +203,51 @@ interface CitationPort {
 }
 
 /**
- * Shared AI action types (Phase 7).
+ * The library's only knowledge of LLMs (pluggable AI provider — issue #119).
+ *
+ * `AIProvider` is a thin transport: one prompt in, a stream of events out.
+ * The library imports only this type — never an implementation. Hosts plug in
+ * `openaiCompatibleProvider` (the default we ship) or their own class wrapping
+ * an agent SDK, a proxy, or an in-process model. Agent orchestration, tool
+ * calling, RAG, and multi-turn memory live behind the host's endpoint, not in
+ * the library. See docs/plans/PLUGGABLE_AI_PROVIDER.md §4.1.
+ */
+type StreamEvent = {
+    type: 'delta';
+    text: string;
+} | {
+    type: 'done';
+    stopReason?: string;
+} | {
+    type: 'error';
+    error: Error;
+};
+interface AICompleteRequest {
+    system?: string;
+    prompt: string;
+    signal?: AbortSignal;
+}
+interface AIProvider {
+    complete(req: AICompleteRequest): AsyncIterable<StreamEvent>;
+}
+
+/**
+ * Shared AI action types (Phase 7; pluggable AI provider — issue #119).
  *
  * The library (aiPlugin) is provider-agnostic: it never names a URL or holds a
- * key. The app implements `AIStreamFn` (apps/web/src/ai/aiStream.ts) and injects
- * it; the server owns provider selection via env config.
+ * key. The host injects `aiStream` / `aiDraft` via `EditorOptions` — either a
+ * hand-written function or `toAIStreamFn(openaiCompatibleProvider({...}))`
+ * (see ./provider.ts, ./openaiCompatibleProvider.ts).
+ */
+
+/**
+ * Factory shape for hosts that hand the library a provider object rather than
+ * a plain function (plan §4.2). `toAIStreamFn` adapts an `AIProvider` to the
+ * `AIStreamFn` port, so both shapes are accepted at the boundary.
  */
+type AIProviderFactory = (config: {
+    signal?: AbortSignal;
+}) => AIProvider;
 type AIAction = 'rewrite' | 'summarize' | 'grammar' | 'tone' | 'translate' | 'expand' | 'shorten' | 'generate' | 'chat' | 'draft';
 interface AIActionRequest {
     action: AIAction;
@@ -455,4 +494,109 @@ declare class SubdocumentProvider {
     destroy(): void;
 }
 
-export { type AIAction, type AIActionRequest, type AIDraftCitation, type AIDraftEvent, type AIDraftFn, type AIStreamFn, type AwarenessState, BlockAttributesExtension, type CitationPort, type CollaborationOptions, type CollaborationSetup, type CslDate, type CslItemData, type CslName, type DocsEditor, type DocsEditorPlugin, EditorContextExtension, type EditorContextOptions, type EditorOptions, FontSizeExtension, type ImageUploadHandler, type ImageUploadResult, SearchAndReplaceExtension, type SearchMatch, type SearchState, type SlashCommand, type SubdocState, SubdocumentProvider, type SubdocumentProviderOptions, type ToolbarItem, clearSearch, collaborationExtensions, collectExtensions, createActionMap, createCollaboration, createEditor, definePlugin, findMatches, getSearchState, replaceAll, replaceCurrent, resolveAction, sanitizePastedHTML, searchAndReplaceKey, searchNext, searchPrev, setSearchQuery };
+declare function toAIStreamFn(provider: AIProvider): AIStreamFn;
+
+/**
+ * Per-action prompt assembly (pluggable AI provider — issue #119).
+ *
+ * Ported from the Phase 7 server proxy (`apps/server/src/ai/context.ts`) so
+ * the browser can call the LLM directly: the selection + BOUNDED surrounding
+ * text is sent — never the whole document (cost + privacy). Untrusted document
+ * text stays in the user prompt; instructions live in the system prompt
+ * (prompt-injection hygiene).
+ */
+
+/** Max characters of surrounding context sent on each side of the selection. */
+declare const CONTEXT_CHAR_CAP = 1500;
+/** Last `CONTEXT_CHAR_CAP` chars of the preceding text (nearest context wins). */
+declare function trimContextBefore(text: string): string;
+/** First `CONTEXT_CHAR_CAP` chars of the following text. */
+declare function trimContextAfter(text: string): string;
+/**
+ * Assemble the per-action system prompt + user prompt from a bounded request.
+ * `draft` is rejected: RAG-cited drafting goes through the `aiDraft` port,
+ * which owns its grounded-prompt assembly (Phase 7E).
+ */
+declare function buildAIPrompt(req: AIActionRequest): {
+    system: string;
+    prompt: string;
+};
+
+/**
+ * Where the AI provider's config (base URL + credentials + model) lives —
+ * the host decides (pluggable AI provider — issue #119, plan §4.4).
+ *
+ * The URL and the key are a pair and travel together. The library ships three
+ * reference implementations; hosts may write their own (e.g. keyed per-tenant
+ * in their own backend). No URL is hardcoded anywhere — `httpKeyStorage`
+ * receives its endpoints from the host, keeping the library backend-agnostic
+ * (docs/LIBRARY_CONTRACT.md rule 3).
+ */
+type Auth = {
+    type: 'bearer';
+    apiKey: string;
+} | {
+    type: 'header';
+    name: string;
+    value: string;
+} | {
+    type: 'none';
+};
+interface AIConfig {
+    baseUrl: string;
+    auth: Auth;
+    model: string;
+}
+interface KeyStorage {
+    get(): Promise<AIConfig | null>;
+    set(value: AIConfig): Promise<void>;
+    clear(): Promise<void>;
+}
+/** In-memory storage — for tests and SSR (no persistence). */
+declare function memoryKeyStorage(initial?: AIConfig | null): KeyStorage;
+declare const LOCAL_STORAGE_KEY = "docflow:ai-config";
+/**
+ * Browser `localStorage` persistence — for embedded apps that want the config
+ * kept client-side. Note: this stores AI *credentials*, not document data, so
+ * it is the host's deliberate choice, not a library persistence leak.
+ */
+declare function localStorageKeyStorage(key?: string, storage?: Storage): KeyStorage;
+interface HttpKeyStorageUrls {
+    /** GET → 200 with the AIConfig JSON body, or 404 when unset. */
+    getUrl: string;
+    /** POST with the AIConfig JSON body. */
+    setUrl: string;
+    /** DELETE to clear. */
+    deleteUrl: string;
+    /** Optional fetch override (tests, custom credentials mode). Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Server-backed storage — for our SaaS web app (`/api/ai/config`) and any
+ * embedded app that wants credentials kept on its own backend. Endpoints are
+ * host-supplied; the library never names a path.
+ */
+declare function httpKeyStorage(urls: HttpKeyStorageUrls): KeyStorage;
+
+/**
+ * Default `AIProvider` implementation (pluggable AI provider — issue #119,
+ * plan §4.3): OpenAI-shaped `POST {baseUrl}/chat/completions` with SSE
+ * streaming. Covers OpenAI, Azure-style gateways, Ollama, vLLM, and most
+ * OpenAI-compatible proxies.
+ *
+ * Cancellation-safe: closing the async iterator early (e.g. the user accepts
+ * or cancels mid-stream) aborts the in-flight `fetch`; an aborted `req.signal`
+ * ends the stream silently rather than yielding an error event.
+ */
+
+interface OpenAICompatibleConfig {
+    /** Base URL of the OpenAI-compatible endpoint, e.g. `https://api.openai.com/v1`. */
+    baseUrl: string;
+    auth: Auth;
+    model: string;
+    /** Prepended to every call's system prompt so hosts don't repeat it. */
+    systemPrompt?: string;
+}
+declare function openaiCompatibleProvider(config: OpenAICompatibleConfig): AIProvider;
+
+export { type AIAction, type AIActionRequest, type AICompleteRequest, type AIConfig, type AIDraftCitation, type AIDraftEvent, type AIDraftFn, type AIProvider, type AIProviderFactory, type AIStreamFn, type Auth, type AwarenessState, BlockAttributesExtension, CONTEXT_CHAR_CAP, type CitationPort, type CollaborationOptions, type CollaborationSetup, type CslDate, type CslItemData, type CslName, type DocsEditor, type DocsEditorPlugin, EditorContextExtension, type EditorContextOptions, type EditorOptions, FontSizeExtension, type HttpKeyStorageUrls, type ImageUploadHandler, type ImageUploadResult, type KeyStorage, LOCAL_STORAGE_KEY, type OpenAICompatibleConfig, SearchAndReplaceExtension, type SearchMatch, type SearchState, type SlashCommand, type StreamEvent, type SubdocState, SubdocumentProvider, type SubdocumentProviderOptions, type ToolbarItem, buildAIPrompt, clearSearch, collaborationExtensions, collectExtensions, createActionMap, createCollaboration, createEditor, definePlugin, findMatches, getSearchState, httpKeyStorage, localStorageKeyStorage, memoryKeyStorage, openaiCompatibleProvider, replaceAll, replaceCurrent, resolveAction, sanitizePastedHTML, searchAndReplaceKey, searchNext, searchPrev, setSearchQuery, toAIStreamFn, trimContextAfter, trimContextBefore };

package/dist/index.js

@@ -1894,14 +1894,280 @@ var SubdocumentProvider = class {
     this.activeQueue.length = 0;
   }
 };
+
+// src/ai/prompts.ts
+var CONTEXT_CHAR_CAP = 1500;
+var ONLY_RESULT = "Return ONLY the resulting text \u2014 no preamble, no explanation, no commentary, no markdown fences.";
+var SYSTEM_PROMPTS = {
+  rewrite: `You are a writing assistant. Rewrite the selected text to improve clarity, flow, and style while preserving its meaning. ${ONLY_RESULT}`,
+  summarize: `You are a writing assistant. Summarize the selected text concisely, keeping every key point. ${ONLY_RESULT}`,
+  grammar: `You are a writing assistant. Fix grammar, spelling, and punctuation in the selected text without changing its meaning or voice. ${ONLY_RESULT}`,
+  tone: `You are a writing assistant. Adjust the tone of the selected text as instructed while preserving its content. ${ONLY_RESULT}`,
+  translate: `You are a writing assistant. Translate the selected text as instructed, preserving structure and formatting. ${ONLY_RESULT}`,
+  expand: `You are a writing assistant. Expand the selected text with relevant detail, staying on topic and matching the existing style. ${ONLY_RESULT}`,
+  shorten: `You are a writing assistant. Shorten the selected text, keeping its essential meaning. ${ONLY_RESULT}`,
+  generate: `You are a writing assistant embedded in a document editor. Write the text the user asks for so it fits the surrounding context. ${ONLY_RESULT}`,
+  chat: "You are a helpful writing assistant embedded in a document editor. Answer the user\u2019s question. Use the provided document context when it is relevant; say so when it is not enough to answer."
+};
+function trimContextBefore(text) {
+  return text.length > CONTEXT_CHAR_CAP ? `\u2026${text.slice(-CONTEXT_CHAR_CAP)}` : text;
+}
+function trimContextAfter(text) {
+  return text.length > CONTEXT_CHAR_CAP ? `${text.slice(0, CONTEXT_CHAR_CAP)}\u2026` : text;
+}
+function quote(label, text) {
+  return `${label}:
+"""${text}"""`;
+}
+function contextSection(req) {
+  const parts = [];
+  if (req.context) {
+    const before = trimContextBefore(req.context.before ?? "");
+    const after = trimContextAfter(req.context.after ?? "");
+    if (before) parts.push(quote("Text before", before));
+    if (after) parts.push(quote("Text after", after));
+  }
+  return parts;
+}
+function buildAIPrompt(req) {
+  let system;
+  const userParts = [];
+  switch (req.action) {
+    case "rewrite":
+    case "summarize":
+    case "grammar":
+    case "expand":
+    case "shorten":
+      system = SYSTEM_PROMPTS[req.action];
+      userParts.push(quote("Selected text", req.selection ?? ""));
+      break;
+    case "tone":
+      system = SYSTEM_PROMPTS.tone;
+      userParts.push(quote("Selected text", req.selection ?? ""));
+      userParts.push(`Target tone: ${req.prompt ?? "professional"}`);
+      break;
+    case "translate":
+      system = SYSTEM_PROMPTS.translate;
+      userParts.push(quote("Selected text", req.selection ?? ""));
+      userParts.push(`Target language: ${req.prompt ?? "English"}`);
+      break;
+    case "generate":
+      system = SYSTEM_PROMPTS.generate;
+      userParts.push(`Instruction: ${req.prompt ?? ""}`);
+      break;
+    case "chat":
+      system = SYSTEM_PROMPTS.chat;
+      if (req.selection) userParts.push(quote("Selected text", req.selection));
+      userParts.push(req.prompt ?? "");
+      break;
+    case "draft":
+      throw new Error(
+        "action 'draft' is not built via buildAIPrompt \u2014 use the aiDraft port (Phase 7E)"
+      );
+    default: {
+      const exhaustive = req.action;
+      throw new Error(`Unknown AI action: ${String(exhaustive)}`);
+    }
+  }
+  userParts.push(...contextSection(req));
+  return { system, prompt: userParts.filter(Boolean).join("\n\n") };
+}
+
+// src/ai/adapter.ts
+function toAIStreamFn(provider) {
+  return async function* aiStream(req, signal) {
+    const { system, prompt } = buildAIPrompt(req);
+    for await (const event of provider.complete({ system, prompt, signal })) {
+      if (event.type === "delta") {
+        yield event.text;
+      } else if (event.type === "done") {
+        return;
+      } else {
+        throw event.error;
+      }
+    }
+  };
+}
+
+// src/ai/keyStorage.ts
+function memoryKeyStorage(initial = null) {
+  let value = initial;
+  return {
+    async get() {
+      return value;
+    },
+    async set(next) {
+      value = next;
+    },
+    async clear() {
+      value = null;
+    }
+  };
+}
+var LOCAL_STORAGE_KEY = "docflow:ai-config";
+function localStorageKeyStorage(key2 = LOCAL_STORAGE_KEY, storage) {
+  const store = () => {
+    const s = storage ?? globalThis.localStorage;
+    if (!s) throw new Error("localStorageKeyStorage: no Storage available (SSR?)");
+    return s;
+  };
+  return {
+    async get() {
+      const raw = store().getItem(key2);
+      if (!raw) return null;
+      try {
+        return JSON.parse(raw);
+      } catch {
+        return null;
+      }
+    },
+    async set(value) {
+      store().setItem(key2, JSON.stringify(value));
+    },
+    async clear() {
+      store().removeItem(key2);
+    }
+  };
+}
+function httpKeyStorage(urls) {
+  const doFetch = urls.fetchImpl ?? ((...args) => fetch(...args));
+  return {
+    async get() {
+      const res = await doFetch(urls.getUrl, { credentials: "include" });
+      if (res.status === 404) return null;
+      if (!res.ok) throw new Error(`AI config read failed: ${res.status}`);
+      return await res.json();
+    },
+    async set(value) {
+      const res = await doFetch(urls.setUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        credentials: "include",
+        body: JSON.stringify(value)
+      });
+      if (!res.ok) throw new Error(`AI config write failed: ${res.status}`);
+    },
+    async clear() {
+      const res = await doFetch(urls.deleteUrl, { method: "DELETE", credentials: "include" });
+      if (!res.ok && res.status !== 404) throw new Error(`AI config delete failed: ${res.status}`);
+    }
+  };
+}
+
+// src/ai/openaiCompatibleProvider.ts
+function authHeaders(auth) {
+  switch (auth.type) {
+    case "bearer":
+      return { Authorization: `Bearer ${auth.apiKey}` };
+    case "header":
+      return { [auth.name]: auth.value };
+    case "none":
+      return {};
+  }
+}
+function toError(err) {
+  return err instanceof Error ? err : new Error(String(err));
+}
+function openaiCompatibleProvider(config) {
+  const baseUrl = config.baseUrl.replace(/\/+$/, "");
+  return {
+    async *complete(req) {
+      const controller = new AbortController();
+      const onAbort = () => controller.abort();
+      const callerSignal = req.signal;
+      if (callerSignal) {
+        if (callerSignal.aborted) controller.abort();
+        else callerSignal.addEventListener("abort", onAbort, { once: true });
+      }
+      try {
+        const system = [config.systemPrompt, req.system].filter(Boolean).join("\n\n");
+        const messages = [];
+        if (system) messages.push({ role: "system", content: system });
+        messages.push({ role: "user", content: req.prompt });
+        let res;
+        try {
+          res = await fetch(`${baseUrl}/chat/completions`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...authHeaders(config.auth) },
+            body: JSON.stringify({ model: config.model, messages, stream: true }),
+            signal: controller.signal
+          });
+        } catch (err) {
+          if (controller.signal.aborted) return;
+          yield { type: "error", error: toError(err) };
+          return;
+        }
+        if (!res.ok) {
+          const detail = await res.text().catch(() => "");
+          yield {
+            type: "error",
+            error: new Error(
+              `AI provider responded ${res.status}${detail ? `: ${detail.slice(0, 200)}` : ""}`
+            )
+          };
+          return;
+        }
+        if (!res.body) {
+          yield { type: "error", error: new Error("AI provider response has no body") };
+          return;
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        let sawDone = false;
+        try {
+          for (; ; ) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            let sep;
+            while ((sep = buffer.indexOf("\n\n")) >= 0) {
+              const block = buffer.slice(0, sep);
+              buffer = buffer.slice(sep + 2);
+              for (const line of block.split("\n")) {
+                if (!line.startsWith("data:")) continue;
+                const data = line.slice("data:".length).trim();
+                if (data === "[DONE]") {
+                  sawDone = true;
+                  yield { type: "done" };
+                  return;
+                }
+                try {
+                  const json = JSON.parse(data);
+                  const text = json.choices?.[0]?.delta?.content;
+                  if (text) yield { type: "delta", text };
+                } catch {
+                }
+              }
+            }
+          }
+        } catch (err) {
+          if (!controller.signal.aborted) {
+            yield { type: "error", error: toError(err) };
+            return;
+          }
+        } finally {
+          reader.releaseLock();
+        }
+        if (!sawDone && !controller.signal.aborted) yield { type: "done" };
+      } finally {
+        callerSignal?.removeEventListener("abort", onAbort);
+        controller.abort();
+      }
+    }
+  };
+}
 export {
   BlockAttributesExtension,
+  CONTEXT_CHAR_CAP,
   EditorContextExtension,
   FontSizeExtension,
+  LOCAL_STORAGE_KEY,
   PAGE_SIZES,
   PaginationPlus,
   SearchAndReplaceExtension,
   SubdocumentProvider,
+  buildAIPrompt,
   clearSearch,
   collaborationExtensions,
   collectExtensions,
@@ -1911,6 +2177,10 @@ export {
   definePlugin,
   findMatches,
   getSearchState,
+  httpKeyStorage,
+  localStorageKeyStorage,
+  memoryKeyStorage,
+  openaiCompatibleProvider,
   replaceAll,
   replaceCurrent,
   resolveAction,
@@ -1918,5 +2188,8 @@ export {
   searchAndReplaceKey,
   searchNext,
   searchPrev,
-  setSearchQuery
+  setSearchQuery,
+  toAIStreamFn,
+  trimContextAfter,
+  trimContextBefore
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kedataindo/docflow-core",
   "license": "UNLICENSED",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",