Wallet Adapter and SDK feedback

### Documentation & Links

* **Broken links**:

* [Accounts example docs](https://0xmiden.github.io/miden-docs/imported/miden-client/src/web-client/examples/accounts.html#relevant-documentation)
* **"API Reference"** link in the [NPM package page](https://www.npmjs.com/package/@demox-labs/miden-sdk) (under *Usage* section)

* **Wallet adapter README mismatch**: Suggests using

```ts
await wallet.adapter.requestSend(transaction);
```

but TypeScript reports that `requestSend` is not available. It works when using `(await (wallet?.adapter as MidenWalletAdapter).requestSend` but it would be great if that was not necessary, because it's not obvious.

---

### Error Handling & Messages

* Passing an invalid value to `AccountId.fromHex` produces an unhelpful error:

```
RuntimeError: unreachable
```

This might be fixable when using https://github.com/rustwasm/console_error_panic_hook (though not sure it's maintained or already used here somehow).

* Invalid MASM compilation only shows generic messages like `"syntax error"` or `"linking error"`. More detailed reports would be helpful. See this issue, as it's very likely related to using `to_string` on errors but that doesn't work for `Report`s returned by assembler APIs: https://github.com/0xMiden/miden-client/pull/1331#discussion_r2379903177.

* Attempting to build an invalid transaction with `TransactionRequestBuilder::build` results in `"unreachable"` error due to an unwrap in `build()`. It should return a proper error. Example code that triggers this:

```ts
let transactionRequest = new TransactionRequestBuilder()
.withCustomScript(txScript)
.withOwnOutputNotes(
new OutputNotesArray([OutputNote.full(note)])
)
.build();
```

* I can't really say how to reproduce this, but I frequently got this error when trying to connect a wallet via the wallet adapter:

```
WalletConnectionError: Failed to execute 'atob' on 'Window': The string to be decoded is not correctly encoded.
at MidenWalletAdapter.connect (adapter.js:184:23)
at async eval (WalletProvider.js:179:13)
```

Restarting the browser and/or localStorage.clear() seemed to help.

---

### Transaction Handling

* **TypeScript type mismatches**:

* `SendTransaction` cannot be used with `requestTransaction`:

```
Argument of type 'SendTransaction' is not assignable to parameter of type 'MidenTransaction'.
```

This suggests transaction types are not fully compatible, which is confusing. In general, there are many transaction types and it would be nice to cut down on the number of them to make this a bit clearer.

* Using

```ts
const txId = (await (wallet?.adapter as MidenWalletAdapter).requestSend(midenTransaction));
```

returns `{}` but the TypeScript signatures says it returns `string`.

* **Transaction IDs**:

* `requestTransaction` returns a tx ID in a non-standard format:

```
ace74ef9-a71b-41ed-b364-d43044940211
```

instead of standard hex.

* **Transaction flow**:

* The transaction approval window opens in the background, making it unclear that something is happening.
* Sometimes the transaction generation tab does not open immediately.
* `requestTransaction` resolves before the transaction is actually submitted and confirmed (from what I can tell), meaning it returns, the UI is updated to say "tx successful!" but the tx hasn't actually made it through yet.

* Developers may need to manually poll the client until confirmation.
* Suggestion: either delay the return until confirmation or document best practices.

* The structure of the wallet adapter is not entirely clear to me. There are top-level functions like `requestTransaction` but also `wallet.adapter.requestSend` and I don't understand why. Just an opinion, but I think it would be clearer if everything was behind `wallet`, e.g. `const wallet = useWallet()` and then `wallet.rawAccountId`, `wallet.requestTransaction`, etc.

---

### Typescript Types

Some APIs are stringly-typed while others use the proper typescript types.

- `AccountId.toBech32` uses `AccountInterface.Unspecified`
- `Address.fromAccountId` uses `"Unspecified"`
- `new CustomTransaction` takes account IDs as strings rather than `AccountId`.
- `rawAccountId` is a string making conversions to `AccountId` necessary for APIs that do need the actual type

These are just some examples and this feels a bit inconsistent and is less nice to use due to the necessary conversions.

---

### Wallet Behavior

* Consuming notes always triggers:

```
Connectivity Issue Detected
Wallet may be offline or out of sync.
```

The only workaround is restarting the browser (I assume this resyncs the wallet).

cc @dagarcia7

The issue lists multiple problems across the wallet adapter, SDK, and error handling. Start by examining the wallet adapter's TypeScript definitions and the README mismatch. Look at the `AccountId.fromHex` method in the Rust/WASM code for the panic error. Check the transaction builder's `build()` method for the unwrap. This requires understanding the codebase structure, TypeScript/ Rust interaction, and the wallet connection flow to even begin diagnosing the reported issues.

Scritto dal modello di indicizzazione a partire dal testo della issue.