@tinkerlandai/longplay-sdk 0.0.0-stage → 0.10.4

package/README.md

@@ -1,3 +1,486 @@
-# Temporary Holding Version
+<p>
+  <a href="https://longplayai.com">
+    <img src="https://longplayai.com/brand/indiana-mark.png" alt="Longplay" width="72" height="72" />
+  </a>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @tinkerlandai/longplay-sdk
+
+This source checkout is SDK 0.10.4, protocol 0.10. These examples use `https://api.longplayai.com` with a Sandbox App and credentials issued by the production deployment. Sandbox still contains production data; do not reuse credentials from the separate test deployment. Confirm runtime readiness in [environment state](../../docs/development-status.md) before running them.
+
+[简体中文](./README.zh-CN.md)
+
+The Longplay business SDK groups its capabilities as **Identity, Commerce, experimentation engine, Analytics, Delivery (Offering, Paywall, Page, Popup and Banner), and Funnel**, over shared protocol, transport, configuration, rendering and recovery foundations. These responsibilities follow the existing L0–L4 architecture; language packages and entry points implement different subsets. The browser/native client and merchant-server entries share contracts and core behavior while retaining separate credentials and allowed operations. Indianapolis is the backend runtime they call; it is not the merchant's server SDK.
+
+**IAM source scanning, generation, validation and upload belong to the independent build package `@tinkerlandai/longplay-iam`.** This business SDK retains only the runtime release binding used by GB visual changes. See [SDK boundaries](../../docs/sdk-architecture.md) and the [IAM package](../iam/README.md).
+
+```sh
+npm install --save-exact @tinkerlandai/longplay-sdk@latest
+```
+
+The first install resolves latest and saves an exact package.json version. Commit the lockfile and use npm ci for later builds. Use the original package identity and exact version from the [release records](../../docs/sdk-releases.md) for historical installations and rollback. New Longplay package names require their own publication; source changes do not publish artifacts.
+
+This SDK requires HTTP protocol 0.10. The runtime must serve the same current protocol; publishing a package does not deploy the server. Publication and accepted environment scope are recorded in the [release ledger](../../docs/sdk-releases.md) and [development status](../../docs/development-status.md).
+
+The data/session layer handles public JSON, integrity checks and authenticated operations. The presentation host composes that layer with the packaged screen renderer; the renderer receives supplied data and emits action intents. Client display entry points load presentation lazily. The `/server` entry has no screen presentation dependency and uses a scoped Server Key only on your backend. A local SDK guard never replaces runtime authorization or verified payment completion. Console preview supplies simulated data/session results to the same presentation host.
+
+## Plain HTML / script installation
+
+The classic-script entry reuses the npm browser implementation, with no bundler:
+
+```sh
+SDK_MODULE_URL="$(curl -fsS https://longplayai.com/sdk/module)" &&
+printf 'export * from "%s";\n' "$SDK_MODULE_URL" > longplay-sdk.js
+```
+
+```html
+<script type="module">
+  import {
+    createLongplay,
+    createPaywallSession,
+    showPaywall,
+    createFunnelRunController,
+    showFunnelRun,
+    mountContent,
+  } from "./longplay-sdk.js";
+  const client = createLongplay({
+    baseUrl: "https://api.longplayai.com",
+    scope: { projectId: "<APP_UUID>", environment: "sandbox" },
+  });
+  // Obtain the complete session pair from your authenticated backend.
+  // client.identify(session);
+  // await client.readHoldings();
+  // client.track("page_viewed", { page: location.pathname });
+  // await client.flush();
+</script>
+```
+
+Commit the generated longplay-sdk.js to lock the immutable module URL; resolve it again only when upgrading. The optional classic loader at `https://longplayai.com/sdk.js` still follows Web releases and uses matching API/credentials. `Longplay.ready` provides every root browser export plus `createPageExperiments` and `createVisualExperiments`; replace npm imports below with destructuring those names. Loading activates no sessions, events or experiments. Server Keys remain on your backend; Funnel start/recovery and logout cleanup retain the existing contracts. Duplicate tags share readiness, failures reject the Promise and UI loads lazily. With `async`/`defer`, wait for the loader tag's load event before accessing `Longplay`. CSP must allow the script origin and API connections. Page experiments use the same script entry; explicitly create their clients and call `start()`. See [script distribution](../../docs/sdk-architecture.md#web-script-distribution) and [the complete integration example](https://longplayai.com/docs/javascript#script).
+
+## React Native core
+
+Use the independent `@tinkerlandai/longplay-react-native` package. The `@tinkerlandai/longplay-sdk/react-native` subpath shares the same implementation. Both support Customer Token identity, holdings, entitlement checks and usage reporting through your authenticated backend. It requires no DOM or native UI/store bridge. See [mobile SDK installation and examples](../../docs/mobile-sdk.md).
+
+## Version compatibility and support
+
+During `0.x`, only the current protocol is supported. Starting with `1.0`, compatibility is preserved within each stable major version. Once the next stable major is published, the preceding stable major remains supported for at least 12 calendar months, with at least 180 days' public notice before retirement. The later deadline applies. See the [support policy](https://longplayai.com/docs/release-notes#support-policy).
+
+The SDK sends current protocol and SDK version headers and validates the protocol declared by successful responses. Old 0.x protocols are not converted into the current contract. Updating source code does not change an existing npm artifact or deploy a server.
+
+## Public entry points
+
+| Import                                   | Purpose                                                                            |
+| ---------------------------------------- | ---------------------------------------------------------------------------------- |
+| `@tinkerlandai/longplay-sdk`              | Browser Customer, Funnel, Feature, and standalone Paywall clients                  |
+| `@tinkerlandai/longplay-sdk/server`       | Trusted Node.js backend, Customer Sessions, business writes, and Funnel decisions  |
+| `@tinkerlandai/longplay-sdk/react-native` | Portable Customer core and authenticated-backend usage relay; no DOM presentation  |
+| `@tinkerlandai/longplay-sdk/popup`        | Standalone screen rendering, sanitization, and previews                            |
+| `@tinkerlandai/longplay-sdk/openrouter`   | Optional OpenRouter usage integration; requires its peer dependency                |
+| `@tinkerlandai/longplay-sdk/native-shell` | Static Funnel shell assets for native WebViews                                     |
+| `@tinkerlandai/longplay-sdk/page`         | Anonymous website URL experiments using a public App environment ID                |
+| `@tinkerlandai/longplay-sdk/visual`       | Anonymous visual experiments and exposure collection using a public environment ID |
+
+The same package supports JavaScript and TypeScript and includes type declarations. Internal `@indiana/contracts` code is bundled; consumers do not install private workspace packages. Swift and Kotlin use their own package ecosystems and are released separately.
+
+For an independent **Page, Popup or Banner resource**, import `createLongplay` and `mountContent` from the root entry, resolve it with `longplay.resolveContent(...)`, then mount the result. `/page` runs GB URL redirect experiments on an existing merchant page; `/visual` applies GB visual changes to that page. `/popup` exposes lower-level screen rendering and preview primitives. Its name does not select or resolve a Popup resource. The public import paths stay unchanged; see [entry ownership](../../docs/sdk-architecture.md#public-entry-points-and-capability-ownership).
+
+The separate [Python server SDK](../python/README.md) provides synchronous and asynchronous Customer, holdings, entitlement-check and usage clients against the same current HTTP protocol. It is distributed from `https://longplayai.com/sdk/python` (not PyPI) and is not part of this npm package.
+
+The [Go server SDK](../go/README.md) provides the same initial capabilities with typed responses, Context cancellation and goroutine-safe client reuse. It is installed with `go get longplayai.com/sdk/go` through the default Go module proxy and shares the release version with the other business SDKs.
+
+## API origin and test services
+
+The canonical repository policy, including production/test domain roles, package tags and test-host configuration, is [SDK API entry and development testing](../../docs/sdk-endpoints-and-testing.md).
+
+Omitting `baseUrl` selects `https://api.longplayai.com`. This applies to Customer/Server, Funnel, Feature, Paywall, page and visual clients. `createConfigurationSync` also defaults its optional `origin` to that address. Swift `LongplayConfiguration(scope: ...)` and Kotlin `LongplayConfiguration(scope = ...)` uses the same default and shared release version. Explicit `baseURL` / `baseUrl` still overrides it. Funnel and Paywall shells and renderers are packaged locally; their executable code is not downloaded from that API origin.
+
+Both `beta` and `latest` versions published with this default use the production API address. Tags select package versions, not deployments. The separate test API at `https://api.dev.longplayai.com` requires its own credentials and a runtime serving the current protocol 0.10.
+
+Use the same API origin for every client and configuration-sync instance in one integration. Sandbox/Live selects business scope inside that deployment, not a different service or database. Never retry against another service automatically after an error or unknown command result. Maintainer test runs require an explicit target and must not fall back to production; follow the [SDK testing guide](../../docs/sdk-selfserve.md#maintainer-api-origin-testing).
+
+## Create a Customer Session from a trusted backend
+
+```ts
+import { createLongplayServer } from "@tinkerlandai/longplay-sdk/server";
+
+const longplay = createLongplayServer({
+  baseUrl: process.env.INDIANA_BASE_URL!,
+  apiKey: process.env.INDIANA_SECRET_KEY!,
+  scope: {
+    projectId: process.env.INDIANA_PROJECT_ID!,
+    environment: "sandbox",
+  },
+});
+const user = await requireSignedInUser(request);
+const { customer } = await longplay.getOrCreateCustomer({
+  externalUserId: user.id,
+});
+const session = await longplay.createCustomerSession(customer.id);
+```
+
+Keep the Secret Key on your trusted backend. A Customer ID supplied by a browser is not proof of login. Give each Customer Token only to the corresponding authenticated user. App, Sandbox/Live environment, Customer identity, permissions, and allowed origins are checked independently. The SDK holds Customer credentials in memory; destroy the previous view and clear credentials when signing out or changing accounts.
+
+```ts
+import { createLongplay } from "@tinkerlandai/longplay-sdk";
+
+const longplay = createLongplay({
+  baseUrl,
+  scope: { projectId, environment: "sandbox" },
+});
+longplay.identify(session);
+const { holdings } = await longplay.readHoldings();
+// On sign-out:
+longplay.reset();
+```
+
+The SDK refreshes its Access/Refresh pair directly with GOP. Access lasts at most one hour, Refresh at most 24 hours per rotation, within the original 30-day session limit. Successful rotation preserves the Customer identity and pending work; a definitive refresh refusal or expired Refresh Token clears the credentials and requires a new verified login. Business requests do not extend expiry or automatically replay after refresh. Revocation and issuer expiry still apply. See [Customer credentials](../../docs/customer-credentials.md).
+
+Customer updates are partial patches and do not use a Customer revision. When a Guest signs in to an existing Customer, the response reports `switched: true`. Resources and history keep their original owner; create a new Session/Funnel for the target Customer. Guest financial facts are not merged.
+
+## Optional stable fingerprint
+
+`fingerprint` is a host-supplied stable deduplication signal, such as an installation identifier. Initialize and retain it before the first Guest/Customer request, independently of login and credentials. Reuse it across Guest identification, account changes and session renewal. The SDK does not collect or generate it.
+
+```ts
+// Trusted backend: retain installationSignal independently of login.
+// verifiedUser.id comes from your application's authenticated session.
+const { customer } = await longplay.getOrCreateCustomer({
+  externalUserId: verifiedUser.id,
+  fingerprint: installationSignal,
+});
+// Reuse the signal on Guest creation. Retain guestToken separately for retries.
+await longplay.createGuestCustomer({
+  guestToken: retainedGuestToken,
+  fingerprint: installationSignal,
+});
+```
+
+Longplay keeps the first supplied signal as an environment-scoped hash; later values do not replace it. Missing input is valid and retains per-Customer trial deduplication. `unique_fingerprint` additionally deduplicates the configured Product trial across Customers sharing the signal. Business user IDs do not identify an installation; Customer/Guest/session tokens and request IDs have their own lifecycles and should not be fingerprints.
+
+On Web, an independent first-party installation cookie can retain the signal. Clearing it or changing browser storage can produce a new value; sign-out need not reset it. Native hosts persist a random installation signal and define reinstall, restore and reset behavior. This signal is separate from device attestation and authentication. Trial conflicts remain generic to clients; retain `X-Request-Id` for server-side diagnosis.
+
+## Funnel, Feature, and standalone Paywall
+
+A trusted backend calls `createFunnelStartClient().start()` with `funnelId`, a retained `requestId`, `customer`, `locale`, and `parameters`. The Customer reference is `{ type: "id", value: customerId }` or `{ type: "externalUserId", value: verifiedUser.id }`. The latter supports creation-only `customerData` and requires `customers:write`; an existing Customer is not updated. The response includes `customerId`, which your backend can use to issue a Customer Session. Historical start-body `customerToken` and decision-body `customerId` inputs are rejected.
+
+`createFunnelClient({ customerToken, ...options })` is for clients that already hold a Customer credential. Its `start()` omits `customer` and `customerData` and runs as the credential's Customer. After response loss, retry with the same request ID and input. Put commercial parameters in `parameters.commerce`. Each Run has its own Run Token, which cannot switch Customer identity.
+
+`createFunnelDecisionClient.submit/decide` and the server entry's `createFunnelCampaignClient` use the same explicit Customer reference. Campaign `decide()` waits for a `FunnelDecision`; a lookup can return the original accepted decision and its original request ID. Campaign `start()` returns either Run credentials or `{ suppressed: true, reason, retryAt }` when frequency or an active Run blocks a new start, without fabricating Run credentials. Report `shown` only after the Run is actually displayed; page closure or local storage cannot replace a durable presentation fact.
+
+In a browser, use `createFunnelRunController` and `showFunnelRun`. The controller handles current-protocol commands, reads, retries, recovery, and subscriptions. Presentation handles provide `refresh()` and `destroy()`. Published nodes delegate business operations to the server. A client assertion or redirect is not payment evidence.
+
+Each Funnel chooses local or remote evaluation. `createFunnelDecisionClient` supports `configuration()`, `features()`, submission, and result reads. `createFeatureClient` identifies configuration by `generation`. Downloaded local rules are visible to clients; use remote evaluation and verified business facts for sensitive decisions.
+
+### Bucketing identity across independent consumers
+
+Funnel, standalone Features and page experiments evaluate independently. Matching App/environment, experiment definition, attributes, hash identity and Sticky state produce matching results; different refresh times or inputs may produce different variations. A Remote Funnel still evaluates on Longplay when its referenced code Experiment allows Local definition delivery. Accepted Funnel decisions retain their original results. There is no cross-feature result synchronization.
+
+For Customer-based evaluation, `id` means the Longplay Customer UUID (`customer.id`); `externalUserId` means the merchant account ID (`customer.externalUserId`). Choose the experiment's `hashAttribute` explicitly when creating it and preserve that meaning in every consumer. Do not put the merchant account ID into `attributes.id`. Supply local attributes from your trusted backend's Customer data; `identify(customerToken)` authenticates requests but does not populate local bucketing attributes. These attributes are evaluation data, not authorization.
+
+`setAttributes()` replaces the complete object, so retain the bucketing fields on every update. Anonymous page/visual experiments instead default `id` and `deviceId` to the shared first-party device cookie; they do not automatically match an account-based experiment. Sticky capabilities differ by adapter: managed Local Run instructions receive server state, while pure local tools require their existing host persistence adapter for durable Sticky. No new shared state is introduced. See the [architecture boundary](../../docs/growthbook-sdk-delivery.md#跨消费方求值边界与分桶身份).
+
+### Server-side local Funnel evaluation
+
+For a Local Funnel containing only Entry, Condition, Feature, Split and literal/Feature End or Output nodes, use the explicit local evaluator. Reuse the client/evaluator across requests; create a session for one verified identity and attribute/parameter snapshot:
+
+```ts
+const local = createFunnelDecisionClient(options).local();
+const session = local.session({
+  attributes: {
+    id: customer.id,
+    externalUserId: customer.externalUserId,
+    country: "US",
+  },
+  parameters: { placement: "home" },
+});
+const preview = await session.evaluate();
+const used = await session.evaluate({ track: true });
+// used.value is a local calculation, with no Decision/receipt ID.
+```
+
+`local_configuration` downloads the scoped dependency projection through the existing backend credential checks. Concurrent loads share one request, definitions are prepared once per Version/policy revision/GB generation, and reuse stops at the supplied expiry or 60 seconds, whichever is earlier. `local.refresh()` forces a fresh read; failed refreshes never fall back to stale rules. `local.reset()` invalidates cached definitions and existing sessions. Create a new session after an identity or context change. Browser execution is refused.
+
+Sessions retain Sticky assignments in memory. Supply `stickyBucketAssignmentDocs` and `saveStickyBucketAssignmentDoc` for host persistence; the host must scope storage by App/environment/identity and own any cross-process merge/CAS. Async saves finish before a result is returned. A failed save retains the original assignment and rejects with `STICKY_SAVE_FAILED`; retry `session.flush()` or the evaluation. In-memory state alone provides no cross-device consistency.
+
+Evaluation is untracked by default. `{ track: true }` invokes configured `onExperimentViewed`/`onFeatureUsage` callbacks once per native assignment/value in that session after successful evaluation and Sticky persistence. Connect callbacks to the existing event tracker only when the result is actually used. Callback errors reach `onError`; event delivery/retries remain the tracker's responsibility, and evaluation does not manufacture durable exposure or usage receipts.
+
+Mixed graphs, resource/Bundle outputs and expired configurations fail explicitly. There is no automatic remote execution. `decide()` retains its server-side idempotency, committed receipts and financial checks; local output never grants a Coupon, purchase, entitlement or campaign frequency promise.
+
+### Standalone Feature delivery
+
+Explicitly grant a backend Key `features:read` / `events:write` and issue existing Customer/Guest Sessions to browser clients.
+
+```ts
+// Customer data supplied by your trusted backend for the current user.
+const bucketingIdentity = {
+  id: customer.id,
+  externalUserId: customer.externalUserId,
+};
+const flags = await longplay.features({
+  attributes: { ...bucketingIdentity, country: "CA" },
+});
+const enabled = flags.getFeatureValue("new-checkout", false);
+const unsubscribe = flags.subscribe(() =>
+  updateView(flags.isOn("new-checkout")),
+);
+flags.setAttributes({ ...bucketingIdentity, country: "US" });
+longplay.track("Checkout Viewed", { source: "pricing" });
+await longplay.flush();
+// On page teardown:
+unsubscribe();
+flags.destroy();
+```
+
+The selected environment's integration settings control behavior events, experiment exposures and Feature usage independently. New environments enable only exposure collection; existing environments retain all three. `flush()` includes a `skipped` count for intentionally disabled collection. The database rechecks every batch, including direct SDK/server and Funnel ingestion. Running experiment/Bandit dependencies prevent incompatible collection changes. These controls do not delete history or affect commercial usage accounting.
+
+Flags default to local evaluation; Owner/Admin can switch each flag to server evaluation. Server-evaluated flags deliver only keys and results, using the caller's fallback until the first result arrives. Attribute changes immediately discard old results. List hashes are not a secrecy boundary. Local Funnels cannot depend on server-evaluated flags; mode switches also check active historical Runs. `identify` / `reset` release the previous identity's Feature instances and event queue.
+
+Merchandise targeting resolves a trusted item in the selected App/environment. Register its attributes and maintain the
+item in Console, then pass a reference rather than item metadata. The SDK resolves the initial SKU before returning;
+after switching items, await context refresh before reading the next decision. Item experiments use `merchandiseId`
+(the internal UUID) without a Customer fallback; Customer experiments keep their own bucketing identity.
+
+```ts
+const merchandiseFlags = await longplay.features({
+  attributes: { ...bucketingIdentity, merchandise: { id: "sku-outdoor" } },
+});
+merchandiseFlags.setAttributes({
+  ...bucketingIdentity,
+  merchandise: { id: "sku-indoor" },
+});
+await merchandiseFlags.refreshRemote();
+const eligible = merchandiseFlags.isOn("item-promotion");
+longplay.track("Item Viewed", {}, { merchandise: { id: "sku-indoor" } });
+await longplay.flush();
+merchandiseFlags.destroy();
+```
+
+Offering pins the Product Version scope and hierarchy. Paywall pins a published Offering Version and independently chooses its displayed Product subset, groups, ordering, and default selection. `createPaywallStartClient`, `createPaywallSession`, and `showPaywall` use a standalone Paywall Session. After payment, read Entitlements again. Your backend still authorizes requests and consumes usage idempotently.
+
+To render a Paywall while handing purchase selection to your own app, pass `onPurchaseIntent` to `showPaywall`. It receives
+`actionId`, the selected `productVersionId`, a copy of the UI `selection`, and validated `featureQuantities`. That callback
+replaces quote creation for the clicked purchase button; it neither charges nor grants access. Share the identified
+client's `session` with `createPaywallSession` to retain automatic Access/Refresh rotation. Your session endpoint must
+verify the native user before issuing credentials; reset the client and destroy the Paywall when that user changes.
+
+## Commercial capabilities and current service boundaries
+
+The server implements Customer/Guest identity, Entitlement checks, holdings and ledger reads, usage and balances, Coupons/referral codes, Offering/standalone Paywall, and configured Stripe Sandbox attach, payment-method collection, subscription validation/updates/refunds/Trial, and License allocation. Each operation depends on configured payment accounts, execution mode, Product/Price terms, and its implemented scope. An API's presence does not certify every combination.
+
+In Stripe environments, Longplay executes `longplay` mode; `record_only` returns instructions for the merchant backend to execute. Both record financial and Entitlement facts from verified Stripe evidence. Collecting a payment method does not itself charge, create an Invoice, or grant extra Entitlements. Quotes, confirmations, and reads retain their durable operation IDs; a request ID cannot be reused with different input.
+
+This beta does not certify complete commercial or production operation. Remaining service gaps include:
+
+- Subscription batch processing. Conflict queries and retries have services but still require a matching deployment and business prerequisites.
+- Postpaid Billing Authorization, Billing Coupon lists, and billing-adjustment confirmation. AutoTopup consent preparation/confirmation/revocation is implemented independently.
+- Complete delivery for `claimRewardProduct`.
+- Real Apple/Google store acceptance. Independent purchase/restore contracts and partial services do not certify store acceptance. `createNativeReceiptClient().recover()` uses `subscriptions/native/restore`.
+
+Implemented commercial operations use the original credential, permission, scope and configured-provider checks in both Sandbox and Live. An unsupported operation returns 501; a provider configuration or business precondition is not a migration allowlist.
+
+## AI usage
+
+The server entry provides AI SDK usage middleware; the OpenRouter entry provides a wrapper. Your host supplies a persistent idempotency key per invocation, usage/quote storage, and recovery callbacks. Recovery replays the original quoted charge without running the model again. Keep provider keys on your trusted backend.
+
+## Publication and verification
+
+Publishing to npm does not deploy Web services, apply database migrations, or release Swift/Kotlin packages. Package installation, types, offline unit tests, and builds are recorded separately from real Auth/RLS, Stripe, native stores, browser checks, and hosted deployment acceptance.
+
+See the [SDK release ledger](https://github.com/tinkerlandai/Indiana/blob/main/docs/sdk-releases.md) for versions and immutable publication evidence, and the [developer documentation](https://longplayai.com/docs?lang=en) for integration guides.
+
+## Shared public configuration
+
+Use one manager per trusted origin and exact App/environment for Features, canonical Funnel files and enabled page experiments. Use a matching runtime and an explicitly reviewed public configuration publication.
+
+```ts
+import {
+  createConfigurationSync,
+  createLongplay,
+} from "@tinkerlandai/longplay-sdk";
+
+// Use a Sandbox App and credentials issued by the production deployment.
+const apiUrl = "https://api.longplayai.com";
+const scope = { projectId, environment: "sandbox" as const, environmentId };
+const configuration = createConfigurationSync({
+  origin: apiUrl,
+  scope,
+});
+const longplay = createLongplay({
+  baseUrl: apiUrl,
+  scope: { projectId, environment: "sandbox" },
+  configuration,
+});
+const features = await longplay.features();
+const document = await configuration.funnel(funnelId);
+// Other consumers receive this same configuration instance.
+// Supply existing credentials separately for business operations.
+features.destroy();
+configuration.destroy(); // Host owns the shared lifetime.
+```
+
+Pass `configuration` to Funnel start/Run helpers or `createPageExperiments` as well. On your backend, `createSynchronizedFunnelLocalEvaluator(configuration, funnelId)` from `/server` uses the same canonical file/GB generation for pure advisory evaluation. Public bytes never authorize business eligibility or commit a Run transition.
+
+Initialization has a five-second total wait budget. Active subscriptions share 12–15-second polling, retries and foreground/reconnect refresh. Local control expires at most 60 seconds after origin validation; expiry or observed pause suspends local evaluation/screens. Cold offline initialization cannot restore active permission from storage. Explicit Longplay Run commands and observations obtain current state from Longplay and bypass CDN initialization and freshness.
+
+Optional browser persistence defaults to localStorage and contains only public bytes: 128 entries / 2 MiB / seven days, with a 128-entry / 32 MiB memory cache. Use `storage: null` to disable persistence or supply a `ConfigurationStorage` adapter. Quota errors fall back to memory. Each artifact is limited to 1 MiB, manifests to 512 KiB, and all files are scope/schema/hash checked. Keep credentials, attributes, Sticky records and accepted decisions in their separate existing stores.
+
+## Local Funnel execution
+
+Local and Remote share the authoritative Longplay Run, command/action receipts, business services and Queue recovery. A Local host predicts pure Condition/Feature/Experiment paths for display, then sends a `commit_segment` advance signal. GOP recomputes the accepted path from the Run inputs and approved public GB configuration. Remote evaluates on GOP without client configuration. Independent `evaluateFunnelNode` and advisory `.local()` helpers have no business effects.
+
+```ts
+import {
+  createLocalFunnelClient,
+  showFunnelRun,
+} from "@tinkerlandai/longplay-sdk";
+
+const flow = await createLocalFunnelClient({
+  baseUrl,
+  configuration,
+  funnelId,
+  credential: customerToken,
+});
+const started = await flow.start({
+  requestId: savedStartRequestId, // Persist before sending; reuse the exact input after an unknown response.
+  locale: "en",
+  parameters: { source: "checkout" },
+});
+const host = await showFunnelRun(container, {
+  client: started.controller,
+  onError: reportError,
+});
+// Retain started.runToken in your host's secure credential storage.
+// Restore the same Run: await flow.restore(originalRunToken).
+host.destroy(); // Detach UI; accepted backend work remains owned by Indiana.
+started.controller.reset();
+```
+
+Merchant backends use the same adapter from `/server`, with their original Server Key as `credential` and the Longplay Customer UUID as `customerId`. Each Run request proves the original live issuing Key in a server-only header; it is never saved in a pending command or exposed to the renderer. The ordinary `createFunnelRunController` accepts `serverKey` only on a merchant backend. Customer clients continue proving their original Customer identity with `identify(customerToken)`; they cannot override it.
+
+A Flow `commit_segment` carries only its retained request ID, parked node/visit/revision, policy revision and configuration generation. Caller steps, results and boundaries are not accepted. The SDK prediction yields to the server response; response-loss recovery preserves the original command identity. Customer Coupon claims still require `offers:resolve` and explicit `selfClaimEnabled`; merchant grants retain `offers:grant`. The independent Coupon issuer owns eligibility, inventory, possession and expiry.
+
+After an advance signal is accepted, actions, waits, retries and recovery use the same GOP driver and Cloud Tasks / Cloud Scheduler as Remote. A disconnected host does not cancel accepted work. Before the required signal arrives, the Run remains parked. The bounded SDK loop settles up to 32 calculation boundaries per call; longer chains continue on a later read.
+
+### Shared UI host
+
+Screens, live Customer/Coupon data, shown acknowledgements, Paywall and external-task handling use the same Run controller and UI host. Canonical node/command history uses the common recording limits. Recovery uses authoritative Run, command and business receipts, without an observation-upload API or a second storage authority. There is no second host business state machine, `invoke` adapter, Local checkpoint owner, `browserFunnelStorage` or Local presentation controller.
+
+Recovery uses the original Run Token and command identities. Do not turn an unknown business outcome into a new start/request ID. The SDK does not import legacy checkpoints. A mode change never rewrites a Run's accepted policy or commands; resolve that original Run before starting another intent.
+
+The native renderer shell uses the same pure JavaScript calculation adapter and native Run-command bridge; credentials remain in the native session. A headless Swift/Kotlin session exposes the pending calculation and does not silently calculate it remotely. Wire schemas and the renderer shell are generated together. Installing the package does not migrate a database or deploy a runtime. Browser, provider, capacity and native-store acceptance remain separate.
+
+## Web IAM entries and Funnel page experiments
+
+Install the entry host once, then configure screen-entry or button/link triggers on a Funnel's Entry node in the App page map. Save and publish through the existing Funnel lifecycle. Use the merchant build's verified IAM digest and the same Customer session as other SDK clients:
+
+```ts
+import { createIamFunnelEntries } from "@tinkerlandai/longplay-sdk";
+
+const entries = createIamFunnelEntries({
+  scope: { projectId, environment: "sandbox" },
+  environmentId,
+  baseUrl,
+  appManifestRelease, // digest resolved from this build's IAM release descriptor
+  session: longplay.session,
+  container,
+  onStatus: (status, entryId) => console.log(status, entryId),
+});
+await entries.start();
+// After an uncertain start, reuse the original in-memory request:
+await entries.retry();
+// On host teardown:
+entries.destroy();
+```
+
+The host observes original button behavior, matches unique render/element guards and attempts automatic entries once per pathname visit. GOP selects the Funnel, checks entry publication, suppresses an existing Customer/Funnel Run and enforces the automatic-entry cooldown. The host retains unknown requests in memory; page reload recovery is not included. When a Run is stopped from Console or expires, the host removes its UI and reports `run_ended`, whether the Run reads `closed` or its next command is refused with `FORBIDDEN`; a later trigger can then start again. An IAM binding supplies no Customer credential or business permission.
+
+An opted-in Split (`applyPageExperiment: true`) uses its accepted experiment variation for the merchant page. The entry host automatically shares `appManifestRelease` with `showFunnelRun`; manual hosts pass that option explicitly. `createFunnelPageExperiments({client, appManifestRelease})` is available for hosts without the standard UI. The consumer never rebuckets, reports use against the accepted receipt, and reverts on stop, completion or destruction. A separately installed visual consumer yields ownership of that experiment during the Run. This Web source feature requires matching GOP contracts and the IAM/Funnel database migration; installation alone does not promote runtime support.
+
+## Funnel-scoped resource requests
+
+Formal Local Runs submit advance signals to Longplay; the canonical executor supplies the original Run/node/visit/receipt when it issues a Coupon or performs commerce. An application consuming a pure Funnel result can bind its Customer client explicitly:
+
+```ts
+const resources = longplay.forFunnel({ funnelId, versionId });
+await resources.claimCoupon(couponId, savedRequestId);
+```
+
+The scoped client automatically carries that fixed Funnel context into Coupon claims, Offering/Paywall resolution and attach quotes. Longplay recomputes only the requested Funnel using trusted facts; caller-reported branches are not permission. Independent `longplay.claimCoupon(...)` remains available under Coupon-owned self-claim rules. Reuse the same request ID and input after an unknown response; accepted commands retain their original result after a later Funnel pause.
+
+## Standalone Pages, Popups and Banners
+
+Publish a Banner with no required inputs and a declared `continue` action. Issue a Customer Token with `content:read`, then explicitly resolve and mount it. Use the matching `kind` for Page or Popup.
+
+```ts
+import {
+  createLongplay,
+  mountContent,
+  type ContentActionIntent,
+} from "@tinkerlandai/longplay-sdk";
+
+export async function showBanner(
+  container: HTMLElement,
+  customerToken: string,
+  contentId: string,
+  onContinue: (intent: ContentActionIntent) => Promise<void>,
+) {
+  const longplay = createLongplay({
+    baseUrl: "https://api.longplayai.com",
+    scope: { projectId: "<APP_UUID>", environment: "sandbox" },
+  });
+  longplay.identify(customerToken);
+  const { content } = await longplay.resolveContent({
+    kind: "banner",
+    selector: { type: "resource", id: contentId },
+  });
+  const host = await mountContent(container, {
+    content,
+    actions: { continue: onContinue },
+    onError: console.error,
+  });
+  return {
+    retryAction: host.retryAction,
+    destroy() {
+      host.destroy();
+      longplay.reset();
+    },
+  };
+}
+```
+
+Provide every declared action handler. `onContinue` uses `intent.requestId` as its backend idempotency key; `retryAction()` reuses that intent after a failure. Call `destroy()` on unmount, sign-out or account change. The host renders content and emits intents; your backend still authorizes and executes business actions.
+
+To remove module loading, document preparation and iframe startup from the opening click, resolve the current Customer's content earlier and prepare it explicitly:
+
+```ts
+import { prepareContent } from "@tinkerlandai/longplay-sdk";
+
+const lifetime = new AbortController();
+const popup = await prepareContent(container, {
+  content, // Already resolved with kind: "popup" for this Customer.
+  actions: { continue: onContinue },
+  onError: console.error,
+  signal: lifetime.signal,
+});
+openButton.addEventListener("click", () => popup.show(), {
+  signal: lifetime.signal,
+});
+// On unmount, sign-out or account/scope change:
+// lifetime.abort();
+```
+
+Preparation waits for the first render without opening the dialog or running actions. `show()` reveals the same iframe and is idempotent; destroy and prepare a fresh handle for another presentation. Abort also cancels preparation while it is pending. This does not pre-authorize business operations or guarantee that images have decoded. For low-level ScreenDocument rendering, `/popup` provides `preparePopup(document, options)` with `ready`, `show()` and `destroy()`.
+
+Customer sessions contain `customerId`, `sessionId`, `accessToken`, `refreshToken`, `expiresAt` and `refreshExpiresAt`. Return the pair only to the authenticated merchant user with `Cache-Control: no-store`, then call `longplay.identify(session)`. The SDK refreshes directly with GOP and keeps credentials in memory; account reset fences pending refresh. Your backend uses `revokeCustomerSessions({customerId, sessionId?})` for revocation. Share `longplay.session` through the `session` option of independent Paywall/Funnel clients to preserve one refresh lifecycle.
+
+## Merchant-recorded billing
+
+In `record_only` mode your backend owns payment execution, verifies its results and submits normalized `provider: "merchant"` facts with the Server SDK. Use `purchase.completed`, `purchase.closed`, `subscription.observed`, `subscription.change.completed`, `invoice.paid` or `refund.updated`. Include the original operation/Customer, complete Invoice lines and subscription items as required. Amounts use minor units; `occurredAt` is an ISO observation time. A durable outbox retains the exact event ID and facts on retry. The receipt records merchant provenance with `providerVerified: false`; Customer/Guest clients cannot submit billing facts. Managed mode retains Longplay-owned provider execution.
+
+## Merchant bridge
+
+`createMerchantBridge` consumes bridge version 3 at POST `/integrations/indiana`, scoped by App and environment. It uses native login for Customer sessions, presentation, commerce reads and confirmed original operations. Call `reset()` on logout/account switch. The client never automatically retries financial execution or opens Checkout. Protocol 0.10 accepts no older protocol.
+
+The Server entry exports `createMerchantBridgeHandler`, `createMerchantBridgeAuthorityResolver`, `signMerchantBridgeMessage` and `verifyMerchantBridgeMessage`. Supply backend signing keys, native authorization/CSRF, implemented capabilities/profiles and typed handlers. Set `resolveOperationAuthority: createMerchantBridgeAuthorityResolver(server)` so every financial/read command obtains fresh Longplay authority from the original operation API. A signed service request still requires confirmation and exact scope/Customer ownership; it cannot issue user sessions.
+
+Handlers must durably reserve the original operation before external effects and retain the same provider idempotency key. The SDK's preceding lookup is not a concurrency lock. `operation.read` returns `found` or `not_received` without creating effects. Recover `RESULT_UNKNOWN` through that original operation; never infer permission from a browser quote or `pending`. Console discovery is configuration validation, not commercial completion. See the [merchant specification](https://longplayai.com/docs/merchant-execution) for exact fields and recovery.