@sparkletree/core 0.1.0 → 0.1.1

package/README.md

@@ -1,12 +1,13 @@
 # @sparkletree/core
 
-The framework-agnostic half of the SparkleTree SDK. Wire protocol, copy
-choreography, theme, trust chrome, analytics, variant pinning, audio.
+Framework-agnostic client for [SparkleTree](https://sparkletree.io): stream
+adaptive campaign text into your site, with copy that renders immediately,
+theme tokens, and built-in impression analytics.
 
-**This is the only thing that speaks the wire.** If you are building a React
-app, install [`@sparkletree/react`](https://www.npmjs.com/package/@sparkletree/react)
-instead — it depends on this. Reach for `core` directly when you are wiring up
-Vue, Svelte, Solid, or plain DOM.
+**Building a React app?** Install
+[`@sparkletree/react`](https://www.npmjs.com/package/@sparkletree/react)
+instead — it wraps this package. Use `core` directly with Vue, Svelte, Solid,
+or plain DOM.
 
 ```bash
 npm install @sparkletree/core
@@ -25,11 +26,11 @@ const handle = openStream({
     island: "hero",
   },
   // Required. This is what the visitor reads if the network is slow, the
-  // campaign is paused, or generation fails. Write it as the only version.
+  // campaign is paused, or generation fails — so write it as copy you would
+  // ship on its own.
   initial: { headline: "Software that meets the moment" },
-  // True when that copy is ALREADY on screen (SSR, or carried across a
-  // navigation). It changes the choreography: copy a reader can see is never
-  // typed over.
+  // Set true when that copy is already visible (server-rendered, or carried
+  // across a navigation). Text a reader can see is never typed over.
   initialIsOnScreen: false,
   onState: (state) => {
     const { marked } = decideChrome(state.contentSource, false);
@@ -41,59 +42,61 @@ const final = await handle.finished;
 handle.close();
 ```
 
-`openStream` returns `{ choreographer, finished, close }`. `choreographer.getState()`
-is the current state; `finished` resolves with the terminal state; `close()`
-aborts the request and releases timers.
+`openStream` returns `{ choreographer, finished, close }`.
+`choreographer.getState()` is the current state; `finished` resolves with the
+terminal state; `close()` aborts the request and releases timers.
 
-## What you get
+## What's in the box
 
 | Export | |
 |---|---|
-| `openStream` | The client. Opens the SSE stream and drives the choreographer. |
-| `fetchContent` | Fetches `/content`. **Nothing calls it** — `openStream` does not, and the React path does not. Exported for consumers who want a first-paint fetch of their own. |
-| `CopyChoreographer`, `COPY_FIELDS`, `COPY_HOLD_MS` | The state machine, if you want to drive it yourself. |
-| `SseParser`, `readSseStream` | SSE parsing, usable standalone. |
-| `decideChrome`, `viewerPrefersStandard`, `setViewerPrefersStandard`, `STANDARD_MODE_KEY` | Trust chrome decisions. |
-| `applyTheme`, `themeStyle`, `tokenName`, `tokenSource`, `TOKEN_PREFIX` | Theme tokens. |
-| `track`, `ImpressionRecorder`, `observeVisibility`, `sessionId` | Analytics. |
-| `pageVariants`, `VariantRegistry`, `RESERVATION_TIMEOUT_MS` | Variant pinning — one page view, one variant. |
-| `mountAudio`, `activePlayer`, `destroyActiveAudio` | Audio engine (no chrome). |
-| `buildStreamUrl`, `buildContentUrl`, `negotiatedProtocol`, `PROTOCOL_*`, `SDK_PARAM`, `VARIANT_PARAM` | Protocol. |
+| `openStream` | Opens the stream and manages copy state for you. |
+| `fetchContent` | One-shot fetch of campaign content, for a first-paint fetch of your own. Not used by `openStream`. |
+| `CopyChoreographer`, `COPY_FIELDS`, `COPY_HOLD_MS` | The copy state machine, if you want to drive it yourself. |
+| `SseParser`, `readSseStream` | Server-sent-events parsing, usable standalone. |
+| `decideChrome`, `viewerPrefersStandard`, `setViewerPrefersStandard`, `STANDARD_MODE_KEY` | Whether to show the AI-adaptation mark, and the viewer's opt-out. |
+| `applyTheme`, `themeStyle`, `tokenName`, `tokenSource`, `TOKEN_PREFIX` | Theme tokens delivered with the campaign. |
+| `track`, `ImpressionRecorder`, `observeVisibility`, `sessionId` | Impression analytics. |
+| `pageVariants`, `VariantRegistry`, `RESERVATION_TIMEOUT_MS` | Variant pinning — one page view sees one variant. |
+| `mountAudio`, `activePlayer`, `destroyActiveAudio` | Audio playback (no UI). |
+| `buildStreamUrl`, `buildContentUrl`, `negotiatedProtocol`, `PROTOCOL_*`, `SDK_PARAM`, `VARIANT_PARAM` | Protocol plumbing. |
 
 ## Copy state
 
 `state.fields.{greeting,headline,body,cta}` each carry
-`{ text, source, mode, typing, settled }`, already choreographed — you render
-`text` and honour `typing`/`settled` for presentation only. Alongside them:
+`{ text, source, mode, typing, settled }`, already sequenced for display — you
+render `text` and use `typing`/`settled` for presentation only. Alongside them:
 `phase`, `error`, `rewrites`, `contentSource`, `degraded`, `variantId`,
 `theme`, `layout`, `backgroundImage`, `videoUrl`, `sequence`, `ctaStyle`,
 `ctaAction`, `meta`.
 
 `phase` moves `idle → holding? → live → settled | failed`. Nothing throws and
-nothing blanks: on `failed`, whatever was painted stays painted and undelivered
-fields fall back to your `initial` text.
+nothing goes blank: on `failed`, whatever was painted stays painted, and
+undelivered fields fall back to your `initial` text.
 
-## The rules this enforces for you
+## What the client guarantees
 
-1. **First paint is real copy.** No skeleton, and no option for one.
+1. **First paint is real copy.** Your `initial` text renders immediately —
+   there is no skeleton state.
 2. **Copy changes at most once.** Text a reader may be mid-sentence on is never
-   wiped and retyped. Deltas aimed at copy already on screen buffer off-canvas
-   and land once, composed.
-3. **The server declares delivery mode**; the client never guesses from timing.
-4. **Adapted copy is marked.** `decideChrome` returns `marked` for `generated`
-   and `cached`, never for `static`. Marking authored copy as adapted is a
-   worse failure than not marking adapted copy.
+   wiped and retyped; updates aimed at visible text are composed off-screen and
+   land in one step.
+3. **The server declares how content was produced** (static, cached, or
+   generated); the client never guesses from timing.
+4. **AI-adapted copy is always marked.** `decideChrome` returns `marked` for
+   generated and cached content, never for static — so readers can tell
+   adapted text from authored text.
 
-Full documentation, including the React quickstart and the reasoning behind
-each rule, is in the [SDK README](https://gitlab.com/sparkletree/sparkletree-sdk/-/blob/main/README.md).
+Full documentation:
+[docs.sparkletree.io](https://docs.sparkletree.io/developers/sdk/core/)
 
 ## Requirements
 
 ES2022, **ESM only**, Node >= 18. `fetch`, `ReadableStream` and
-`AbortController` must exist — inject `fetchImpl` if you need to substitute
-them. No dependencies.
+`AbortController` must exist — inject `fetchImpl` to substitute them. No
+dependencies.
 
-There is no `require` export condition, which is worth knowing in two places:
+There is no `require` export condition, which matters in two places:
 
 - **From CommonJS**, `require("@sparkletree/core")` fails on Node 18 with
   `ERR_REQUIRE_ESM`. Use `await import("@sparkletree/core")`. (Node 26 loads it
@@ -101,5 +104,4 @@ There is no `require` export condition, which is worth knowing in two places:
 - **In TypeScript**, `moduleResolution: "bundler"` resolves cleanly. So does
   `"node16"`/`"nodenext"` *if your own package.json has `"type": "module"`*.
   Without it you get `TS1479` telling you to use a dynamic import — accurate,
-  not a false positive, and the most likely way a Node backend meets this
-  package.
+  not a false positive.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sparkletree/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Framework-agnostic core for the SparkleTree SDK: wire protocol, copy choreography, theme, analytics, audio.",
   "license": "MIT",
   "type": "module",