@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.
Maintainers
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-aiPublic 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 }:onwhen this template calls for it,supportedwhen 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 thehandlesoption (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_FEATURESis 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 orderallocation:{ 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 pointsform:{ 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. WhenplayAtStartis true the author wants the video played once as Begin is pressed: call the element'splay()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 oncectx.chromeStateisstarted.- After
restart()the begin page returns withctx.respondentstill holding the name and email given before; prefill from it.
Station page rules
- Render
ctx.station.questionas 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 inmessages). - Render the control
ctx.answerControlnames.nonemeans no control (Stop station, or a turn in flight). ctx.sdk.stationMediagoes 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 fromctx.station.questionand a Submit button that callsfinish(). - Save and exit. Nothing is written and nothing needs calling: every turn
is saved as it happens, and with
sessionParamthe page URL already names the conversation. The control only has to say so and showresumeUrl. - Start over.
restart()permanently deletes this conversation's answers and returns the page tobeginunder 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.canRetryis true, showctx.sdk.lastErrorwith a button that callsretry(): it asks again for a question that never arrived, on the answer already saved. WhenlastErroris set andcanRetryis false the answer itself was not saved; the respondent sends it again. - Finish early. When
ctx.sdk.stopOfferis 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.promotionCodewhen the template issues one (promotionCodePendingwhile it is being claimed).ctx.sdk.completion.reports—{ generating, items, expected }. When the template shows participant reports,generatingis true until theexpectedrows have arrived (or a bounded wait ends); renderitems[].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; otherwisenull. 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— withshowParticipantReports, 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 tostart({ 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()isfile()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 innotices— 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'sanalysisEngineApiUrlon 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-textand friends on.bf-reportto 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,
docxandjszipincluded); the main entry and/reactnever 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/mpegoraudio/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 itctx.sdk.voice.inputstays 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.jsNo 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 …/shotstest/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
- Bump
versioninpackage.jsonand add the entry toCHANGELOG.md. - Merge to the integration branch as usual.
- Tag the release commit
curious-ai-v<version>and push the tag. ThePublish curious-aiworkflow 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.
