solana-studio 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b69fe07789c9b9f7f1db1627257d1bf48b9f4a0c8008d041737c56eeba6cf39c
-  data.tar.gz: 73c86733f7b77f5ace0cec51a59c5cc003d2fc728ce45d868b429abd0963bf45
+  metadata.gz: 752d18d346d95e1960408a04f03b7879bb25f34dfa3851a233e9070db6a1ec4d
+  data.tar.gz: 4d7bcb63da94cb07279077dc525f35a0e11df1e104cad6538d67e15261311ae5
 SHA512:
-  metadata.gz: ba01f48f7ae0f245db23c4d782b7b195f7cc7bea2e6dc59c8e657a2226e59d616fe09cc2ac88cc8024575bb5835576b4f50e5d1c4fdf0275e97e0d417cb320f8
-  data.tar.gz: ee63a339452249039f48ab8ce681d45e308a17c334230ec2cfd7887a05327529d9973694288a94d06f32333450a4a04ab2f7f26f9e5d5f4ef0c147db59c67754
+  metadata.gz: 2d265a31b6049386a96f286cabd2abd0dbd94520c068cccc5827c58c5b407ee75d95875c20aec7d9bb8893891f6ec26bd02a28acc5d565a6c6efb5378906ee08
+  data.tar.gz: 62a5d328df9adf8f2959bc3137b4d07b7345ca5e83841dcc69f572d84f46b5fe78c62863482a50550a50d916178aefb67a5d14157c85c1eb16d499de4a9fd0d2

data/CHANGELOG.md

@@ -5,17 +5,24 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 ## Unreleased
 
 ### Added
+- **Wallet failures on both web3 modals now reach the host's error log** (`app/views/solana_studio/modals/_wallet_connect.html.erb`, `_web3_step_up.html.erb`). Each catch block already mapped the wallet's throw into a paragraph and stopped there, so every rejection on this surface died in the browser. Both now call the host's optional `window.reportWalletFailure(stage, provider, raw, mapped)` behind a `typeof` guard, with stage `wallet_connect` and `web3_step_up`. **The reporter and its endpoint stay HOST-owned, and that is a dependency call rather than a convenience**: by the two-axis test in `docs/agents/modules/modal-lifecycle.md` neither axis fires on the reporter — it needs no gem code to render and binds to no wallet/chain runtime, only `fetch` and a CSRF meta every base app already has — so it is not solana-studio-bound, and what makes it LOOK gem-shaped is subject matter, the error that module names outright (`blocks/_wallet_brand_sprite` is wallet-depicting and engine-owned for the same reason). The decisive half is that the ENDPOINT cannot move: it writes an `ErrorLog` through `rescue_and_log`, and `lib/solana_studio/engine.rb` mounts no routes by design. A gem-side reporter would therefore be half a mechanism whose other half every consumer still hand-rolls, and its failure mode would upgrade from silence to a **silent 404** on a surface that now looks wired — harder to catch than the darkness it replaced. The graduation trigger has not fired either: one app has the reporter, zero second adopters, and the module's rule is a second app that has ALREADY shipped the shape, never a forecast. What answers the rediscovery cost instead is DECLARING the contract where a consumer meets it — both partial headers and a new README section now name all six host globals, what each absence degrades, and the four-value body.
 - **An optional `on_click` local on the wallet sign-in button** (`app/views/solana_studio/auth/_wallet_credential.html.erb`). The click was hardcoded to swap straight to the wallet-connect picker, and that single line blocked Turf Monster's adoption: its board stages a contest lineup in `localStorage`, the picker's redirect is UNCONDITIONAL, and `pendingContestEntry` has exactly one writer app-wide with no `beforeunload` fallback and no server draft for guests — so the default handler navigates away with a staged lineup never written anywhere. Lost, not mis-routed. Turf passes `on_click: "openWalletHub()"` and lets its own board listener save the cart and swap. **The seam is the TAIL of the handler, not the whole of it**: `attested()` stays template text no local can reach, so a host cannot drop the legal-age gate by simply never calling it, which a seam carrying the whole handler could — and the button would look and behave perfectly normal. Keeping the gate out of the local guarantees it is CALLED; making it CONTROL the tail needed one more step, because both land in ONE JavaScript expression and precedence decides which wins. `&&` binds tighter than `||`, `?:` and comma, so an override built on any of those reparsed and ran its tail with the gate FALSE — measured in Chromium against the vendored Alpine 3.16.1, where `on_click: "saveCart() || openWalletHub()"` ran `openWalletHub()` with the box unticked. The override is now **parenthesised** before it is emitted, so any expression is safe to pass. Never reachable in a shipped release: the seam has not shipped, and byte-identity proves no host passes the local. A host that passes no locals renders **byte-identical** output, measured by rendering the partial before and after and diffing, not asserted.
 - **The wallet sign-in button, contributed into studio-engine's auth modal** (`app/views/solana_studio/auth/_wallet_credential.html.erb`). Part of the base/bolt-on split: studio-engine plus McRitchie Studio is the template every app is built from, web2 and web3 alike, and this gem plus Turf Monster is the web3 bolt-on. Sign-in is a base concern so the modal stays in the engine; **wallets are not**, so the button moved here. The engine renders whatever resolves at `solana_studio/auth/wallet_credential` and nothing when the path is empty, so bundling this gem IS the registration and a web2 app carries no wallet markup at all. Deliberately NOT solved by giving this gem its own auth modal: that would fork a surface both apps sign in through, which is how the wallet picker reached three drifting copies before it was promoted. The engine keeps both halves of the existing gate (`Studio.auth_method?(:wallet)` and `Studio.feature?(:web3)`) so the hub — which bundles this gem for its signing primitives with web3 off — still renders a web2 sign-in modal.
 - **The web3 modals move here** — `solana_studio/modals/wallet_connect`, `solana_studio/modals/web3_step_up`, `solana_studio/phantom_deeplink` and `solana_studio/deeplink_assets`, promoted out of studio-engine byte for byte. They are Solana-specific to the last line, and studio-engine is the engine EVERY app bundles, including apps that ship no chain feature at all. Only the home changes: the markup, the locals and the behaviour are identical, and the four files are added here before studio-engine drops its copies, so no consumer is ever without a home for them.
 
 ### Changed
+- **Both catch blocks capture the wallet's RAW string before the mapper runs.** `raw` was previously an inline sub-expression consumed by the ternary and discarded; it is now a named binding sent alongside the mapped sentence. Only the pair makes a MIS-mapping diagnosable, and the 2026-09-06 incident WAS a correct mapper meeting a string it had never seen — with only the mapped half in hand there is nothing to notice. The 4001 decline path keeps the wallet's own words as `raw` while the user still reads `Signature rejected`.
+- **The report call is wrapped in its own `try`/`catch`, which is NOT redundant with the reporter's.** This gem does not own the reporter; a host does, and a host's implementation may throw. At the step-up call site that is load-bearing rather than defensive: `this.connecting = false` sits OUTSIDE the catch block, so a throw from the reporter skips it and leaves the sign-in button disabled forever with an error the user cannot retry — and Alpine swallows a throw out of an async handler, so nothing anywhere would say so. An observer that can wedge the card is a worse bug than the darkness it was added to fix. The call is also the LAST statement in each block, after every user-facing assignment: observation may not delay, block or alter the line the user has just been handed.
+- **Neither call site reports an error already tagged `walletFailureReported`.** A host's `solanaConnectAndVerify` substitutes its own sentence for an unusable wallet and reports the pair from in there, where the wallet's words still exist; reporting again from the surface files a second row whose `raw` and `mapped` are BOTH the host's sentence — the useless row, and the one an operator meets first.
 - **The wallet step-up card leads with the WALLET, not a padlock** (`app/views/solana_studio/modals/_web3_step_up.html.erb`). Four operator edits in one pass. (1) The card's mark is now the remembered brand's own sprite at 56px, falling back to the neutral billfold this file already draws for its no-brand button — it replaces a lock emoji, on the reasoning that a card asking someone to reach for a specific object should show them the object. Hand-rolled rather than passed to `studio/modals/blocks/_card_header`, because that block takes an emoji, a spinner or one of two fixed icons and has NO slot for a brand mark; its else-branch paints a check tinted with the host's `primary` token. Per the modal-lifecycle module the trigger for a primitive is a second consumer or a third copy, and this is the first — when a second card wants a brand header, add an icon slot to `card_header` rather than a second hand-rolled one. (2) The default `subtext` drops from four lines to one: *This account is secured by a Solana wallet. You are signed in, but this session can't sign on-chain — so on-chain actions still need your wallet.* becomes *Your account is secured by a Solana wallet.* **A host that overrides `subtext` never sees this** — see Notes for hosts. (3) The truncated address moved UP out of the footnote into the body, inside an `x-if` on `walletHint`, so the card names the wallet it is asking for where the sentence is rather than under the button. The footnote it replaces is gone. (4) The **full-width "Use a different wallet" row is gone**, replaced by a quiet **"Not your wallet?" link beside the address** — same `openPicker()` handler, a fraction of the layout, and the card still runs CTA → `Not now`. Both are operator calls. The link carries TWO gates and they answer different questions: the `x-if` is `walletHint` (no address, no sentence to correct) and the `x-show` is `canOneClick` (with no remembered brand the PRIMARY button is already the picker, so the link would be a second door into the same room). **Those two states are not the same** — an account that linked its wallet before the host stored the brand has an address and no brand — which is why the link needs both. Without it the address made a mismatch VISIBLE without making it ACTIONABLE: `providerMissing` is written in exactly one place, inside `signIn()` after the `reachable()` guard, so nothing auto-flips, and a remembered wallet that was simply the WRONG one had no route to the picker at all.
 - **The body block carries `mb-5`, and that is a FIX rather than a taste change.** The old callsite passed a BLOCK to `card_header`, which wraps `yield` in a `<p>` of its own — so the rendered card emitted `<p class="text-xs text-secondary mb-5"><p class="text-sm text-body">` and the HTML parser auto-closed it into a stray EMPTY paragraph. That empty paragraph WAS the body-to-CTA gap. Hand-rolling the header removed the accident, so the margin now has to be declared. Both new icon branches also carry `aria-hidden`, which `card_header`'s svg did not.
 - **The wallet button's visibility gate tolerates a host that never defined `methodOn`.** `x-show="methodOn('wallet')"` became `x-show="typeof methodOn === 'function' ? methodOn('wallet') : true"`. A bare call in a host without the member THROWS, Alpine grades the throw as falsy, and the button **silently never renders** — no error a user can see, no missing asset, nothing in the page to debug. That was the second, independent blocker on Turf Monster's adoption, and it is invisible by construction. MEASURED in Chromium against the vendored Alpine 3.16.1, driving the real rendered markup: without the guard the console carries `methodOn is not defined` and the button resolves to `display:none`; with it the button shows, and a host that DOES define `methodOn` still follows the toggle in **both** directions. The fallback is `true` rather than false because bundling the gem has already answered *is wallet implemented* — a host with no toggle has expressed no opinion about showing it, and defaulting to false rebuilds the same invisible button from the other side. The test stays in **Alpine** deliberately: Ruby decides whether the partial EXISTS and Alpine decides whether it SHOWS, and folding the visibility into Ruby collapses that split and brings back the floating-divider bug on a toggle page.
 - `.github/workflows/gem-ci.yml` asserts all four new partials are inside the BUILT gem, not just the manifest. `test/gemspec_test.rb` already asserts the invariant that every `app/` file reaches `spec.files`; the artifact check is a different claim, and only the artifact is what a consumer installs.
 
 ### Tests
+- **`e2e/wallet_failure_report.spec.js` (7, new)** — the reporting seam in a real Chromium, against both real partials through the engine's real modal host. It is the only tier that can see it: every line under test is inlined JavaScript inside an `x-data` attribute, so a Ruby test can assert the characters shipped but cannot run them. **FAIL-OPEN IS PROVED BY A REAL THROW.** The trap on the consumer half of this feature was that `fetch()` RESOLVES on 4xx/5xx, so four specs stubbing a 500 stayed green with the error handling deleted; the equivalent trap here is different in shape and identical in kind, and only a host reporter that genuinely throws exercises the gem's guard. **10 mutants, all 10 killed**, each shown applied by its own diffstat against a 19/19 green baseline and reverted after: the picker sending the other surface's stage; `raw` and `mapped` swapped; `raw` captured AFTER the mapper so both halves are the mapped one; the 4001 branch overwriting `raw` with our sentence; the `try`/`catch` unwrapped at each call site separately; the `typeof` guard negated; the `walletFailureReported` check dropped; and the report REORDERED above the user-facing assignment. Two are recorded because the first measurement was wrong and the correction is the finding: negating the `typeof` guard SURVIVED the absent-reporter spec, because the surrounding `try`/`catch` swallows the resulting `TypeError` — the two guards are genuinely redundant AT THAT SEAM, each covering the other. It is killed by the present-reporter specs instead (a negated guard reports nothing at all), and removing the PAIR together takes the absent-reporter spec red, which is what proves that spec is not inert. Single-mutating either guard alone could never have shown this.
+- **`test/e2e_lane_contract_test.rb`** — the new lab page is asserted to render both gem partials and the engine's real host BY NAME, and refuted from ever CALLING `window.reportWalletFailure`. The page legitimately DEFINES that global (it is the host's to provide and the lab is the host); a lab that also invoked it would satisfy every reporting spec while the gem's call sites never fired.
+- `config/e2e_lane.yml` 12 -> 19 specs, derived with `npx playwright test --list` rather than counted by hand, per the file's own instruction.
 - **`test/views/web3_step_up_modal_test.rb` (17 -> 24)** — seven tests for the polish pass above, one of them the CONTROL that keeps the other six honest. **The first version of them was INERT and this is recorded because the failure mode is invisible from inside the file**: they asserted `'#se-wallet-' + provider` and `canOneClick` against the WHOLE rendered card, and both strings already lived in it — the first in the pre-existing 36px CTA row, the second in the x-data getter. Deleting the ENTIRE new brand header left the suite at 22 runs / 118 assertions / **0 failures** while a probe on the same tree confirmed the header was gone from the HTML (header div present true->false, `w-14 h-14` tiles 3->0, sprite-binding sites 2->1). **Six of nine mutants survived.** The fix is STRUCTURAL rather than a longer string: `brand_header` slices the element immediately ABOVE the heading and `header_branch` slices one `x-if` branch of it by its GUARD, so no assertion can be satisfied by markup elsewhere in the card and a swap of the two branches moves the markup to the other guard. `test_the_header_slice_can_come_up_empty` is the control — strip the header from the rendered HTML and the slice must find no branch — and it is not decorative: widening `brand_header` to the whole card takes it RED against the CTA row, which is the original bug reproduced. Re-measured on the SHIPPED tree across **20 mutants, every one KILLED, no survivors**, each shown to reach the file by its own diffstat against a baseline of **24 runs / 151 assertions / 0 failures**, restored clean after every one. The card: delete the whole header (+0/-15, 2 failures), swap its two branches (+5/-5), delete the billfold fallback (+0/-8), hardcode the mark to `#se-wallet-phantom` (+1/-1), drop both `x-if` guards (+0/-4), an HTML-entity padlock (+1/-6) and a literal-codepoint one (+1/-6) — **both** forms, because `&#128274;` renders identically and sails past a codepoint-only refutation — restore the alternate-wallet row (+4/-0), `mb-5` -> `mb-0` (+1/-1), and the margin drifting onto an empty neighbour (+2/-1, 4 failures). The correction link: delete it (+1/-3), move it OUTSIDE the `walletHint` guard (+4/-3), point it at `dismiss()` (+1/-1), drop the `canOneClick` gate (+1/-1), INVERT that gate (+1/-1), relabel it as the row it replaced (+1/-1, 2 failures), let it grow back to `w-full` (+1/-1), delete the address and keep the link (+1/-2, 2 failures), split the nowrap group so the link wraps onto its own line (+1/-1), and unguard the address line entirely (+0/-1, 2 failures). The link and the address are asserted SEPARATELY even though they share one block, because an assertion matching the block as a whole cannot say which half broke — the same shape as the inert-header bug.
 - **`test/views/auth_wallet_credential_test.rb`** (14, new) — the RENDER tier for the credential button, which this gem never had. It is the tier that can see this change at all: the default handler is assembled by ERB, so the string hosts depend on appears ZERO times in the template source and a source grep stays green on a partial whose default never reaches the attribute. Pins the default handler against the literal previous bytes, the default tracking `modal_store` (a hardcoded `"modals"` would give the style guide a dead button), the override replacing the default, the override leaving **no** trace of it, the age gate LEADING an override — narrowly, and the assertion now says so, because `start_with?` cannot see whether the gate also CONTROLS the tail — the handler reaching the page **unescaped** — read from the RAW html, never the parsed attribute, because Nokogiri decodes entities and the assertion would otherwise pass on the very bug it exists to catch — the default carrying no double quote that would close the attribute, and both halves of the visibility gate. Mutation-proven five ways, every mode red: dropping `raw`, hardcoding the store name, reverting the gate to the bare call, letting `on_click` swallow the age gate, and dropping the picker's props. A **behavioural tier** was added alongside the string assertions: it runs the rendered handler in a real JS engine, built the way Alpine builds it, and asserts the gate CONTROLS the tail for every top-level operator that binds looser than `&&`. It carries its own control — the pre-fix spelling, asserted to STILL bypass — so a harness that quietly stopped seeing anything goes red instead of green. Both were mutation-proven: blanking the harness took three tests red, pinning `attested()` to a constant took two.
 - `test/auth_credential_test.rb` (7 -> 11): the partial sits at the path the engine resolves, the click handler consults the modal's age gate, visibility binds to the shared `methodOn('wallet')` toggle, `modal_store` is required with no default, the swap carries the picker's `backTo`/`ageAttested` contract, the brand gradient id is namespaced against collisions, and the mark stays inline rather than becoming a sprockets asset request. Every assertion reads ERB-comment-stripped source, because this file documents its own contract in prose and a bare grep would match the paragraph instead of the code — proven by mutating the gate into a comment and watching it go red. The `on_click` assertion is bound to the CONCERN rather than one spelling of it: it pinned `fetch(:on_click) do`, which went red when the precedence fix traded that for a `key?` branch while preserving every property the assertion existed to protect. It now asserts the local is read through an accessor that tolerates its ABSENCE, which is the thing that actually matters. A new assertion pins the parentheses around an overridden tail, labelled as the WEAKER copy — it matches characters, and the render tier next door is the authority.
@@ -24,6 +31,9 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 - **`test/erb_comment_leak_test.rb`** (6) — ported from studio-engine, whose glob stops covering these files the moment they leave it. An ERB comment ends at its FIRST close sequence, so a comment quoting a tag leaks its tail into the page as visible prose; the two most comment-dense files in the move (`_wallet_connect`, `_web3_step_up`, 8 comments each) were exactly the ones losing the guard. All three leak signatures ported with their guard-the-guard probes, and mutation-proved on a real moved file.
 
 ### Notes for hosts
+- **Nothing changes for a host that does nothing.** `window.reportWalletFailure` is optional and guarded; a consumer that never defines it renders and behaves exactly as on 0.6.1, with wallet failures recorded nowhere — the state every consumer is in today. This is additive, and there is no migration.
+- **To light the surface up you must build the endpoint; the gem cannot.** It mounts no routes, so define `window.reportWalletFailure(stage, provider, raw, mapped)` and a path for it to POST to. Four things are worth copying rather than re-deriving, each of which cost something to learn: (1) record **both** message halves — a mis-mapping is invisible in the mapped half alone; (2) **scrub `raw` server-side** — it is free text a WALLET composed, and a wallet can quote your own nonce back at you inside a field your key allowlist has already approved, so redact by VALUE as well as by key, and leave the pubkey alone because over-redaction blinds the tool; (3) make it **fire and forget** — no `await`, swallow your own faults, and answer the same status whether or not you recorded anything, so no caller can block a user on observation; (4) tag any error you rethrow after substituting your own sentence with `walletFailureReported = true`, and report it from where you made the substitution, or the surface files a second useless row. turf-monster's `app/javascript/solana_errors.js` and `Solana::ClientFailureReport` are the worked example.
+- **Stage strings are a filter, so spell them exactly.** The picker sends `wallet_connect` and the step-up card sends `web3_step_up`. A host whose server normalises an unrecognised stage to `unknown` will still record the row, but it loses the one field triage runs on.
 - **The "Use a different wallet" row is GONE, and a host bound to it goes red at its next lock bump, not at this PR.** This gem ships only `.github/workflows/gem-ci.yml` — there is no consumer lane — so a green CI here cannot see a consumer at all. turf-monster bound to that row in TWO places: `test/controllers/web3_step_up_gallery_test.rb` ("a remembered wallet still offers a way to use another one", asserting both the label and `openPicker()`) and `e2e/web3_step_up.spec.js`, which does not merely assert copy — it clicks the row and walks step-up -> wallet-connect -> Back -> step-up, checking the props survive the round trip. It breaks at `bump_consumer_locks_for_qa` during the next `qa-release` sweep, which runs `bundle lock --update solana-studio --conservative` on every consumer. **THE ROUTE SURVIVES, ITS SPELLING DOES NOT.** A quiet **"Not your wallet?"** link beside the address calls the same `openPicker()` the row called, so a consumer's picker round trip is REPOINTED rather than deleted. Write that locator to accept EITHER spelling (`/Use a different wallet|Not your wallet\?/`) if the spec must be green on both sides of the bump — a consumer's own CI resolves the PUBLISHED gem, so a spec pinned to the new label is red on that consumer's PR and a spec pinned to the old one is red at the sweep. turf-monster's two files now do exactly that. The other unchanged route is the no-remembered-brand one: the "Connect your wallet" button IS `openPicker()` in both releases. Why the link exists at all, since the acceptance never named the cost: `providerMissing` is written in exactly ONE place (inside `signIn()`, after the `reachable()` guard) and nothing in `init()`, `refresh()` or the poll touches it, so there is no auto-flip — without the link a remembered-but-UNREACHABLE wallet had to press a button that could not work and read an error before the no-brand row appeared, and a remembered, REACHABLE, but WRONG wallet had no route to the picker at all. It is advisory either way: the session stays usable, `Not now` exits, and the help line still reaches a human.
 - **The default `subtext` is one line now, and a host that OVERRIDES it sees none of that.** turf-monster passed its own four-line `subtext:`, so the gem's default changed and the card a player actually met did not — it kept the long copy AND gained the new address line, which is more copy rather than less. If you override `subtext`, this release is the moment to decide whether you still mean to. This gem's own `test/views/web3_step_up_modal_test.rb` refutes the string `this session can`, which was live in a consumer's override at the time this shipped.
 - **RESOLVED — studio-engine's style-guide specimen no longer pins the OLD gate string.** This entry warned that `test/views/style_web3_specimens_test.rb` asserted the literal `x-show="methodOn('wallet')"`, which the new gate does not contain, and that it would go red the moment the engine bumped past this gem. Both halves have since moved and the warning is kept as provenance rather than as live guidance. Re-derived 2026-09-06: studio-engine's `Gemfile.lock` now resolves **solana-studio 0.6.0** (not the 0.5.3 this note was written against), and its assertion is now `assert_includes gate, "methodOn('wallet')"` — the SUBSTRING form this note asked for, landed by its own commit *Bind the wallet gate assertion to the CTA element*. The gate it reads, `typeof methodOn === 'function' ? methodOn('wallet') : true`, contains that substring, so the engine is green on the current pin. Nothing to do; the recorded reasoning stands, which is why it is corrected here rather than deleted.

data/README.md

@@ -349,6 +349,63 @@ exists to prevent — so this is a documented host requirement, not something th
 gem can enforce from inside. `solana_studio/modals/network_mismatch` already
 shipped on exactly these terms.
 
+#### The host JavaScript these modals reach for
+
+Every global below belongs to the **host**. This gem ships one JavaScript file
+(`solana_studio/network_guard.js`) and **no routes at all**, so none of these can
+live here. Each is reached behind a `typeof` guard: an absent one degrades the
+card rather than breaking it, and the whole point of writing the list down is
+that a consumer meets it here instead of rediscovering it.
+
+| Global | Needed by | Absent means |
+|---|---|---|
+| `window.solanaConnectAndVerify(name, opts)` | both | **required** — nothing can connect |
+| `window.walletProvider` | both | **required** — no wallet rows paint |
+| `window.handleSolanaVerifySuccess(result)` | both | no post-verify hook runs |
+| `window.startPhantomDeepLink(linkMode, userId)` | picker | the mobile Phantom row is hidden |
+| `parseSolanaError(msg)` | both | the wallet's raw words are shown unmapped |
+| `window.reportWalletFailure(stage, provider, raw, mapped)` | both | **this surface is dark** |
+
+##### `reportWalletFailure`, and why the endpoint is yours
+
+Everything on the wallet surface fails **client-side**: the throw is caught,
+mapped, and painted into a paragraph. Without this call nothing about it exists
+outside the browser — which is how a user whose Phantom held no keypair was told
+to check their USDC balance seven times in one production session (2026-09-06)
+before an operator noticed by hand.
+
+The gem calls it; it does not implement it. **The reporter and its endpoint are
+host-owned because they need an `ErrorLog` this gem cannot assume** — the engine
+here mounts no routes by design, so a gem-side reporter would POST at a path a
+consumer is not guaranteed to have, and a report that 404s silently is strictly
+worse than the silence it replaced: the surface still looks wired. Reference
+implementation in turf-monster: `app/javascript/solana_errors.js`, receiving at
+`POST /auth/solana/report_failure`.
+
+The contract the call sites keep:
+
+- **Called once per caught rejection**, with the stage for that surface —
+  `'wallet_connect'` from the picker, `'web3_step_up'` from the step-up card. A
+  stage the host does not recognise should be recorded, not refused; the report
+  is still worth having.
+- **Both message halves, always.** `raw` is what the wallet said, captured before
+  the mapper runs; `mapped` is what the user read. A **mis-mapping** is invisible
+  in the mapped half alone, and that is the failure the 2026-09-06 incident
+  actually was — a correct mapper meeting a string it had never seen.
+- **Skipped when the error is already tagged `walletFailureReported`.** Set that
+  property on any error your `solanaConnectAndVerify` rethrows after substituting
+  a sentence of your own, and report it from in there, where the wallet's words
+  still exist. Without the tag the same failure files a second row carrying your
+  sentence in both halves — the useless row, and the one an operator meets first.
+- **Fire and forget.** The return value is ignored and a **throw is swallowed**.
+  Do not rely on that: a reporter that throws is a bug, and the guard exists
+  because an observer must never become the incident.
+- **Four values, and only these four.** No signature, no nonce, no signed SIWS
+  message — the modals never hold any of them, so none can leak. `raw` is free
+  text a **wallet** composed, so scrub it **server-side**: a wallet can quote your
+  own nonce back at you inside a field your key allowlist has already approved. A
+  pubkey is fine and should be kept; over-redaction blinds the tool.
+
 #### The signed statement is not configurable
 
 `solana_studio/phantom_deeplink` emits `Studio.wallet_sign_in_statement`, and it

data/app/views/solana_studio/modals/_wallet_connect.html.erb

@@ -76,6 +76,42 @@
                          browser, or to do something else entirely. The default
                          calls window.startPhantomDeepLink(linkMode, userId).
     onBack()             the Back button; DEFAULT closes the modal
+
+  CONTRACT WITH THE HOST'S JS. This gem ships one JavaScript file
+  (solana_studio/network_guard.js) and no routes at all, so every global below is
+  the HOST'S to provide. Each is reached behind a `typeof` guard, and an absent
+  one degrades this card rather than breaking it — which is the whole reason the
+  list is written down here instead of being rediscovered per consumer.
+
+    window[connect_fn]              REQUIRED. Connect + verify. Default
+                                    window.solanaConnectAndVerify.
+    window.walletProvider           REQUIRED for the rows: .available() lists the
+                                    detected wallets this card paints.
+    parseSolanaError(msg)           optional. Maps a wallet string to a sentence
+                                    a user can act on; absent means the wallet's
+                                    own words are shown unmapped.
+    window.handleSolanaVerifySuccess(result)
+                                    optional. Post-verify hook on the happy path.
+    window.startPhantomDeepLink(linkMode, userId)
+                                    optional. The mobile deep link; absent hides
+                                    the Phantom deep-link row entirely.
+    window.reportWalletFailure(stage, provider, raw, mapped)
+                                    optional. Fire-and-forget observation, called
+                                    ONCE per caught rejection with stage
+                                    'wallet_connect'. `raw` is what the wallet
+                                    said and `mapped` is what the user was shown;
+                                    a host that records only one half cannot
+                                    diagnose a MIS-mapping, which is the failure
+                                    this exists for. Return value is ignored and
+                                    a throw is swallowed — see the call site.
+                                    Absent means this surface is DARK: the user
+                                    is served correctly and nothing is recorded
+                                    anywhere. Reference implementation and the
+                                    receiving endpoint (both host-owned, because
+                                    they need an ErrorLog this gem cannot assume)
+                                    live in turf-monster:
+                                    app/javascript/solana_errors.js and
+                                    POST /auth/solana/report_failure.
 %>
 <%
   store      = local_assigns.fetch(:store, "modals")
@@ -195,9 +231,46 @@
              this.connecting = false; this.picking = '';
            }
          } catch (e) {
-           var msg = (e && e.code === 4001) ? 'Signature rejected' : ((e && e.message) || 'Connection failed');
+           // BOTH HALVES OR NEITHER. raw is what the WALLET said, captured
+           // before the mapper runs; msg is what the user reads. A mis-mapping
+           // is invisible in the mapped half alone, and that is not theoretical
+           // -- a correct mapper meeting a string it had never seen is how an
+           // empty Phantom came to be answered with balance advice seven times
+           // in one production session on 2026-09-06.
+           var raw = (e && e.message) || '';
+           var msg = (e && e.code === 4001) ? 'Signature rejected' : (raw || 'Connection failed');
            if (typeof parseSolanaError === 'function') msg = parseSolanaError(msg);
            this.error = msg; this.connecting = false; this.picking = '';
+           // ── OBSERVATION, AFTER THE USER HAS BEEN SERVED ──────────────────
+           //
+           // Deliberately the LAST statement in this block, and the three lines
+           // above are deliberately not in it: reporting may not delay, block or
+           // alter the line the user has just been handed.
+           //
+           // HOST-SUPPLIED, like every other global this partial reaches for
+           // (see CONTRACT WITH THE HOST'S JS in the header). The endpoint it
+           // posts to writes an ErrorLog, which is host-owned -- this gem ships
+           // no routes at all -- so a consumer that has not built one simply
+           // does not define this, the guard is false, and the card behaves
+           // exactly as it did before. Silence, never a 404.
+           //
+           // ALREADY REPORTED UPSTREAM? The connect helper substitutes its own
+           // sentence for an unusable wallet and reports the pair from in there,
+           // where the wallet's words still exist. Reporting again from out here
+           // would add a second row whose raw and mapped are BOTH our sentence
+           // -- the useless row, and the one an operator meets first.
+           //
+           // THE try/catch IS THIS GEM'S OWN LAYER, and it is not redundant with
+           // the reporter's. We do not own the reporter -- a host does, and a
+           // host's implementation may throw. A throw here escapes an async Alpine
+           // handler silently, which is the failure mode this whole feature
+           // exists to remove -- so the observation cannot be allowed to become
+           // the incident. Four values, and only these four: opts,
+           // verifyArgs() and this.props are all in scope and carry
+           // currentUserId, none of which belongs in an error log.
+           if (typeof window.reportWalletFailure === 'function' && !(e && e.walletFailureReported)) {
+             try { window.reportWalletFailure('wallet_connect', name, raw, msg); } catch (_e) {}
+           }
          }
        },
        deepLink() {

data/app/views/solana_studio/modals/_web3_step_up.html.erb

@@ -64,6 +64,19 @@
   you into that wallet's account, exactly as a standalone wallet button does. The
   walletHint is shown precisely so that is a visible choice, not a surprise.
 
+  Two more host globals, both OPTIONAL and both reached behind a `typeof` guard:
+  `parseSolanaError(msg)` maps a wallet string to a sentence a user can act on,
+  and `window.reportWalletFailure(stage, provider, raw, mapped)` records a caught
+  rejection with stage 'web3_step_up'. The reporter is fire-and-forget — its
+  return value is ignored and a throw is swallowed — and it is called ONCE per
+  rejection, skipping any error solanaConnectAndVerify already reported upstream.
+  Send BOTH message halves: `raw` is what the wallet said, `mapped` is what the
+  user read, and only the pair makes a MIS-mapping diagnosable. A host that
+  defines neither gets this card exactly as it behaved before, with the failure
+  recorded nowhere. The reporter and its endpoint stay host-owned because they
+  need an ErrorLog this gem cannot assume — reference implementation in
+  turf-monster: app/javascript/solana_errors.js, POST /auth/solana/report_failure.
+
   CRITICAL (Alpine): this partial is cloned from a <template x-if> by the modal
   host, so it must have ONE root element, and the x-data below is a
   DOUBLE-QUOTED attribute — a single " anywhere inside it (a code comment
@@ -167,9 +180,38 @@
            }
            this.error = (result && result.error) || 'Verification failed.';
          } catch (e) {
-           var msg = (e && e.code === 4001) ? 'Signature rejected' : ((e && e.message) || 'Connection failed');
+           // BOTH HALVES OR NEITHER. raw is what the WALLET said, captured
+           // before the mapper runs; msg is what the user reads. A mis-mapping
+           // is invisible in the mapped half alone -- a correct mapper meeting a
+           // string it had never seen is how an empty Phantom came to be
+           // answered with balance advice seven times in one production session
+           // on 2026-09-06, which is the incident this reporting exists for.
+           var raw = (e && e.message) || '';
+           var msg = (e && e.code === 4001) ? 'Signature rejected' : (raw || 'Connection failed');
            if (typeof parseSolanaError === 'function') msg = parseSolanaError(msg);
            this.error = msg;
+           // Observation, LAST and after the user has been served. Host-supplied
+           // like every other global here (see CONTRACT WITH THE HOST'S JS in
+           // the header): the endpoint it posts to writes an ErrorLog, which is
+           // host-owned -- this gem ships no routes -- so a consumer that built
+           // none simply leaves this undefined and the card behaves exactly as
+           // before. The walletFailureReported tag means solanaConnectAndVerify
+           // already reported this one from where the wallet's words still
+           // existed; reporting again would file a second row carrying OUR
+           // sentence in both halves, and that is the row an operator meets
+           // first. Sibling call site in modals/_wallet_connect carries the long
+           // form of both arguments.
+           //
+           // THE try/catch IS LOAD-BEARING HERE IN A WAY IT IS NOT THERE.
+           // this.connecting = false sits OUTSIDE this catch block, on the
+           // line below. A host reporter that throws would skip it, leaving the
+           // sign-in button disabled forever with an error the user cannot
+           // retry -- and Alpine swallows a throw out of an async handler, so
+           // nothing anywhere would say so. An observer that can wedge the card
+           // is a worse bug than the darkness it was added to fix.
+           if (typeof window.reportWalletFailure === 'function' && !(e && e.walletFailureReported)) {
+             try { window.reportWalletFailure('web3_step_up', name, raw, msg); } catch (_e) {}
+           }
          }
          this.connecting = false;
        },
@@ -281,7 +323,7 @@
       Installed badge, chevron — so a wallet reads identically everywhere it is
       offered and this card does not invent a third look for one action.
 
-      It carries `pulse-cta` (engine-motion) because it is the ONE target on the
+      It carries pulse-cta (engine-motion) because it is the ONE target on the
       card and the whole point of the card is that the user should press it. %>
   <template x-if="canOneClick">
     <div>

data/lib/solana_studio/version.rb

@@ -16,5 +16,5 @@ module SolanaStudio
   # through the normal cycle. Splitting the version out is the same shape
   # studio-engine already uses (lib/studio/version.rb) and hands each file back
   # to its real owner: this one to the release, the gemspec to the PR.
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solana-studio
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Alex McRitchie