npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@blendification/curious-ai

v0.3.20

Published

Run a Curious AI interview from any web app: the participant protocol (session, stations, turns, submission, completion reports) packaged once, with the surface-context read model the pages render from.

Readme

@blendification/curious-ai

Run a Curious AI interview from any web app. The package carries the participant protocol the Blendification interview page runs — session, stations, turns, submission — so a page built elsewhere (Lovable, a marketing site, an internal tool) lands the conversation in Blendification exactly as /interview/<templateId> would: same rows, same results group, same post-interview processing.

There is no API key. Respondents are anonymous by design. The only configuration is which template the conversation belongs to, plus optionally a results group and an invite-group label — the same things a share link carries.

Install

npm install @blendification/curious-ai

Public on npm, MIT. React 18+ is an optional peer dependency (only the /react entry needs it). In Lovable: ask the agent to add the package, and put this README in the project's knowledge. A Lovable project that loads the /reports entry needs 0.3.7 or later: on an older version its published pages answer 500 (starters/README.md, "On Lovable: a site on a package older than 0.3.7").

import { createCuriousAi } from '@blendification/curious-ai';

const curious = createCuriousAi({ env: 'prod' });          // or 'staging'
const interview = curious.interview({
  templateId: '617441-cv9-771180',
  resultsGroupId: undefined,   // optional: pin the conversation to a results group
  group: undefined,            // optional: invite-group label
});

interview.subscribe(() => render(interview.snapshot()));

await interview.load();                       // → ctx.chromeState === 'begin'
await interview.start({ username: 'Dana', email: '[email protected]' });
await interview.answer('We mostly co-deliver grants.');
await interview.answer({ choice: 'Optimistic' });
await interview.finish();                     // → ctx.chromeState === 'complete'

React:

import { useCuriousInterview } from '@blendification/curious-ai/react';

function InterviewPage({ templateId }) {
  const { ctx, start, answer, advance, finish, finishEarly, retry, restart, resumeUrl } = useCuriousInterview({
    env: 'prod',
    templateId,
    sessionParam: 'session',   // keeps the conversation id in the URL: refresh and return visits resume
    handles: ['resume', 'saveAndExit', 'restart', 'retry', 'finishEarly', 'consent'],
  });
  if (ctx.chromeState === 'begin')    return <BeginPage ctx={ctx} onStart={start} />;
  if (ctx.chromeState === 'started')  return <StationPage ctx={ctx} onAnswer={answer} onFinish={finish} onRestart={restart} resumeUrl={resumeUrl} />;
  if (ctx.chromeState === 'complete') return <SubmissionPage ctx={ctx} />;
  if (ctx.chromeState === 'inactive') return <Closed />;
  return <Unavailable error={ctx.loadError} onRetry={ctx.sdk.canRetry ? retry : null} />;
}

What the page owes the respondent

The platform's own interview page does more than ask and answer, and a page built elsewhere has to draw the same things itself. The package knows the list for each template and says it three ways:

  • ctx.sdk.features.<id> is { on, supported }: on when this template calls for it, supported when the package can do it.
  • At load() the session logs one console notice naming every feature that is on and that the page has not declared, with what to draw and what to call. Declare what the page handles with the handles option (an id list, or 'all'); the notice shrinks as the page gains them and disappears when none is left. A feature that is on but not supported is always named, so the author hears that a hosted page will not have it.
  • hostChecklist(ctx.sdk.features, handles) returns the same list in code; HOST_FEATURES is the catalog.

| id | Applies | The page draws | It reads or calls | |---|---|---|---| | resume | every template | nothing visible; the conversation id is in the page URL from the first turn | sessionParam: 'session' on the hook (or sessionId + ctx.sdk.sessionId yourself) | | saveAndExit | every template | a "Save and exit" control: the answers are saved, this link brings you back | resumeUrl from the hook; nothing to call | | restart | every template | "Start over", behind a confirmation that the answers will be deleted | restart() while ctx.sdk.canRestart | | retry | every template | ctx.sdk.lastError (or the unavailable notice) with "Try again" | retry() while ctx.sdk.canRetry | | finishEarly | every template | "Finish and submit" and "Keep going" | finishEarly() while ctx.sdk.stopOffer | | consent | every template | the consent wording by the Begin button | ctx.sdk.consentStatement | | language | the template's language is not English | the page's own words (buttons, labels, placeholders, the stop-offer buttons) in that language; the questions already arrive in it | ctx.sdk.language (code for <html lang> and dictation) | | languageChoice | respondentLanguages set | a language switch on the begin and station pages, each language in its own name | ctx.sdk.languages, setLanguage(code) | | supportContact | supportContactEmail set | "Contact for support" | ctx.parameters.supportContactEmail | | stationMedia | a station has media | the image or video above the question | ctx.sdk.stationMedia | | beginMedia | the Begin station has media | the image or video on the begin page; a playAtStart video plays once when Begin is pressed | ctx.sdk.beginMedia | | reports | showParticipantReports | the reports on the submission page | ctx.sdk.completion.reports | | promotionCode | promotionCodesEnabled | the code on the submission page | ctx.sdk.completion.promotionCode | | redirect | redirectUrl set | a button to the author's URL, never an automatic redirect | ctx.parameters.redirectUrl | | voiceInput | the author switched it on | a microphone by the text box; the transcription lands in the box to send | ctx.sdk.voice.input, createRecorder() + transcribe(blob) — see Voice | | voiceOutput | the author switched it on | a voice control (Off / Male / Female) and each new question read aloud | ctx.sdk.voice.output, speak(text, { voice }) + playAudio() — see Voice | | liveAvatar, accountSignIn | the author switched it on | nothing: not supported on a hosted page | supported: false |

What a page reads: snapshot()

The snapshot is the interview page's own surface context (buildSurfaceContext), plus an sdk block. Everything is a resolved value; a page renders and compares, it never re-derives.

| Field | Meaning | |---|---| | chromeState | Which page: begin · started · complete · inactive · unavailable | | isLoading | Show a loading overlay on top of the current page | | station | { id, tag, label, question, mediaSource, isStop } — the active station | | answerControl | Which control to render: none · fixed · form · text | | responseType | text · choice · choices · scale · ranked · allocation · form | | responseOptions | [{ id, label, value, kind, imageS3Key, imageUrl }] for the fixed control | | formItems | [{ id, name, type, choices, options, sessionField }] for the form control | | sections | The respondent's walk: [{ id, tag, label, index, isStop, state }], state ∈ complete/active/upcoming | | messages | The transcript: { id, role, content, stationId, label, order } | | followUpCount | Follow-ups asked on the active station so far | | goalProgress | { level, fraction, covered, required } or null — how much of the station's goal is covered (never what is missing) | | processingMessage | The "thinking" copy while a turn runs, or null | | theme | The template's stock colours, if the author set any | | templateName, parameters | Template name and its raw parameters | | respondent | { username, emailid } once collected | | loadError | { subject: 'template'\|'interview', kind: 'notfound'\|'unreachable' } when unavailable | | sdk.status | ready when the respondent may answer; waiting / posting during a turn; loading; inactive; unavailable | | sdk.access | What the begin page must collect: { anonymous, needsName, needsEmail, unsupported } | | sdk.stationMedia | { url, kind: 'image'\|'video' } for the station's media, resolved, or null | | sdk.beginMedia | { url, kind, playAtStart } for the Begin station's media, or null | | sdk.consentStatement | The consent wording for the begin page: the author's, else the platform default with the template's support address | | sdk.language | { name, code, nativeName }: the language the conversation is held in ("Spanish", "es", "Español"), or null when the template names none. The engine writes its questions, greeting and stop offer in it; Fixed questions, choice options and form labels show as the author wrote them | | sdk.languages | The languages the respondent may switch to with setLanguage, in the same shape; empty when the template offers no choice | | sdk.features | { [id]: { on, supported } } — what this template expects the page to offer (see above) | | sdk.canRetry | Show "Try again" and call retry() | | sdk.canRestart | Show "Start over" (behind a confirmation) and call restart() | | sdk.lastError | What went wrong on the last action, in words a respondent can read, or null | | sdk.stopOffer | The engine offered to finish early — show "finish and submit" (finishEarly()) and "keep going" | | sdk.completion | { promotionCode, promotionCodePending, metaProcessing } after finish() | | sdk.sessionId | The interview id. The hook's sessionParam keeps it in the URL; without the hook, put it there yourself and pass it back as interview({ templateId, sessionId }) |

Answering

answer(input) accepts, by answerControl / responseType:

  • text: 'free text' or { text }
  • choice: { choice: 'Optimistic' } (label or option id); an "Other" option takes { choice: 'Other', other: 'free text' }
  • choices: { choices: ['Optimistic', 'Concerned'] }
  • scale: { scale: 4 }
  • ranked: { ranking: ['b', 'a', 'c'] } — every option, in rank order
  • allocation: { allocation: [40, 35, 25] } — points per option in display order adding up to 100 (or { label: points }); { allocation: 'decline' } records that the respondent would not split the points
  • form: { form: { [itemId]: value } } — text, number, label, or list per item

A template can assign one text item of a form to the respondent's name and one to the respondent's email. Those items arrive with sessionField: 'name' or 'email' (null on every other item); render them as a name or an email input. answer({ form }) writes what was typed there to the conversation itself as well: its name, the email its reports are sent to, and, on a template that began anonymous, it stops being anonymous once either is filled in. Left blank, nothing changes. A malformed email throws before anything is written. A field the start form already collects (needsName, needsEmail) is never taken from a form, so no item is marked for it.

An option that is not on the question throws before anything is written. Optional responseTimeMs, keystrokeData and source: 'voice' ride along for analytics.

The next question reaches subscribe listeners (and snapshot()) the moment the engine answers, in one update with its station, answer options and ready; it is saved just after. Render from subscribe. answer() itself resolves once that turn is saved, and answering again before then is safe: the new answer waits for the previous turn.

A slow engine does not end a turn. Past the template's responseTimeout (default 10 s) the turn is recorded as slow and nothing else changes: the page stays on waiting with its progress line, and the engine's answer is the one posted when it arrives. A turn ends without the engine only when the engine call itself does: an error, or no answer within 45 s (four times responseTimeout when that is longer, up to 3 minutes). Then the answer the engine wrote down is used if there is one, and otherwise the fallback question is posted. A connection lost in the middle of a turn is not an ending either: the engine keeps working, so the page stays on waiting and looks for its written answer every 2 seconds for the rest of that allowance. An engine that says nothing at all is treated the same way: when a request has gone out and not one frame has come back for responseTimeout (never less than 10 s), the page stops listening and looks for the engine's record of the turn. If there is none, the engine never took the turn and the fallback question is posted about 2 seconds later; a working engine sends its first frame within about a second, so a turn that is merely slow is never silent. The stock page follows the same rules. Before 0.3.8 the fallback was posted at responseTimeout and the engine's answer discarded, and before 0.3.9 a lost connection posted it at once; either moved a respondent off a station that had more to ask.

Letting the respondent move on

A station ends when the engine decides it should: its follow-up limit is reached, its goal reads as met, or more probing looks unproductive. A page can also let the respondent decide, with a control of its own:

<button disabled={ctx.sdk.status !== 'ready'} onClick={() => advance()}>Continue</button>

advance() moves to the next station at once. It is the respondent saying "next", and it is not left to the engine: no follow-up limit, goal or model output keeps them on the station. A respondent message is still recorded, so the transcript reads as a conversation ("Let's move on to the next topic." by default; pass advance({ text }) to word it yourself, or in another language), and the engine answers it with the next station's opening question. The recorded message is marked as not typed, the way a voice answer is, and it is not scored as an answer.

Nothing in a template turns this on, and no host is required to offer it. Show the control where the conversation calls for one, for example on stations written to run for as long as the respondent has more to say. It resolves false, and does nothing, before the conversation starts, on a Stop or Processing station, and while a turn is under way. Where a station branches, the engine still chooses the branch.

Letting the respondent choose the language

A template can let the respondent hold the conversation in another language. The author lists the languages in parameters.respondentLanguages (over MCP: update_template_settings with parameters: { respondentLanguages: ["Spanish"] }); the template's own language is always one of them. The page then draws a switch from ctx.sdk.languages and calls setLanguage:

{ctx.sdk.languages.length > 1 && ctx.sdk.languages.map((l) => (
  <button key={l.code ?? l.name} aria-pressed={ctx.sdk.language?.code === l.code} onClick={() => setLanguage(l.code ?? l.name)}>
    {l.nativeName}
  </button>
))}

The switch applies from the next message. Chosen before Begin, the opening question arrives in it too; chosen mid-way, the questions already asked stay as they were. The engine writes every later question, its greeting and its stop offer in the chosen language; what the author wrote word for word (Fixed questions, choice options, form labels, the Stop station's text) shows as written. The choice is saved on the interview's notes, so a refresh or a return visit keeps it. interview({ language }) opens the conversation in a language the template offers; setLanguage resolves false, changing nothing, for a language it does not offer. The page's own words are the page's to translate.

Begin page rules

  • ctx.sdk.access.needsName — ask for a name unless the template is anonymous.
  • ctx.sdk.access.needsEmail — the template requires an email.
  • ctx.sdk.access.unsupported === 'requireAcct' — the template requires a Blendification sign-in; start() refuses. Use an anonymous or email-gated template.
  • ctx.parameters.beginMessage — author-provided copy, if set.
  • ctx.sdk.consentStatement — always present once the template is read: the author's consent wording, or the platform default. Show it by the Begin button.
  • ctx.sdk.beginMedia — the Begin station's image or video. When playAtStart is true the author wants the video played once as Begin is pressed: call the element's play() inside the click handler (a browser only allows sound from a user gesture), keep it up while the first question is prepared, and offer Continue once ctx.chromeState is started.
  • After restart() the begin page returns with ctx.respondent still holding the name and email given before; prefill from it.

Station page rules

  • Render ctx.station.question as the current ask only when there are no messages for the station yet; otherwise the latest assistant message is the question (Adaptive follow-ups exist only in messages).
  • Render the control ctx.answerControl names. none means no control (Stop station, or a turn in flight).
  • ctx.sdk.stationMedia goes above the question when present; it is the stimulus the question refers to, not decoration.
  • A Stop station (ctx.station.isStop) shows the closing copy from ctx.station.question and a Submit button that calls finish().
  • Save and exit. Nothing is written and nothing needs calling: every turn is saved as it happens, and with sessionParam the page URL already names the conversation. The control only has to say so and show resumeUrl.
  • Start over. restart() permanently deletes this conversation's answers and returns the page to begin under the same conversation id, so the link a respondent holds keeps working. Put it behind a confirmation. It is refused once the interview is submitted; if it fails part-way (ctx.sdk.lastError), calling it again finishes the job.
  • Try again. When ctx.sdk.canRetry is true, show ctx.sdk.lastError with a button that calls retry(): it asks again for a question that never arrived, on the answer already saved. When lastError is set and canRetry is false the answer itself was not saved; the respondent sends it again.
  • Finish early. When ctx.sdk.stopOffer is true the engine has enough: show "Finish and submit" (finishEarly()) and "Keep going" (hide the offer).

Submission page rules

  • ctx.parameters.endMessage, redirectUrl, redirectButtonLabel, redirectMessage — author-provided; show the redirect as a button, never auto-redirect.
  • ctx.sdk.completion.promotionCode when the template issues one (promotionCodePending while it is being claimed).
  • ctx.sdk.completion.reports — { generating, items, expected }. When the template shows participant reports, generating is true until the expected rows have arrived (or a bounded wait ends); render items[].content (markdown) and, for chart reports, reportFeatures(report.id) for the dimensions. Every report the template names is generated whether or not it is shown; they also land in the results group. To show a report formatted and themed, or offer its download, use @blendification/curious-ai/reports (next section) rather than rendering the markdown yourself.
  • ctx.sdk.summary — the conversation summary, only when the template shows reports to participants; otherwise null. It is written for the owner after every completion, and the app's own submission screen never displays it, so a host page should not either unless the author turned reports on.
  • ctx.parameters.emailReportsOnComplete — with showParticipantReports, the participant is emailed a link to their reports once the first one is saved. The platform sends it, once per conversation, to the address given to start({ email }); an interview started without one gets no email. The page has nothing to do and need not stay open. The link opens the Blendification interview page (/interview/<templateId>/<interviewId> on the platform), not the host's own page — the participant sees the platform's completion screen with the report downloads. A host that wants participants back on its own page should leave this off and send its own email.
  • ctx.parameters.disableConversationDownload — the author hid the transcript download on the completion screen; a host that offers one should honor it.

Reports: view and download

@blendification/curious-ai/reports delivers a completion report the way the app's own submission screen does: the report template's layout for its category, the brand theme the template chose (colours, logo, a Radar Chart's branded scorecard with its native Word chart), the template's Word cover page in front, and Word or PDF as the template chose. The document is built in the browser by the app's own generator, bundled into the package, so it is the same file a respondent downloads in Blendification. No key or session is involved: everything it reads was staged for respondents when the report was produced, and every call is scoped to the respondent's own interview.

import { createReportDocuments } from '@blendification/curious-ai/reports';

const reports = createReportDocuments(interview);   // the InterviewSession (the hook returns it as `interview`)
const { items } = interview.snapshot().sdk.completion.reports;

// On the page: themed HTML, escaped throughout, styles scoped under .bf-report.
const { html } = await reports.view(items[0]);
container.innerHTML = html;

// A download button: Word or PDF as the template chose.
const outcome = await reports.download(items[0]);
if (outcome.notices.length) showNotice(outcome.notices.join(' '));

// The formatted document itself, in a frame (always PDF: a browser cannot show Word).
const { url, revoke } = await reports.preview(items[0]);
if (url) frame.src = url;             // revoke() when the frame goes; null url → use view()
  • file(report) returns { blob, filename, format, fellBack, notices } for a page that stores or uploads the file itself; download() is file() handed to the browser. { format: 'docx' | 'pdf' } overrides the template.
  • Never a lost download. A PDF that cannot be made arrives as the Word file (fellBack: true); a cover that cannot be added costs the cover. Both put a sentence for the reader in notices — show it.
  • PDF goes through interview-support's public convertDocumentToPdf (the respondent route, reachable from any allowed website), falling back to the analysis engine at the discovery document's analysisEngineApiUrl on a backend deployed before that action existed.
  • view() carries the brand through text, table headers and the chart, and nothing else; override --bf-report-accent, --bf-report-text and friends on .bf-report to fit the page. renderReportHtml(report, { scorecard, brand }) is the pure renderer underneath.
  • In React: const reports = useMemo(() => createReportDocuments(interview), [interview]).
  • The subpath carries the document code (about 1 MB before a host minifies it, docx and jszip included); the main entry and /react never load it. The package has no dependencies of its own to install or resolve.

Voice

When the template has voice input or output on, ctx.sdk.voice says what to draw: input (a microphone) and output (a voice control), plus the template's speech service. The platform page offers exactly these two.

import { createRecorder, playAudio } from '@blendification/curious-ai/voice';

// Input: record on a click, transcribe, let the respondent send it.
const rec = createRecorder();
await rec.start();                          // mic button pressed
const text = await interview.transcribe(await rec.stop());   // pressed again
setDraft(text);                             // or answer(text) straight away

// Output: once the respondent picks a voice, read each new question aloud.
let playing = null;
playing?.stop();
playing = playAudio(await interview.speak(lastAssistant.content, { voice: 'female' }));
  • transcribe(blob) uploads the recording (webm, ogg, mp4/m4a, mp3, wav or flac, up to 25 MB) and returns the text, in the conversation's language. It goes through the same upload and transcription the platform page uses, scoped by the interview and the template's allowed domains.
  • speak(text, { voice }) reads the text with the template's speech service (voice: 'male', 'female', a voice id, or omitted for the service's default) and resolves with the whole clip, audio/mpeg or audio/wav. Formatting is stripped first. onChunk(bytes, format) sees each piece as it arrives, for a page that streams playback itself.
  • Browsers allow the microphone and sound only after the respondent has clicked or typed on the page. Start recording from the click itself; the voice control's first choice counts as the interaction that later playback needs.
  • isRecordingSupported() says whether this browser can record at all; hide the microphone when it cannot.
  • Voice input needs the environment's aiServicesRestUrl (published in the discovery document since this release's backend); without it ctx.sdk.voice.input stays false.

Processing stations

A station whose guide is Processing is a system step: the SDK asks the engine for the station's artifact (summary / scorecard / poll), records it as the station's only message, and advances on its own — to the next station's opening question, the next processing step, the Stop screen, or straight to submission when nothing follows. A page renders the artifact like any other assistant message; answerControl is none throughout.

Typing telemetry

useKeystrokeAnalytics() (from @blendification/curious-ai/react) is the app's own typing-analytics hook. Spread its handlers onto the textarea and pass JSON.stringify(finalize()) as keystrokeData (with timestamps.totalMs as responseTimeMs) to answer(); the row then carries the same telemetry the stock page records.

Lifecycle

answer() resolves once the respondent can act again — after the next question is posted and after any Processing step it landed on has run. Call interview.dispose() when a page unmounts (the React hook does) to stop background report polling.

Without React, the resume link is two helpers: sessionIdFromUrl(location.href) for the id to pass as sessionId, and urlWithSessionId(location.href, ctx.sdk.sessionId) for the URL to history.replaceState once it exists.

TypeScript

Declarations ship in types/; import type { Snapshot } from '@blendification/curious-ai'.

Starters

starters/ holds finished interview pages to begin a site from: research (a study that asks for considered answers) and feedback (customer feedback for a brand), both built on starters/kit, which draws everything under "What the page owes the respondent" and every answer control. They are source to copy into a project and restyle, not something to import. On a preview or local address each also offers a "Survey preview": every page of the design on sample content, with nothing sent or saved, so a site can be reviewed without holding a conversation. starters/README.md says how, and what the kit covers.

Reference surface

demo/ is the plainest React that drives every verb: begin, station and submission pages. Build it with scripts/dev-utils/build-curious-ai-demo.mjs and serve the output with scripts/dev-utils/serve-static.mjs.

Media

Stimulus media (a station's image or video, a choice option's artwork) lives in Blendification and arrives resolved: sdk.stationMedia.url, responseOptions[].imageUrl. Presigned image URLs last an hour; the snapshot re-resolves them when the station changes. Decorative art — backgrounds, illustrations, icons — belongs to the page.

Allowed domains

By default any website can host a template's interview, as a share link allows. A template can restrict that: Template Options → Theme → Hosted pages (or allowedOrigins through template_settings_update over MCP) lists the origins allowed — https://acme.com, or *.lovable.app for every subdomain. Blendification's own domains are always allowed.

On a website the template does not list, load() ends unavailable with ctx.loadError.kind === 'origin-not-allowed' and ctx.loadError.message naming the domain and where the owner adds it. Show the message; retrying cannot help. The same check covers the conversation and its reports, PDF conversion included.

While building in Lovable, list the preview domain (*.lovable.app) as well as the published one, then remove it at launch.

The check reads the browser's Origin, so it decides which websites can run the interview in a visitor's browser. It is not authentication: a script outside a browser can claim any origin, and the conversation id stays the only credential a respondent holds.

Invites that open the page

A known group of respondents can be invited by email from Blendification (Template Builder → Send invites, with reminders from the Deployment panel) and still answer on the hosted page. The template owner sets the page's address under Template Options → Theme → Hosted pages (hostedPageUrl through template_settings_update over MCP). Each invite then creates the conversation and links to <hostedPageUrl>?session=<conversation id>; reminders and the participant report email carry the same link.

Nothing on the page changes for this. sessionParam: 'session' (the default) reads the id, load() finds the conversation not started with the respondent's name and email already on it, and start() continues it. A page that renames sessionParam does not receive invite links. When the template lists allowed domains, the page's domain has to be one of them.

Where a conversation was held

Each conversation records the page it was held on, so its owner can tell a conversation run on another website from one run in Blendification. The backend takes the website from the browser's Origin; the package adds the page path (location.pathname — never the query string or the fragment, which can carry respondent ids). The first page recorded stays: a conversation reopened somewhere else was still held where it began. The owner sees it under Session Notes as "Hosted on". Nothing to wire.

Configuration

createCuriousAi({ env }) fetches https://<app origin>/.well-known/curious-ai.json for prod (blendification.app) or staging (uat.blendification.app). A missing or malformed document throws and names the URL; there is no baked fallback. createCuriousAi({ endpoints }) skips discovery for scripts that already know them.

Not yet supported

Templates with requireAcct; Poll stations (multi-speaker sessions); the live avatar.

Development

npm test          # builds dist/report-documents.js, then node --test test/*.test.js

No network in tests. test/driftFromApp.test.js keeps the modules copied from apps/fusion-analytics identical to their originals.

dist/report-documents.js is not copied: scripts/build-reports.mjs bundles the app's report generator (Lucidity/AnalysisReport/ReportGenerator.js and reportDocx/) with esbuild, swapping the app services it imports for bundle/shims/. It is built by npm run build, npm test and prepack, and is never committed. The build fails if the generator gains an app import outside the allowed list, so a new service cannot pull the app's store or auth into the package unnoticed; shim it deliberately. Run the repo's npm ci first — the bundle resolves @blendification/shared-data and @blendification/report-doc from the workspace.

The starters are source nothing imports, so test/starters.test.js holds what a copy depends on (they ship, they need only React and this package, the kit declares every supported host feature, each still bundles). To see them, and after any change to one, walk both through a whole conversation in a browser on the test suite's fake backend:

node demo/starters/build.mjs      # → scripts/tmp/curious-ai-starters/index.html?starter=research|feedback
node demo/starters/walk.mjs       # drives both in Chromium, desktop and phone; screenshots in …/shots

test/starterTypes.test.js type-checks them against types/ the way a host compiles a copy: TypeScript with the strictest settings a host is known to build with (a Lovable site's and Vite's react-ts template's together), on React 18's types and on React 19's.

Releasing

  1. Bump version in package.json and add the entry to CHANGELOG.md.
  2. Merge to the integration branch as usual.
  3. Tag the release commit curious-ai-v<version> and push the tag. The Publish curious-ai workflow verifies the tag matches the version, runs the tests, packs, and publishes with --access public.

The first publish uses an NPM_TOKEN repository secret (npm only lets a package be bound to a Trusted Publisher once it exists). After it, configure this workflow as the package's Trusted Publisher on npmjs.com and delete the secret; later releases authenticate with OIDC and no token exists anywhere.