@perspective-dev/viewer 5.1.0 → 5.2.0

package/src/rust/agent/client/turn.rs

@@ -0,0 +1,174 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+//! The agentic loop: model request → dispatch any tool calls → repeat, until
+//! the model answers in text or the turn budget runs out.
+
+use perspective_js::utils::ApiError;
+use serde_json::json;
+
+use super::protocol::{ChatMessage, ChatRequest};
+use super::transport::{AgentTransport, OnDelta};
+use crate::agent::config::SystemRole;
+use crate::agent::tools::{ToolCtx, tool_definitions, tool_dispatch};
+use crate::custom_elements::viewer::PerspectiveViewerElement;
+
+/// How a turn ended without a final assistant answer. The distinction
+/// matters to the caller's commit decision: on [`TurnError::Budget`] the
+/// transcript is *coherent* (every dispatched tool call has its result) and
+/// the dispatched tools may have mutated the viewer, so the transcript must
+/// be COMMITTED — discarding it would leave the next prompt blind to
+/// mutations that persist on screen (e.g. re-adding a panel the model does
+/// not know it created). [`TurnError::Api`] (transport/protocol failure)
+/// leaves the transcript mid-request and is discarded as before.
+pub enum TurnError {
+    Budget { max_turns: usize },
+    Api(ApiError),
+}
+
+impl From<ApiError> for TurnError {
+    fn from(err: ApiError) -> Self {
+        Self::Api(err)
+    }
+}
+
+impl From<TurnError> for ApiError {
+    fn from(err: TurnError) -> Self {
+        match err {
+            TurnError::Budget { max_turns } => ApiError::from(format!(
+                "Turn budget exhausted after {max_turns} model requests (see `maxTurns`)"
+            )),
+            TurnError::Api(err) => err,
+        }
+    }
+}
+
+/// Appended (transiently — never committed to the durable transcript) to
+/// the turn's final budgeted request, so the model answers instead of
+/// starting tool work it cannot finish.
+const BUDGET_NUDGE: &str = "This is the final model request of this turn's budget. Do not call \
+                            more tools - answer now with a short summary of what was done and \
+                            what, if anything, remains.";
+
+/// Run one conversational turn, mutating `messages` (system prompt at index
+/// 0, then transcript) in place with everything the model and tools said.
+/// Tool *failures* are fed back to the model as error tool-results so it can
+/// self-correct; transport and protocol failures abort the turn mid-request,
+/// while turn-budget exhaustion ends it with a coherent transcript — see
+/// [`TurnError`] for the commit consequences.
+#[allow(clippy::too_many_arguments)]
+pub async fn run_turn(
+    transport: &AgentTransport,
+    model: &str,
+    max_turns: usize,
+    elem: &PerspectiveViewerElement,
+    ctx: &ToolCtx,
+    messages: &mut Vec<ChatMessage>,
+    system_role: SystemRole,
+    on_delta: OnDelta<'_>,
+) -> Result<String, TurnError> {
+    let defs = tool_definitions(ctx);
+    for turn in 0..max_turns {
+        // Each model request streams into a fresh tail — reset the live
+        // view so a prior request's partial text does not linger across
+        // tool rounds.
+        on_delta("", "");
+        let nudged;
+        let request_messages: &[ChatMessage] = if turn + 1 == max_turns && max_turns > 1 {
+            let mut with_nudge = messages.clone();
+
+            // Follows the preamble's placement: an engine that rejects a
+            // system message alongside `tools` rejects THIS one too, and
+            // it is appended to the very request that most needs to
+            // succeed.
+            with_nudge.push(match system_role {
+                SystemRole::System => ChatMessage::System {
+                    content: BUDGET_NUDGE.to_owned(),
+                },
+                SystemRole::User => ChatMessage::User {
+                    content: BUDGET_NUDGE.to_owned(),
+                },
+            });
+
+            nudged = with_nudge;
+            &nudged
+        } else {
+            messages
+        };
+
+        let request = ChatRequest {
+            model,
+            messages: request_messages,
+            tools: &defs,
+            stream: true,
+        };
+
+        let message = transport.create(&request, on_delta).await?;
+        let ChatMessage::Assistant {
+            content,
+            tool_calls,
+            reasoning_content,
+        } = message
+        else {
+            return Err(
+                ApiError::from("Completion response message role is not `assistant`").into(),
+            );
+        };
+
+        if tool_calls.is_empty() {
+            let text = content.unwrap_or_default();
+
+            // The buffered fallback never fired `on_delta` — surface the
+            // final text (and any reasoning) so the live view converges on
+            // what history records regardless of transport path.
+            on_delta(&text, reasoning_content.as_deref().unwrap_or_default());
+            messages.push(ChatMessage::Assistant {
+                content: Some(text.clone()),
+                tool_calls: vec![],
+                reasoning_content,
+            });
+
+            return Ok(text);
+        }
+
+        messages.push(ChatMessage::Assistant {
+            content,
+            tool_calls: tool_calls.clone(),
+            reasoning_content,
+        });
+
+        // TODO: There is deliberately no duplicate-call breaker here: a
+        // tool call identical (name + arguments) to one already made this
+        // turn is re-dispatched verbatim, so a model stuck at a fixed
+        // point burns budget until the nudge/exhaustion path ends the
+        // turn (observed in the field: qwen looping `validate_expression`
+        // to `maxTurns`). If nudge + budget prove insufficient, the
+        // breaker is: synthesize an error result ("already called with
+        // identical arguments; the result will not change") without
+        // dispatching.
+        for call in tool_calls {
+            let content =
+                match tool_dispatch(elem, ctx, &call.function.name, &call.function.arguments).await
+                {
+                    Ok(value) => value.to_string(),
+                    Err(err) => json!({ "error": format!("{err}") }).to_string(),
+                };
+
+            messages.push(ChatMessage::Tool {
+                tool_call_id: call.id,
+                content,
+            });
+        }
+    }
+
+    Err(TurnError::Budget { max_turns })
+}

package/src/rust/agent/config.rs

@@ -0,0 +1,159 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+//! `agentConfig()` parsing. There is no provider abstraction in the core —
+//! the client speaks one protocol (OpenAI chat-completions) over primitive
+//! connection fields (`url` + `headers` + `apiKey`, or an in-page
+//! `engine`), and "providers" are plain JSON presets in the JS package
+//! spread into the config (`{...providers.anthropic, apiKey}`).
+
+use std::collections::HashMap;
+
+use perspective_js::utils::{ApiError, ApiResult};
+use serde::Deserialize;
+use wasm_bindgen::prelude::*;
+
+use super::tools::Entitlement;
+
+/// The serde-compatible subset of the `agentConfig()` argument; the
+/// `engine` and `docs` fields are live JS values (an engine object; a
+/// fetch `Response`/buffer/promise or entry array) and are extracted
+/// separately by reference.
+#[derive(Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct AgentConfigFields {
+    /// Cosmetic label for the chat badge (presets set this).
+    name: Option<String>,
+
+    /// Full chat-completions endpoint URL, e.g.
+    /// `https://api.anthropic.com/v1/chat/completions`.
+    url: Option<String>,
+
+    /// Extra request headers sent verbatim (e.g. Anthropic's
+    /// `anthropic-dangerous-direct-browser-access`).
+    headers: Option<HashMap<String, String>>,
+
+    /// Sugar for `Authorization: Bearer <apiKey>` — verified accepted by
+    /// every supported OpenAI-compat endpoint (incl. Anthropic + Gemini).
+    api_key: Option<String>,
+
+    model: Option<String>,
+    system_prompt: Option<String>,
+    system_role: Option<SystemRole>,
+    max_turns: Option<usize>,
+
+    /// Access grants (snake_case [`Entitlement`] names); omitted ⇒ the
+    /// default set (everything except `read_data`).
+    entitlements: Option<Vec<String>>,
+}
+
+/// Where the preamble (plus any `systemPrompt`) is placed in a request.
+///
+/// Some engines refuse to accept a system message alongside `tools`
+/// because they need to own the system prompt themselves — WebLLM's
+/// Hermes function-calling rejects the whole request with
+/// `CustomSystemPromptError`. [`SystemRole::User`] folds the same text
+/// into the conversation's first USER message instead, which those
+/// engines accept and which reads identically to the model.
+#[derive(Clone, Copy, Debug, Default, Deserialize, PartialEq)]
+#[serde(rename_all = "lowercase")]
+pub enum SystemRole {
+    #[default]
+    System,
+    User,
+}
+
+/// Parsed `viewer.agentConfig({...})` argument.
+pub struct AgentConfig {
+    pub name: Option<String>,
+    pub url: Option<String>,
+    pub headers: Option<HashMap<String, String>>,
+    pub api_key: Option<String>,
+    pub model: Option<String>,
+    pub system_prompt: Option<String>,
+    pub system_role: SystemRole,
+    pub max_turns: Option<usize>,
+    pub entitlements: Vec<Entitlement>,
+    pub engine: Option<JsValue>,
+    pub docs: Option<JsValue>,
+}
+
+impl AgentConfig {
+    pub fn from_js(config: &JsValue) -> ApiResult<Self> {
+        let fields: AgentConfigFields = serde_wasm_bindgen::from_value(config.clone())?;
+        let engine = js_sys::Reflect::get(config, &JsValue::from_str("engine"))
+            .ok()
+            .filter(|x| !x.is_undefined() && !x.is_null());
+
+        let docs = js_sys::Reflect::get(config, &JsValue::from_str("docs"))
+            .ok()
+            .filter(|x| !x.is_undefined() && !x.is_null() && x.as_bool() != Some(false));
+
+        match (&fields.url, &engine) {
+            (Some(_), Some(_)) => {
+                return Err(ApiError::from("Pass either `url` or `engine`, not both"));
+            },
+            (None, None) => {
+                return Err(ApiError::from(
+                    "Either `url` (a chat-completions endpoint, e.g. a spread provider preset) or \
+                     `engine` (an in-page engine object) is required",
+                ));
+            },
+            _ => (),
+        }
+
+        let entitlements = match fields.entitlements {
+            None => Entitlement::default_set(),
+            Some(names) => names
+                .iter()
+                .map(|x| x.parse())
+                .collect::<Result<Vec<_>, _>>()
+                .map_err(ApiError::from)?,
+        };
+
+        Ok(Self {
+            name: fields.name,
+            url: fields.url,
+            headers: fields.headers,
+            api_key: fields.api_key,
+            model: fields.model,
+            system_prompt: fields.system_prompt,
+            system_role: fields.system_role.unwrap_or_default(),
+            max_turns: fields.max_turns,
+            entitlements,
+            engine,
+            docs,
+        })
+    }
+
+    /// The model id sent on every completion request. Local servers and
+    /// in-page engines generally answer with whatever model they have
+    /// loaded, so the fallback is a placeholder.
+    pub fn model_name(&self) -> &str {
+        self.model.as_deref().unwrap_or("default")
+    }
+
+    /// Chat-badge text: the preset `name`, else the endpoint host, else
+    /// `"engine"`.
+    pub fn label_name(&self) -> String {
+        if let Some(name) = &self.name {
+            return name.clone();
+        }
+
+        self.url
+            .as_deref()
+            .and_then(|x| x.split("//").nth(1))
+            .and_then(|x| x.split('/').next())
+            .map(str::to_owned)
+            .unwrap_or_else(|| "engine".to_owned())
+    }
+}

package/src/rust/agent/docs.rs

@@ -0,0 +1,293 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+use std::collections::HashMap;
+use std::rc::Rc;
+
+use serde::Deserialize;
+use serde_json::Value;
+use wasm_bindgen::prelude::*;
+use wasm_bindgen_futures::JsFuture;
+
+/// One retrievable unit. `title`/`path` are optional in host-supplied
+/// entries; oversized `text` is split at paragraph boundaries on ingest so
+/// hosts never need to understand chunking.
+#[derive(Clone, Deserialize)]
+pub struct Chunk {
+    #[serde(default)]
+    pub title: String,
+    #[serde(default)]
+    pub path: String,
+    pub text: String,
+}
+
+const SPLIT_OVER: usize = 2500;
+
+/// Words too common to discriminate; deliberately tiny — the caller is a
+/// model that writes keyword-style queries.
+const STOP_WORDS: &[&str] = &["the", "a", "an", "of", "to", "is", "in", "and", "or", "for"];
+
+/// Lowercase alphanumeric-and-`_` tokens; identifiers containing `_` also
+/// emit their parts, so `split_by` matches both the exact API token and the
+/// natural-language query "split by".
+fn tokenize(text: &str) -> Vec<String> {
+    let mut tokens = vec![];
+    for raw in text
+        .to_lowercase()
+        .split(|x: char| !x.is_alphanumeric() && x != '_')
+    {
+        if raw.is_empty() || STOP_WORDS.contains(&raw) {
+            continue;
+        }
+
+        tokens.push(raw.to_owned());
+        if raw.contains('_') {
+            for part in raw.split('_').filter(|x| !x.is_empty()) {
+                tokens.push(part.to_owned());
+            }
+        }
+    }
+
+    tokens
+}
+
+pub struct DocsIndex {
+    chunks: Vec<Chunk>,
+    postings: HashMap<String, Vec<(usize, f64)>>,
+    lens: Vec<f64>,
+    avg_len: f64,
+}
+
+impl DocsIndex {
+    pub fn build(entries: Vec<Chunk>) -> Self {
+        let chunks = normalize(entries);
+        let mut postings: HashMap<String, Vec<(usize, f64)>> = HashMap::new();
+        let mut lens = Vec::with_capacity(chunks.len());
+        for (idx, chunk) in chunks.iter().enumerate() {
+            let tokens = tokenize(&format!("{} {}", chunk.title, chunk.text));
+            lens.push(tokens.len() as f64);
+            let mut counts: HashMap<String, f64> = HashMap::new();
+            for token in tokens {
+                *counts.entry(token).or_default() += 1.0;
+            }
+
+            for (token, count) in counts {
+                postings.entry(token).or_default().push((idx, count));
+            }
+        }
+
+        let avg_len = (lens.iter().sum::<f64>() / lens.len().max(1) as f64).max(1.0);
+        Self {
+            chunks,
+            postings,
+            lens,
+            avg_len,
+        }
+    }
+
+    /// BM25 (k1 = 1.2, b = 0.75) top-`limit` chunks for a keyword query.
+    pub fn search(&self, query: &str, limit: usize) -> Vec<&Chunk> {
+        const K1: f64 = 1.2;
+        const B: f64 = 0.75;
+        let n = self.chunks.len() as f64;
+        let mut terms = tokenize(query);
+        terms.sort();
+        terms.dedup();
+        let mut scores: HashMap<usize, f64> = HashMap::new();
+        for term in terms {
+            let Some(posting) = self.postings.get(&term) else {
+                continue;
+            };
+
+            let df = posting.len() as f64;
+            let idf = ((n - df + 0.5) / (df + 0.5) + 1.0).ln();
+            for (idx, tf) in posting {
+                let norm = K1 * (1.0 - B + B * self.lens[*idx] / self.avg_len);
+                *scores.entry(*idx).or_default() += idf * tf / (tf + norm);
+            }
+        }
+
+        let mut ranked = scores.into_iter().collect::<Vec<_>>();
+        ranked.sort_by(|x, y| y.1.total_cmp(&x.1).then(x.0.cmp(&y.0)));
+        ranked
+            .into_iter()
+            .take(limit)
+            .map(|(idx, _)| &self.chunks[idx])
+            .collect()
+    }
+}
+
+/// Default titles from a text prefix; split oversized entries at paragraph
+/// boundaries (a single paragraph longer than the limit stays whole).
+fn normalize(entries: Vec<Chunk>) -> Vec<Chunk> {
+    let mut out = vec![];
+    for mut chunk in entries {
+        if chunk.title.is_empty() {
+            chunk.title = chunk.text.chars().take(60).collect::<String>();
+        }
+
+        if chunk.text.len() <= SPLIT_OVER {
+            out.push(chunk);
+            continue;
+        }
+
+        let mut part = String::new();
+        for para in chunk.text.split("\n\n") {
+            if !part.is_empty() && part.len() + para.len() > SPLIT_OVER {
+                out.push(Chunk {
+                    text: std::mem::take(&mut part),
+                    ..chunk.clone()
+                });
+            }
+
+            if !part.is_empty() {
+                part.push_str("\n\n");
+            }
+
+            part.push_str(para);
+        }
+
+        if !part.is_empty() {
+            out.push(Chunk {
+                text: part,
+                ..chunk
+            });
+        }
+    }
+
+    out
+}
+
+/// One resolved `docs` source: tool-parameter schemas, the searchable
+/// corpus index, and an optional host preamble override.
+pub struct DocsBundle {
+    pub schemas: HashMap<String, Value>,
+    pub index: DocsIndex,
+    pub preamble: Option<String>,
+}
+
+/// The two accepted source shapes: a bare entry array (host inline
+/// entries), or the metadata-bundle object.
+#[derive(Deserialize)]
+#[serde(untagged)]
+enum RawDocs {
+    Entries(Vec<Chunk>),
+    Bundle {
+        #[serde(default)]
+        schemas: HashMap<String, Value>,
+
+        #[serde(default)]
+        chunks: Vec<Chunk>,
+
+        #[serde(default)]
+        preamble: Option<String>,
+    },
+}
+
+/// The lazily-resolved, cached bundle for one configured `docs` source.
+/// Owned by `AgentRuntime` (so it persists across `prompt()` calls) and
+/// shared with each turn's `ToolCtx`.
+pub struct DocsCell {
+    source: JsValue,
+    cache: async_lock::Mutex<Option<Rc<Result<DocsBundle, String>>>>,
+}
+
+impl DocsCell {
+    pub fn new(source: JsValue) -> Self {
+        Self {
+            source,
+            cache: async_lock::Mutex::new(None),
+        }
+    }
+
+    pub async fn bundle(&self) -> Rc<Result<DocsBundle, String>> {
+        let mut cache = self.cache.lock().await;
+        if let Some(cached) = &*cache {
+            return cached.clone();
+        }
+
+        let result = Rc::new(resolve(&self.source).await.map(|raw| {
+            let (schemas, chunks, preamble) = match raw {
+                RawDocs::Entries(chunks) => (HashMap::new(), chunks, None),
+                RawDocs::Bundle {
+                    schemas,
+                    chunks,
+                    preamble,
+                } => (schemas, chunks, preamble),
+            };
+
+            DocsBundle {
+                schemas,
+                index: DocsIndex::build(chunks),
+                preamble,
+            }
+        }));
+
+        *cache = Some(result.clone());
+        result
+    }
+}
+
+fn js_error(err: JsValue) -> String {
+    err.as_string()
+        .or_else(|| {
+            js_sys::Reflect::get(&err, &JsValue::from_str("message"))
+                .ok()
+                .and_then(|x| x.as_string())
+        })
+        .unwrap_or_else(|| format!("{err:?}"))
+}
+
+/// Resolve the `docs` source union to a parsed raw bundle.
+async fn resolve(source: &JsValue) -> Result<RawDocs, String> {
+    let value = JsFuture::from(js_sys::Promise::resolve(source))
+        .await
+        .map_err(js_error)?;
+
+    let text = if js_sys::Array::is_array(&value) {
+        js_sys::JSON::stringify(&value)
+            .map_err(js_error)?
+            .as_string()
+            .ok_or_else(|| "Unserializable `docs` array".to_owned())?
+    } else if let Some(text) = value.as_string() {
+        text
+    } else if value.is_instance_of::<web_sys::Response>() {
+        let response: web_sys::Response = value.unchecked_into();
+        if !response.ok() {
+            return Err(format!(
+                "HTTP {} {}",
+                response.status(),
+                response.status_text()
+            ));
+        }
+
+        JsFuture::from(response.text().map_err(js_error)?)
+            .await
+            .map_err(js_error)?
+            .as_string()
+            .unwrap_or_default()
+    } else if value.is_instance_of::<js_sys::Uint8Array>()
+        || value.is_instance_of::<js_sys::ArrayBuffer>()
+    {
+        let bytes = js_sys::Uint8Array::new(&value).to_vec();
+        String::from_utf8(bytes).map_err(|x| format!("Docs source is not UTF-8: {x}"))?
+    } else if value.is_object() {
+        js_sys::JSON::stringify(&value)
+            .map_err(js_error)?
+            .as_string()
+            .ok_or_else(|| "Unserializable `docs` object".to_owned())?
+    } else {
+        return Err("Unsupported `docs` type".to_owned());
+    };
+
+    serde_json::from_str(&text).map_err(|x| format!("Invalid docs JSON: {x}"))
+}