openreceive-rails 0.4.6 → 0.4.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cd25ab457fdc7a54d989c2a490fa75d451362157618702bc3e101d461c450d4
-  data.tar.gz: c377fd378153bd78bb195000a74efd776587b40d1a8927a514aa7b9739da8986
+  metadata.gz: c53bf506f1db08240a35a17c509b74d5bdb13964f10bdc0b3e8d580d71e0f6c1
+  data.tar.gz: b3361f7e657d7d0e96228b1a8a8f5531ed61ed6924f002b6bebdb70a80f91efe
 SHA512:
-  metadata.gz: 980779f4826ebc988f9d6b11a24004153477b84738ba26e5ad849658137b24edd8d5f3cded4d212ae6e17f4c69a6d02d3398cca5abc2417033d599f9c7665fb3
-  data.tar.gz: c48b85c8349b5bc27ae2c8f2b1dc9a9aa4f1f81640850368a4a411ca5035cdad5bd3e8d9f03298077516c8dbd163c82c42c60a448d43431f24dc8ddb494731e4
+  metadata.gz: 07c085990621609cde309b305d3887079232ddfa00c191b409a8aa2bba38370d2937422607cb3479dfff78edbe0bde4976e6ec9e50aa3bd0ff1525f429905b3f
+  data.tar.gz: 0ed794db39837fb586b2e49d705fc8064f2aadf647544e51bd13888f748fbf3ad897700950211ca2f5087739d2036bcf748d3af9a28668d13bb1a2c6660b4864

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.4.9 - 2026-09-14
+
+Release alongside the packaged checkout fix that hides the Lightning pane
+on “Switch payment method” and reuses the same invoice when Bitcoin is
+selected again. Update `@openreceive/elements` and rebuild the frontend to
+receive this fix; upgrading the gem alone does not update the checkout UI.
+
+Refresh the bundled Rails integration directions with the method-switch
+regression check and guidance to serve the compiled stylesheet without
+importing it into the host Tailwind entry. No Rails engine API or settlement
+changes.
+
+## 0.4.8 - 2026-09-14
+
+Release alongside the custom element's Lightning invoice loading indicator.
+Rails hosts must also update their npm checkout dependencies and rebuild
+JavaScript to receive it. No Rails engine API or settlement changes.
+
+## 0.4.7 - 2026-09-13
+
+Version alignment for the BTCPay plugin release; no Ruby behavior changes.
+
 ## 0.4.6 - 2026-09-11
 
 Refresh installation and quickstart documentation and package metadata.

data/lib/openreceive/rails/version.rb

@@ -5,6 +5,6 @@ module OpenReceive
   # top-level `::Rails` framework constant — engine code always references the framework as
   # `::Rails` to avoid shadowing.
   module Rails
-    VERSION = "0.4.6"
+    VERSION = "0.4.9"
   end
 end

data/skills/integrate-openreceive/references/btcpay.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (BTCPay Server)
 
-These directions describe OpenReceive 0.4.6.
+These directions describe OpenReceive 0.4.9.
 
 Connect a BTCPay Server store to a receive-only NWC wallet with the OpenReceive
 plugin, and optionally let payers pay BTCPay invoices with USDT, USDC, ETH or

data/skills/integrate-openreceive/references/django.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Django)
 
-These directions describe OpenReceive 0.4.6.
+These directions describe OpenReceive 0.4.9.
 
 Add OpenReceive to a Django project — the app you are already working in. You
 do not need a copy of the OpenReceive source: the Python package is on PyPI
@@ -218,6 +218,8 @@ The engine serves JSON only, so the view is yours — but the drop-ins
 list is the short form of https://openreceive.org/guides/checkout-ux.md, for a UI
 built on `@openreceive/browser/headless`. Read that before writing components.
 
+- Check Bitcoin → Switch payment method → Bitcoin: the grid must hide the
+  Lightning invoice, then restore the same bolt11 without another mint.
 - `createCheckoutController` is the engine. Do not hand-roll a poll loop.
 - `createCheckoutStatusModel` for the status line. Do not draw a
   Cart → Pay → Done stepper. Read the model's `phase`, not the snapshot's.
@@ -245,11 +247,25 @@ built on `@openreceive/browser/headless`. Read that before writing components.
   "switch payment method".
 - No "Open wallet" button on desktop.
 - Wallet suggestions: `getPaymentWizardRoutes()` +
-  `createWizardRouteDisplays`. Lightning only. Every image ships inside
-  the JavaScript — logos as data URIs, tutorials once `loadPayTutorialImages()`
-  resolves (`image` is `undefined` until then) — so serve nothing and set no
-  asset option. When it works, the logos and payment icons render; a missing
-  image means a CSP `img-src` that blocks `data:`, and the console names it.
+  `createWizardRouteDisplays`. Lightning only. Logos are data URIs; tutorial
+  images load from a JavaScript chunk. For a custom headless UI, load it when
+  a tutorial opens and look up the returned table by the tutorial's `path`:
+
+  ```js
+  import { loadPayTutorialImages } from "@openreceive/browser/headless";
+
+  const images = await loadPayTutorialImages();
+  const src = images[tutorial.path]; // data URI for the selected tutorial
+  ```
+
+  Render `src` as the image source and update your UI after loading. Existing
+  display objects do not update: their `tutorial.image` stays `undefined` if
+  created before loading. Alternatively, await the loader, recreate the displays
+  with `createWizardRouteDisplays`, and render the new `tutorial.image`.
+  Show the caption while loading or if loading fails; never use an empty image
+  source. Deploy all JavaScript chunks and allow `data:` in CSP `img-src`.
+  For missing images, check CSP errors, failed chunks, and stale displays.
+  Registry paths are lookup keys; there is no asset option or image route.
   The registry answers ~37 wallets: pass
   `providerPreviewLimit` and build "show all" from `display.providerCount`,
   or they push the QR off the screen.
@@ -570,6 +586,11 @@ manage.py openreceive_doctor                        # the same, for humans; neve
 
 ### Render the checkout
 
+Serve the compiled `styles.css` without Tailwind processing: import it from
+JavaScript (with a CSS-capable bundler) or use a plain `<link rel="stylesheet">`.
+Do not `@import` it into the host Tailwind entry. Its zero-specificity rules
+allow host styles to override checkout styles; scoping does not prevent that.
+
 The app serves JSON checkout routes only — rendering is your template. Any
 OpenReceive frontend package works against the `/openreceive` mount; the
 smallest is the custom element, and the Python package carries its
@@ -590,8 +611,7 @@ bundler at all:
 
 `openreceive-checkout.js` registers the `<openreceive-checkout>` tag when it
 loads (one self-contained ES module, un-minified identifiers), and the
-stylesheet is scoped to what OpenReceive renders so it sits safely next to any
-CSS framework in any order. `collectstatic` ships both with the rest of your
+stylesheet is scoped to what OpenReceive renders. `collectstatic` ships both with the rest of your
 static files; the package's `MANIFEST.json` names every file and its hash. The
 element creates the checkout for `reference`, then renders and polls itself
 (its default `prefix` is already `/openreceive`).

data/skills/integrate-openreceive/references/fastapi.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (FastAPI)
 
-These directions describe OpenReceive 0.4.6.
+These directions describe OpenReceive 0.4.9.
 
 Add OpenReceive to a FastAPI application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the engine is on PyPI
@@ -215,6 +215,8 @@ This list is the short form of https://openreceive.org/guides/checkout-ux.md, fo
 UI built on `@openreceive/browser/headless`. Read that before writing
 components.
 
+- Check Bitcoin → Switch payment method → Bitcoin: the grid must hide the
+  Lightning invoice, then restore the same bolt11 without another mint.
 - `createCheckoutController` is the engine. Do not hand-roll a poll loop.
 - `createCheckoutStatusModel` for the status line. Do not draw a
   Cart → Pay → Done stepper. Read the model's `phase`, not the snapshot's.
@@ -242,11 +244,25 @@ components.
   "switch payment method".
 - No "Open wallet" button on desktop.
 - Wallet suggestions: `getPaymentWizardRoutes()` +
-  `createWizardRouteDisplays`. Lightning only. Every image ships inside
-  the JavaScript — logos as data URIs, tutorials once `loadPayTutorialImages()`
-  resolves (`image` is `undefined` until then) — so serve nothing and set no
-  asset option. When it works, the logos and payment icons render; a missing
-  image means a CSP `img-src` that blocks `data:`, and the console names it.
+  `createWizardRouteDisplays`. Lightning only. Logos are data URIs; tutorial
+  images load from a JavaScript chunk. For a custom headless UI, load it when
+  a tutorial opens and look up the returned table by the tutorial's `path`:
+
+  ```js
+  import { loadPayTutorialImages } from "@openreceive/browser/headless";
+
+  const images = await loadPayTutorialImages();
+  const src = images[tutorial.path]; // data URI for the selected tutorial
+  ```
+
+  Render `src` as the image source and update your UI after loading. Existing
+  display objects do not update: their `tutorial.image` stays `undefined` if
+  created before loading. Alternatively, await the loader, recreate the displays
+  with `createWizardRouteDisplays`, and render the new `tutorial.image`.
+  Show the caption while loading or if loading fails; never use an empty image
+  source. Deploy all JavaScript chunks and allow `data:` in CSP `img-src`.
+  For missing images, check CSP errors, failed chunks, and stale displays.
+  Registry paths are lookup keys; there is no asset option or image route.
 
 ## More documentation
 
@@ -472,8 +488,12 @@ import "@openreceive/react/styles.css";
 The checkout renders, polls, and settles itself. The compiled `styles.css`
 sheets (`@openreceive/react`, `@openreceive/elements`) are self-contained — a
 plain `<link rel="stylesheet">` works with no build step — and scoped: every
-rule applies only inside what OpenReceive renders, so the sheet is safe next
-to any CSS framework (Mantine, Bootstrap, your own reset) in any import order.
+rule applies only inside what OpenReceive renders.
+
+Serve the compiled `styles.css` without Tailwind processing: import it from
+JavaScript (with a CSS-capable bundler) or use a plain `<link rel="stylesheet">`.
+Do not `@import` it into the host Tailwind entry. Its zero-specificity rules
+allow host styles to override checkout styles; scoping does not prevent that.
 
 `<Checkout>` is complete as rendered: it already shows the `description` from
 `amountFor` and the collapsed transaction-details panel. Do not build a custom

data/skills/integrate-openreceive/references/fastify.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Fastify)
 
-These directions describe OpenReceive 0.4.6.
+These directions describe OpenReceive 0.4.9.
 
 Add OpenReceive to a Fastify application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the packages are on npm, and
@@ -198,6 +198,8 @@ This list is the short form of https://openreceive.org/guides/checkout-ux.md, fo
 UI built on `@openreceive/browser/headless`. Read that before writing
 components.
 
+- Check Bitcoin → Switch payment method → Bitcoin: the grid must hide the
+  Lightning invoice, then restore the same bolt11 without another mint.
 - `createCheckoutController` is the engine. Do not hand-roll a poll loop.
 - `createCheckoutStatusModel` for the status line. Do not draw a
   Cart → Pay → Done stepper. Read the model's `phase`, not the snapshot's.
@@ -225,11 +227,25 @@ components.
   "switch payment method".
 - No "Open wallet" button on desktop.
 - Wallet suggestions: `getPaymentWizardRoutes()` +
-  `createWizardRouteDisplays`. Lightning only. Every image ships inside
-  the JavaScript — logos as data URIs, tutorials once `loadPayTutorialImages()`
-  resolves (`image` is `undefined` until then) — so serve nothing and set no
-  asset option. When it works, the logos and payment icons render; a missing
-  image means a CSP `img-src` that blocks `data:`, and the console names it.
+  `createWizardRouteDisplays`. Lightning only. Logos are data URIs; tutorial
+  images load from a JavaScript chunk. For a custom headless UI, load it when
+  a tutorial opens and look up the returned table by the tutorial's `path`:
+
+  ```js
+  import { loadPayTutorialImages } from "@openreceive/browser/headless";
+
+  const images = await loadPayTutorialImages();
+  const src = images[tutorial.path]; // data URI for the selected tutorial
+  ```
+
+  Render `src` as the image source and update your UI after loading. Existing
+  display objects do not update: their `tutorial.image` stays `undefined` if
+  created before loading. Alternatively, await the loader, recreate the displays
+  with `createWizardRouteDisplays`, and render the new `tutorial.image`.
+  Show the caption while loading or if loading fails; never use an empty image
+  source. Deploy all JavaScript chunks and allow `data:` in CSP `img-src`.
+  For missing images, check CSP errors, failed chunks, and stale displays.
+  Registry paths are lookup keys; there is no asset option or image route.
 
 ## More documentation
 
@@ -474,8 +490,12 @@ import "@openreceive/react/styles.css";
 The checkout renders, polls, and settles itself. The compiled `styles.css`
 sheets (`@openreceive/react`, `@openreceive/elements`) are self-contained — a
 plain `<link rel="stylesheet">` works with no build step — and scoped: every
-rule applies only inside what OpenReceive renders, so the sheet is safe next
-to any CSS framework (Mantine, Bootstrap, your own reset) in any import order.
+rule applies only inside what OpenReceive renders.
+
+Serve the compiled `styles.css` without Tailwind processing: import it from
+JavaScript (with a CSS-capable bundler) or use a plain `<link rel="stylesheet">`.
+Do not `@import` it into the host Tailwind entry. Its zero-specificity rules
+allow host styles to override checkout styles; scoping does not prevent that.
 
 `<Checkout>` is complete as rendered: it already shows the `description` from
 `amountFor` and the collapsed transaction-details panel. Do not build a custom

data/skills/integrate-openreceive/references/laravel.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Laravel)
 
-These directions describe OpenReceive 0.4.6.
+These directions describe OpenReceive 0.4.9.
 
 Add OpenReceive to a Laravel application — the app you are already working in.
 You do not need a copy of the OpenReceive source: the package is on Packagist
@@ -203,6 +203,8 @@ The engine serves JSON only, so the view is yours — but the drop-ins
 list is the short form of https://openreceive.org/guides/checkout-ux.md, for a UI
 built on `@openreceive/browser/headless`. Read that before writing components.
 
+- Check Bitcoin → Switch payment method → Bitcoin: the grid must hide the
+  Lightning invoice, then restore the same bolt11 without another mint.
 - `createCheckoutController` is the engine. Do not hand-roll a poll loop.
 - `createCheckoutStatusModel` for the status line. Do not draw a
   Cart → Pay → Done stepper. Read the model's `phase`, not the snapshot's.
@@ -230,11 +232,25 @@ built on `@openreceive/browser/headless`. Read that before writing components.
   "switch payment method".
 - No "Open wallet" button on desktop.
 - Wallet suggestions: `getPaymentWizardRoutes()` +
-  `createWizardRouteDisplays`. Lightning only. Every image ships inside
-  the JavaScript — logos as data URIs, tutorials once `loadPayTutorialImages()`
-  resolves (`image` is `undefined` until then) — so serve nothing and set no
-  asset option. When it works, the logos and payment icons render; a missing
-  image means a CSP `img-src` that blocks `data:`, and the console names it.
+  `createWizardRouteDisplays`. Lightning only. Logos are data URIs; tutorial
+  images load from a JavaScript chunk. For a custom headless UI, load it when
+  a tutorial opens and look up the returned table by the tutorial's `path`:
+
+  ```js
+  import { loadPayTutorialImages } from "@openreceive/browser/headless";
+
+  const images = await loadPayTutorialImages();
+  const src = images[tutorial.path]; // data URI for the selected tutorial
+  ```
+
+  Render `src` as the image source and update your UI after loading. Existing
+  display objects do not update: their `tutorial.image` stays `undefined` if
+  created before loading. Alternatively, await the loader, recreate the displays
+  with `createWizardRouteDisplays`, and render the new `tutorial.image`.
+  Show the caption while loading or if loading fails; never use an empty image
+  source. Deploy all JavaScript chunks and allow `data:` in CSP `img-src`.
+  For missing images, check CSP errors, failed chunks, and stale displays.
+  Registry paths are lookup keys; there is no asset option or image route.
   The registry answers ~37 wallets: pass
   `providerPreviewLimit` and build "show all" from `display.providerCount`,
   or they push the QR off the screen.
@@ -546,12 +562,16 @@ costs one relay round trip, not two.
 
 ### Render the checkout
 
+Serve the compiled `styles.css` without Tailwind processing: import it from
+JavaScript (with a CSS-capable bundler) or use a plain `<link rel="stylesheet">`.
+Do not `@import` it into the host Tailwind entry. Its zero-specificity rules
+allow host styles to override checkout styles; scoping does not prevent that.
+
 The engine serves JSON checkout routes only — rendering is your view. Any
 OpenReceive frontend package works against the `/openreceive` mount; the
 smallest is the custom element (its default `prefix` is already
 `/openreceive`, and the package ships a self-contained `styles.css`; it is
-scoped to what OpenReceive renders, so it sits safely next to any CSS
-framework in any order). Laravel ships Vite, so the package installs like any
+scoped to what OpenReceive renders). Laravel ships Vite, so the package installs like any
 other frontend dependency:
 
 ```sh

data/skills/integrate-openreceive/references/next.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Next.js)
 
-These directions describe OpenReceive 0.4.6.
+These directions describe OpenReceive 0.4.9.
 
 Add OpenReceive to a Next.js App Router application — the app you are already
 working in. You do not need a copy of the OpenReceive source: the packages are
@@ -204,6 +204,8 @@ This list is the short form of https://openreceive.org/guides/checkout-ux.md, fo
 UI built on `@openreceive/browser/headless`. Read that before writing
 components.
 
+- Check Bitcoin → Switch payment method → Bitcoin: the grid must hide the
+  Lightning invoice, then restore the same bolt11 without another mint.
 - `createCheckoutController` is the engine. Do not hand-roll a poll loop.
 - `createCheckoutStatusModel` for the status line. Do not draw a
   Cart → Pay → Done stepper. Read the model's `phase`, not the snapshot's.
@@ -231,11 +233,25 @@ components.
   "switch payment method".
 - No "Open wallet" button on desktop.
 - Wallet suggestions: `getPaymentWizardRoutes()` +
-  `createWizardRouteDisplays`. Lightning only. Every image ships inside
-  the JavaScript — logos as data URIs, tutorials once `loadPayTutorialImages()`
-  resolves (`image` is `undefined` until then) — so serve nothing and set no
-  asset option. When it works, the logos and payment icons render; a missing
-  image means a CSP `img-src` that blocks `data:`, and the console names it.
+  `createWizardRouteDisplays`. Lightning only. Logos are data URIs; tutorial
+  images load from a JavaScript chunk. For a custom headless UI, load it when
+  a tutorial opens and look up the returned table by the tutorial's `path`:
+
+  ```js
+  import { loadPayTutorialImages } from "@openreceive/browser/headless";
+
+  const images = await loadPayTutorialImages();
+  const src = images[tutorial.path]; // data URI for the selected tutorial
+  ```
+
+  Render `src` as the image source and update your UI after loading. Existing
+  display objects do not update: their `tutorial.image` stays `undefined` if
+  created before loading. Alternatively, await the loader, recreate the displays
+  with `createWizardRouteDisplays`, and render the new `tutorial.image`.
+  Show the caption while loading or if loading fails; never use an empty image
+  source. Deploy all JavaScript chunks and allow `data:` in CSP `img-src`.
+  For missing images, check CSP errors, failed chunks, and stale displays.
+  Registry paths are lookup keys; there is no asset option or image route.
 
 ## More documentation
 
@@ -523,10 +539,13 @@ reference the current session may not see; the page can read the session and
 
 The checkout renders, polls, and settles itself. The compiled `styles.css`
 sheets (`@openreceive/react`, `@openreceive/elements`) are self-contained and
-scoped: every rule applies only inside what OpenReceive renders, so the sheet
-is safe next to any CSS framework (Tailwind, Mantine, your own reset) in any
-import order. No `transpilePackages` entry is needed; the packages ship plain
-ESM.
+scoped: every rule applies only inside what OpenReceive renders. No
+`transpilePackages` entry is needed; the packages ship plain ESM.
+
+Serve the compiled `styles.css` without Tailwind processing: import it from
+JavaScript (with a CSS-capable bundler) or use a plain `<link rel="stylesheet">`.
+Do not `@import` it into the host Tailwind entry. Its zero-specificity rules
+allow host styles to override checkout styles; scoping does not prevent that.
 
 `<Checkout>` is complete as rendered: it already shows the `description` from
 `amountFor` and the collapsed transaction-details panel. Do not build a custom

data/skills/integrate-openreceive/references/node.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Node.js)
 
-These directions describe OpenReceive 0.4.6.
+These directions describe OpenReceive 0.4.9.
 
 Add OpenReceive to a Node application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the packages are on npm, and the
@@ -190,6 +190,8 @@ This list is the short form of https://openreceive.org/guides/checkout-ux.md, fo
 UI built on `@openreceive/browser/headless`. Read that before writing
 components.
 
+- Check Bitcoin → Switch payment method → Bitcoin: the grid must hide the
+  Lightning invoice, then restore the same bolt11 without another mint.
 - `createCheckoutController` is the engine. Do not hand-roll a poll loop.
 - `createCheckoutStatusModel` for the status line. Do not draw a
   Cart → Pay → Done stepper. Read the model's `phase`, not the snapshot's.
@@ -217,11 +219,25 @@ components.
   "switch payment method".
 - No "Open wallet" button on desktop.
 - Wallet suggestions: `getPaymentWizardRoutes()` +
-  `createWizardRouteDisplays`. Lightning only. Every image ships inside
-  the JavaScript — logos as data URIs, tutorials once `loadPayTutorialImages()`
-  resolves (`image` is `undefined` until then) — so serve nothing and set no
-  asset option. When it works, the logos and payment icons render; a missing
-  image means a CSP `img-src` that blocks `data:`, and the console names it.
+  `createWizardRouteDisplays`. Lightning only. Logos are data URIs; tutorial
+  images load from a JavaScript chunk. For a custom headless UI, load it when
+  a tutorial opens and look up the returned table by the tutorial's `path`:
+
+  ```js
+  import { loadPayTutorialImages } from "@openreceive/browser/headless";
+
+  const images = await loadPayTutorialImages();
+  const src = images[tutorial.path]; // data URI for the selected tutorial
+  ```
+
+  Render `src` as the image source and update your UI after loading. Existing
+  display objects do not update: their `tutorial.image` stays `undefined` if
+  created before loading. Alternatively, await the loader, recreate the displays
+  with `createWizardRouteDisplays`, and render the new `tutorial.image`.
+  Show the caption while loading or if loading fails; never use an empty image
+  source. Deploy all JavaScript chunks and allow `data:` in CSP `img-src`.
+  For missing images, check CSP errors, failed chunks, and stale displays.
+  Registry paths are lookup keys; there is no asset option or image route.
 
 ## More documentation
 
@@ -451,8 +467,12 @@ import "@openreceive/react/styles.css";
 The checkout renders, polls, and settles itself. The compiled `styles.css`
 sheets (`@openreceive/react`, `@openreceive/elements`) are self-contained — a
 plain `<link rel="stylesheet">` works with no build step — and scoped: every
-rule applies only inside what OpenReceive renders, so the sheet is safe next
-to any CSS framework (Mantine, Bootstrap, your own reset) in any import order.
+rule applies only inside what OpenReceive renders.
+
+Serve the compiled `styles.css` without Tailwind processing: import it from
+JavaScript (with a CSS-capable bundler) or use a plain `<link rel="stylesheet">`.
+Do not `@import` it into the host Tailwind entry. Its zero-specificity rules
+allow host styles to override checkout styles; scoping does not prevent that.
 
 `<Checkout>` is complete as rendered: it already shows the `description` from
 `amountFor` and the collapsed transaction-details panel. Do not build a custom

data/skills/integrate-openreceive/references/php.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (PHP)
 
-These directions describe OpenReceive 0.4.6.
+These directions describe OpenReceive 0.4.9.
 
 Add OpenReceive to a PHP application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the engine is on Packagist
@@ -216,6 +216,8 @@ The drop-in (`<openreceive-checkout>`, from the release's standalone tarball or
 of https://openreceive.org/guides/checkout-ux.md, for a UI built on
 `@openreceive/browser/headless`. Read that before writing components.
 
+- Check Bitcoin → Switch payment method → Bitcoin: the grid must hide the
+  Lightning invoice, then restore the same bolt11 without another mint.
 - `createCheckoutController` is the engine. Do not hand-roll a poll loop.
 - `createCheckoutStatusModel` for the status line. Do not draw a
   Cart → Pay → Done stepper. Read the model's `phase`, not the snapshot's.
@@ -243,11 +245,25 @@ of https://openreceive.org/guides/checkout-ux.md, for a UI built on
   "switch payment method".
 - No "Open wallet" button on desktop.
 - Wallet suggestions: `getPaymentWizardRoutes()` +
-  `createWizardRouteDisplays`. Lightning only. Every image ships inside
-  the JavaScript — logos as data URIs, tutorials once `loadPayTutorialImages()`
-  resolves (`image` is `undefined` until then) — so serve nothing and set no
-  asset option. When it works, the logos and payment icons render; a missing
-  image means a CSP `img-src` that blocks `data:`, and the console names it.
+  `createWizardRouteDisplays`. Lightning only. Logos are data URIs; tutorial
+  images load from a JavaScript chunk. For a custom headless UI, load it when
+  a tutorial opens and look up the returned table by the tutorial's `path`:
+
+  ```js
+  import { loadPayTutorialImages } from "@openreceive/browser/headless";
+
+  const images = await loadPayTutorialImages();
+  const src = images[tutorial.path]; // data URI for the selected tutorial
+  ```
+
+  Render `src` as the image source and update your UI after loading. Existing
+  display objects do not update: their `tutorial.image` stays `undefined` if
+  created before loading. Alternatively, await the loader, recreate the displays
+  with `createWizardRouteDisplays`, and render the new `tutorial.image`.
+  Show the caption while loading or if loading fails; never use an empty image
+  source. Deploy all JavaScript chunks and allow `data:` in CSP `img-src`.
+  For missing images, check CSP errors, failed chunks, and stale displays.
+  Registry paths are lookup keys; there is no asset option or image route.
 
 ## More documentation
 
@@ -499,6 +515,11 @@ and the browser snapshots are snake_case throughout.
 
 ### 5. Render checkout
 
+Serve the compiled `styles.css` without Tailwind processing: import it from
+JavaScript (with a CSS-capable bundler) or use a plain `<link rel="stylesheet">`.
+Do not `@import` it into the host Tailwind entry. Its zero-specificity rules
+allow host styles to override checkout styles; scoping does not prevent that.
+
 Unpack the release's `standalone-checkout-<version>.tar.gz` into a directory
 your web server serves — `public/openreceive/` here — and add two tags plus
 the element:
@@ -515,8 +536,7 @@ the element:
 
 The module registers `<openreceive-checkout>` as it loads; the element creates
 the checkout for `reference`, then renders, polls and settles itself. The
-stylesheet is scoped to what OpenReceive renders, so it sits safely next to
-any CSS framework. The checkout follows the payer's theme; on a page that is
+stylesheet is scoped to what OpenReceive renders. The checkout follows the payer's theme; on a page that is
 always one theme, lock it with `theme="dark"`. React/Vue/Svelte/Angular apps
 use the matching wrapper package instead — same attributes
 ([Frontend checkout](https://openreceive.org/guides/frontend-checkout.md)); a custom UI builds on

data/skills/integrate-openreceive/references/rails.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (Rails)
 
-These directions describe OpenReceive 0.4.6.
+These directions describe OpenReceive 0.4.9.
 
 Add OpenReceive to a Rails application — the app you are already working in. You
 do not need a copy of the OpenReceive source: the gem is on RubyGems, the
@@ -197,6 +197,8 @@ The engine serves JSON only, so the view is yours — but the drop-ins
 list is the short form of https://openreceive.org/guides/checkout-ux.md, for a UI
 built on `@openreceive/browser/headless`. Read that before writing components.
 
+- Check Bitcoin → Switch payment method → Bitcoin: the grid must hide the
+  Lightning invoice, then restore the same bolt11 without another mint.
 - `createCheckoutController` is the engine. Do not hand-roll a poll loop.
 - `createCheckoutStatusModel` for the status line. Do not draw a
   Cart → Pay → Done stepper. Read the model's `phase`, not the snapshot's.
@@ -224,11 +226,25 @@ built on `@openreceive/browser/headless`. Read that before writing components.
   "switch payment method".
 - No "Open wallet" button on desktop.
 - Wallet suggestions: `getPaymentWizardRoutes()` +
-  `createWizardRouteDisplays`. Lightning only. Every image ships inside
-  the JavaScript — logos as data URIs, tutorials once `loadPayTutorialImages()`
-  resolves (`image` is `undefined` until then) — so serve nothing and set no
-  asset option. When it works, the logos and payment icons render; a missing
-  image means a CSP `img-src` that blocks `data:`, and the console names it.
+  `createWizardRouteDisplays`. Lightning only. Logos are data URIs; tutorial
+  images load from a JavaScript chunk. For a custom headless UI, load it when
+  a tutorial opens and look up the returned table by the tutorial's `path`:
+
+  ```js
+  import { loadPayTutorialImages } from "@openreceive/browser/headless";
+
+  const images = await loadPayTutorialImages();
+  const src = images[tutorial.path]; // data URI for the selected tutorial
+  ```
+
+  Render `src` as the image source and update your UI after loading. Existing
+  display objects do not update: their `tutorial.image` stays `undefined` if
+  created before loading. Alternatively, await the loader, recreate the displays
+  with `createWizardRouteDisplays`, and render the new `tutorial.image`.
+  Show the caption while loading or if loading fails; never use an empty image
+  source. Deploy all JavaScript chunks and allow `data:` in CSP `img-src`.
+  For missing images, check CSP errors, failed chunks, and stale displays.
+  Registry paths are lookup keys; there is no asset option or image route.
   The registry answers ~37 wallets: pass
   `providerPreviewLimit` and build "show all" from `display.providerCount`,
   or they push the QR off the screen.
@@ -521,12 +537,16 @@ consoles) the client is built lazily so no live wallet is needed.
 
 ### Render the checkout
 
+Serve the compiled `styles.css` without Tailwind processing: import it from
+JavaScript (with a CSS-capable bundler) or use a plain `<link rel="stylesheet">`.
+Do not `@import` it into the host Tailwind entry. Its zero-specificity rules
+allow host styles to override checkout styles; scoping does not prevent that.
+
 The engine serves JSON checkout routes only — rendering is your view. Any
 OpenReceive frontend package works against the `/openreceive` mount; the
 smallest is the custom element (its default `prefix` is already
 `/openreceive`, and the package ships a self-contained `styles.css` a plain
-stylesheet link can serve; it is scoped to what OpenReceive renders, so it
-sits safely next to any CSS framework in any order):
+stylesheet link can serve; it is scoped to what OpenReceive renders):
 
 ```erb
 <%# app/views/orders/pay.html.erb %>
@@ -534,7 +554,7 @@ sits safely next to any CSS framework in any order):
 ```
 
 ```js
-// In your JS bundle (importmap/esbuild/webpacker):
+// In your JS bundle (esbuild/webpacker with CSS support):
 import { defineElements } from "@openreceive/elements";
 import "@openreceive/elements/styles.css"; // or link the compiled styles.css
 

data/skills/integrate-openreceive/references/woocommerce.md

@@ -1,6 +1,6 @@
 # OpenReceive agent directions (WordPress + WooCommerce)
 
-These directions describe OpenReceive 0.4.6.
+These directions describe OpenReceive 0.4.9.
 
 Install and configure the OpenReceive gateway in the existing WooCommerce
 store. Preserve its theme, checkout, customer accounts, order model and prices.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openreceive-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.6
+  version: 0.4.9
 platform: ruby
 authors:
 - OpenReceive
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.4.6
+        version: 0.4.9
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.4.6
+        version: 0.4.9
 - !ruby/object:Gem::Dependency
   name: openreceive-server
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.4.6
+        version: 0.4.9
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.4.6
+        version: 0.4.9
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement