chore: merge main into the token-forge migration branch

.claude/skills/create-issue/SKILL.md

@@ -35,6 +35,29 @@ The word limit above is a hard cap, not a guideline. A body that exceeds it is n
 - Over the hard cap means delete content, never compress it into one long sentence.
 - Steps and criteria are for a human to execute: numbered, imperative, one ultra brief line each, no assumed context.
 
+## Writing Style
+
+Avoid dense technical writing. Use clear, concise, and non-redundant prose. Examples: Simple English Wikipedia, Mr. Rogers, Ernest Hemingway.
+
+Banned vocabulary: do not invent abbreviations, compound labels, framework names, or domain terms.
+
+List of usual words to avoid:
+
+- load-bearing
+- blast radius
+- footgun
+- yak shaving
+- belt-and-suspenders
+- smoking gun
+- spine
+- seams
+- gate
+- substrate
+
+If writing documentation pay special attention to use words a maintainer would search for in the codebase.
+
+If something can be made a list, make it a list. It's easier to read. Prefer avoiding walls of text.
+
 ## Step 1: Classify
 
 | Signal | Type |

.claude/skills/create-pr/SKILL.md

@@ -38,6 +38,29 @@ The word limits above are hard caps, not guidelines. A body that exceeds one is
 - No preamble. `This PR adds...` → `Adds...`, then delete that too if the bullet below says it.
 - Over a hard cap means delete content, never compress it into one long sentence.
 
+## Writing Style
+
+Avoid dense technical writing. Use clear, concise, and non-redundant prose. Examples: Simple English Wikipedia, Mr. Rogers, Ernest Hemingway.
+
+Banned vocabulary: do not invent abbreviations, compound labels, framework names, or domain terms.
+
+List of usual words to avoid:
+
+- load-bearing
+- blast radius
+- footgun
+- yak shaving
+- belt-and-suspenders
+- smoking gun
+- spine
+- seams
+- gate
+- substrate
+
+If writing documentation pay special attention to use words a maintainer would search for in the codebase.
+
+If something can be made a list, make it a list. It's easier to read. Prefer avoiding walls of text.
+
 ## Step 0: Scope Check
 
 Run this first. A developer must never discover at the end of the wizard that the branch should have been split.

.github/workflows/pr.yml

@@ -61,6 +61,20 @@ jobs:
       - run: pnpm install --frozen-lockfile
       - run: pnpm test
 
+  test-node-26:
+    name: 3 - test (node 26)
+    runs-on: ubuntu-latest
+    if: github.event.action != 'edited'
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - run: corepack enable
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 26
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test
+
   commitlint:
     name: 4 - commitlint
     runs-on: ubuntu-latest

.lintstagedrc.mjs

@@ -3,10 +3,11 @@
 export default {
   'canton-connect/src/**/*.{ts,tsx,js,jsx}': () => 'pnpm -C canton-connect test',
   'canton-dappbooster/src/**/*.{ts,tsx,js,jsx}': () => 'pnpm -C canton-dappbooster test',
+  'dapp/frontend/src/**/*.{ts,tsx,js,jsx}': () => 'pnpm -C dapp/frontend test',
   // One task for the whole doc gate, under the name CI uses: typedoc resolves both packages in a
   // single run anyway, so splitting it per package bought a second and two ways to drift.
   // Snippets live in the READMEs as well as in the doc blocks, so a doc edit re-runs the compile.
-  '{canton-connect,canton-dappbooster}/{src/**/*.{ts,tsx},doc-fixtures.d.ts,README.md,architecture.md,typedoc.json}':
+  '{canton-connect,canton-dappbooster}/{src/**/*.{ts,tsx},doc-fixtures.d.ts,README.md,architecture.md,coming-from-wagmi.md,typedoc.json}':
     () => 'pnpm docs:check',
   // Either side of the L2/L3 contract moving on its own is what this catches.
   '{canton-dappbooster/src/{components,providers}/**/anatomy.ts,canton-theme/src/**/*.css}': () =>

CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- starter-kit: v2026.08 -->
+<!-- starter-kit: v2026.09 -->
 
 # Agent Configuration — Canton dAppBooster
 
@@ -30,7 +30,7 @@ Use one reader per doc type, layered by scope:
 | `AGENTS.md` | Agent compatibility loader | Three-line shim beside every `CLAUDE.md`, pointing to the sibling `CLAUDE.md`. It is never canonical. |
 | `architecture.md` | Human or agent: what are the structural seams and internal subsystems? | Root always for cross-component seams. Subproject only when internals outgrow the README: three or more interacting subsystems, non-trivial control flow, or named abstractions. |
 | `architecture/<topic>.md` | Human or agent editing one subsystem: how does it behave in full? | Only beside an `architecture.md` that indexes it, when a section outgrows the seam it describes. The index keeps the seam and links the chapter; no chapter without its index entry. |
-| Generated reference | Human: what does this export do and how do I call it? | Not hand-maintained and not a file anyone edits. `typedoc.json` builds it from the JSDoc on `canton-dappbooster` and `canton-connect`'s barrels; `@internal` keeps a symbol off it. Fix the doc block, never the site. |
+| Generated reference | Human: what does this export do and how do I call it? | Not hand-maintained and not a file anyone edits. `typedoc.json` builds it from the JSDoc on `canton-dappbooster` and `canton-connect`'s barrels; `@internal` keeps a symbol off it. Fix the doc block, never the site. `canton-connect/coming-from-wagmi.md`, published through `projectDocuments`, is the one hand-written page in it: an exception for a mapping to another library's API, not a pattern to repeat. |
 
 Current distribution:
 
@@ -83,7 +83,7 @@ A README may state that a contract exists and link to it. It may not restate it.
 
 | Path | Purpose | Stack | Port |
 |------|---------|-------|------|
-| [`dapp/frontend/`](dapp/frontend/) | `DBT` vesting dApp over the local participant. Every read and write goes through the connected CIP-0103 wallet via `canton-connect`; the operator's factory and the instrument's `InstrumentConfig` arrive by explicit disclosure, the config from the token registry. Imported from `cn-dappbooster@feat/vesting-lite` (see its `PROVENANCE.md`). | Vite + React + Tailwind v4 + zustand + react-router + Biome | 3012 |
+| [`dapp/frontend/`](dapp/frontend/) | `DBT` vesting dApp over the local participant. Every read and write goes through the connected CIP-0103 wallet via `canton-connect`; the operator's factory and the instrument's `InstrumentConfig` arrive by explicit disclosure, the config from the token registry. Imported from `cn-dappbooster@feat/vesting-lite` (see its `PROVENANCE.md`). | Vite + React + Ark UI + lucide-react + Tailwind v4 + zustand + react-router + Biome | 3012 |
 | [`canton-connect/`](canton-connect/) | wagmi-style React hooks wrapping the `dapp-sdk` facade; the SDK owns discovery, the picker, the session and the transports | TypeScript + React 19 + xstate 5 + Biome | n/a (library) |
 | [`canton-dappbooster/`](canton-dappbooster/) | L2 headless UI components for Canton dApps (tsdown-built, zero styling), plus the light/dark/system theme runtime that drives `data-theme`, plus the pure utilities the components are built on, the exact-decimal amount ones included. Styling lives in `canton-theme`. `src/index.ts` is the public API; `src/connect.ts` is the `/connect` sub-path, holding the components that read the wallet session so the main barrel stays free of the Canton SDK. | TypeScript + React 19 + tsdown + vitest + Biome | n/a (library) |
 | [`canton-theme/`](canton-theme/) | L3 plain-CSS theme for the kit: `--cnc-*` tokens + prestyled defaults, consumed by importing its CSS. | CSS | n/a (library) |
@@ -330,6 +330,9 @@ package, because only `canton-dappbooster` splits markup from styles across a pa
   `onClick ?? doTheThing` silently drops the behaviour the component exists for. Where a state
   machine owns the handler, merge through its own utility (`mergeProps` in Zag) rather than by
   hand, so a handler the library adds later is not missed.
+- **A ternary is for a two-way toggle between two things to render; a guard clause is for bailing
+  out of the whole render** (loading, error, no data). Two real faces get
+  `cond ? <A /> : <B />`; a bail-out gets an `if` above the return.
 - Tests assert on roles, accessible names, and whatever contract the component declares. Never on
   styling.
 

architecture.md

@@ -8,7 +8,7 @@
 | `scripts/` | Bash + Node | The local loop: `dev-stack.sh`, the DAR upload, the token mint, the vesting bootstrap |
 | wallet-service (external: [BootNodeDev/canton-wallet-service](https://github.com/BootNodeDev/canton-wallet-service)) | Node 24 + Express 5 + TypeScript + `@canton-network/wallet-sdk` | Bridge the wallet uses for external-party onboarding and participant JSON API calls. A git dependency pinned to a tag, run on the host by `scripts/dev-stack.sh` |
 | token registry (external: [BootNodeDev/canton-token-forge](https://github.com/BootNodeDev/canton-token-forge)) | Node + Express + TypeScript | Read-only CIP-56 registry over the `canton-token-forge` package: serves instrument metadata and the transfer-factory choice context. A git dependency pinned to a tag, run on the host by `scripts/dev-stack.sh` |
-| `dapp/frontend/` | Vite + React + Tailwind v4 + zustand + react-router | `DBT` **vesting** dApp; every read and write goes through the connected CIP-0103 wallet via `canton-connect`, and the `InstrumentConfig` every write carries comes from the token registry |
+| `dapp/frontend/` | Vite + React + Ark UI + lucide-react + Tailwind v4 + zustand + react-router | `DBT` **vesting** dApp; every read and write goes through the connected CIP-0103 wallet via `canton-connect`, and the `InstrumentConfig` every write carries comes from the token registry |
 | `canton-connect/` | TypeScript + React 19 | wagmi-style hooks wrapping the dapp-sdk facade |
 | `canton-dappbooster/` | TypeScript + React 19 + tsdown | L2 headless UI components, zero styling, plus the theme runtime and the pure utilities under the components, exact-decimal amounts included |
 | `canton-theme/` | CSS | L3 plain-CSS theme: `--cnc-*` tokens + prestyled defaults |

canton-connect/CLAUDE.md

@@ -19,19 +19,20 @@ the session and the transports. Browser-only, and built to stay cheap to delete.
   lifecycle; remount the provider (`key`) to change it.
 - **A state carries a tag for what it means to the outside.** The tags union in
   `machine/connectionMachine.ts` is the authority, and no other module names a state. A state that
-  answers an operation must carry its tag or the bridge waits forever: `waitFor` is unbounded here
-  (#105).
+  answers an operation must carry its tag or the bridge waits forever: `waitFor` is unbounded here,
+  and no clock will rescue it.
 - **A state's `exit` clears what that state alone justified.** `party` is cleared on leaving
   `session.authenticated`, because a wallet that stops serving requests has none to offer, and a
   lock cannot be told from a wallet-side disconnect. `sdk` has no exit; nothing outlives it.
 - **Listeners register only inside a state's `invoke`.** `sdk.onX` binds to the current client and
   `sdk.connect()` swaps it.
-- **The provider selects nothing.** It publishes the config, the actor and three actions; each hook
+- **The provider selects nothing.** It publishes the config, the actor and four actions; each hook
   selects its own slice. Never add a field a hook could select.
 - **Publish the narrowest type.** `ConnectionSubscription` puts `send` out of reach; `WalletSdk`
   narrows `DappSDK` to the methods this package calls.
-- **React owns two things:** `lastTx` (`useExecute`) and the `toConnectError` memo (`useConnect`).
-  Anything else that looks like state belongs in the machine.
+- **The machine owns the session; a hook owns what it asked for.** `sdk`, `party`, status and the
+  last connect error are machine context, never React state. A call's result or in-flight flag
+  (`lastTx`, a signature) is React state: the session does not depend on it.
 - **Import the SDK's types.** A `param as Parameters<…>` cast is a duplicated type: import the real
   one from `dapp-sdk` or `core-types`.
 - **The picker is `CantonConnectConfig.walletPicker`.** No picker UI in this package; that lives in
@@ -46,10 +47,14 @@ the session and the transports. Browser-only, and built to stay cheap to delete.
 
 ## Bumping `dapp-sdk`
 
-`guardedConnect` rests on two SDK internals no test can pin: that the picker window comes from
-`window.open`, and the shape of the `SPLICE_WALLET_PICKER_RESULT` message it reads and posts. Why:
-[`architecture/popup-close-guard.md`](architecture/popup-close-guard.md). Serve `dapp/frontend` and
-walk all four:
+`guardedConnect` and `retireSdk` rest on three SDK internals no test can pin:
+
+- the picker popup is opened through `window.open`
+- the shape of the `SPLICE_WALLET_PICKER_RESULT` message
+- `connect()` calls `this.walletPicker` only when it reaches the picker, so a swapped one is honored
+
+Why: [`architecture/popup-close-guard.md`](architecture/popup-close-guard.md). Serve `dapp/frontend`
+and walk all five:
 
 1. Close the picker without choosing, three times over: the button re-enables each time, and the
    next real connect raises exactly one approval prompt.
@@ -60,6 +65,9 @@ walk all four:
 4. Check that `new DappSDK()` still only initializes fields (true on 1.5.1). The machine constructs
    one inside a plain `assign`; if construction turns effectful, move the ritual into the provider's
    `createSdk` and dispose the abandoned instance on the same transition, never from an effect.
+5. Click Connect, then the Cancel that replaces it, fast enough to beat the popup: the button reads
+   Connect again and no picker window appears. One appearing means `connect()` no longer reads
+   `walletPicker` off the instance at pick time.
 
 ## Layout
 

canton-connect/README.md

@@ -12,13 +12,14 @@ types.
 
 [`@partylayer/react`](https://partylayer.xyz) is the alternative, built over its own wallet
 adapters. This one wraps Digital Asset's official SDK, the dependency these dApps already carry, and
-stays thin enough to delete. How close the result shapes should sit to wagmi's is open in #52.
+stays thin enough to delete. How the hook results relate to wagmi's is in
+[coming-from-wagmi.md](https://github.com/BootNodeDev/canton-dappbooster/blob/main/canton-connect/coming-from-wagmi.md).
 
 ## Why a state machine
 
 The connection lifecycle looks like four states (idle, connecting, connected,
 disconnected) and isn't. The hard part isn't holding state, it's canceling work
-when the state that started it is gone: a picker the user walked out of, a lock
+when the state that started it is gone: a picker the user abandoned, a lock
 that races the account read, a connect asked for mid-disconnect, a wallet that
 answers late or never. Handled one at a time these were five separate races
 (#76). A state machine folds them into one model: a state's invoked work is
@@ -36,7 +37,7 @@ switching only once those gaps close. Until then, the machine earns its cost.
 
 | dapp-sdk gap | what it costs us | gone when |
 |---|---|---|
-| `connect()` can't be aborted; a closed popup hangs it (#49) | `guardedConnect`, `settleAbandonedConnect`, `PickerClosedError`, the `retiring` state | `connect(signal)` truly aborts |
+| `connect()` can't be aborted; a closed popup hangs it (#49) | `guardedConnect`, `settleAbandonedConnect`, `PickerClosedError`, the `retiring` state, `retireSdk`'s picker swap | `connect(signal)` truly aborts |
 | `init()` caches a rejected promise forever | `retireSdk`, the `retiring` state, `InitFailedError` | `init()` retries after a failure |
 | `disconnect()` has no timeout (#105) | `DISCONNECT_TIMEOUT_MS`, and `retireSdk` when it fires | `disconnect()` times out itself |
 | lock and wallet-side disconnect are one push | `session.unauthenticated`, party-dropped-on-lock | CIP-0103 separates them (spec, not SDK) |
@@ -75,7 +76,7 @@ function App() {
 }
 
 function Dapp() {
-  const { connect, isConnecting, isConnected, connectError } = useConnect()
+  const { connect, isPending, isConnected, error } = useConnect()
   const { party } = useParty()
   const { isLocked } = useWalletStatus()
   const { signMessage } = useSignMessage()
@@ -85,10 +86,10 @@ function Dapp() {
   if (!isConnected) {
     return (
       <div>
-        <button onClick={() => connect().catch(() => undefined)} disabled={isConnecting}>
+        <button onClick={() => connect().catch(() => undefined)} disabled={isPending}>
           Connect
         </button>
-        {connectError !== undefined && <p>{connectError.message}</p>}
+        {error !== undefined && <p>{error.message}</p>}
       </div>
     )
   }
@@ -103,20 +104,23 @@ function Dapp() {
 
 `connect()` opens the SDK's wallet picker, a popup by default. There is no mode argument: the picker
 is what chooses the wallet. Dismissing it rejects with `ConnectCancelledError`, which you filter by
-`instanceof`, never by message. Whether `connectError` records it as well depends on which side saw
+`instanceof`, never by message. Whether `error` records it as well depends on which side saw
 the close, so do not gate on that.
 
 `signMessage`, `execute` and `ledgerApi` refuse with no session, and refuse again while the wallet
-reports it is not authenticated; that is `isLocked`, and it happens after a successful connect. The
-SDK's status carries one `isConnected` flag, so a lock and a wallet-side disconnect look the same
+reports it is not authenticated; that is `isLocked`, and it happens after a successful connect.
+`signMessage` and `execute` also refuse with no party, which `ledgerApi` does not need. The
+reference gateway also refuses `signMessage` for a local party; `usePartyType().readPartyType()`
+tells local from external when you ask. The SDK's status carries one `isConnected` flag, so a lock
+and a wallet-side disconnect look the same
 here. `useLedger().isReady` covers both, and `useParty().party` is `undefined` for the duration:
 gate session content on the party, and use `isLocked` only to explain why it went away.
 
 ## Reference
 
 Every hook and every config field is documented in JSDoc, which your editor surfaces at the call
 site and which is published at
-[docs-canton-dappbooster.vercel.app](https://docs-canton-dappbooster.vercel.app). Start at
+[docs.dappbooster.cc](https://docs.dappbooster.cc/). Start at
 `CantonConnectProvider` and `CantonConnectConfig`.
 
 ## Testing helpers