feat(tutorial): add interactive in-browser runners to most read-only tutorials by thephez · Pull Request #161 · dashpay/docs-platform

thephez · 2026-08-19T18:51:32Z

Overview

Adds interactive "try it" widgets to the JavaScript (Evo SDK) tutorials so readers can run the documented queries against testnet directly from the docs page. Each widget executes one of a fixed allow-list of read-only operations, and the code shown on the page is derived from the same function the Run button invokes, so the displayed example can never drift from what actually runs. The Evo SDK is now bundled locally at build time instead of being imported from esm.sh at runtime.

Highlights

Interactive runners on seven tutorial pages: network status, identity, data contract, contract history, documents query, name resolve/search/lookup, and token info
All operations are read-only testnet queries from a predefined allow-list; the DOM contains no executable code
Evo SDK 4.1.1 is bundled with esbuild into a gitignored static asset (_static/vendor/evo-sdk.js), pinned via package-lock.json; Read the Docs builds it in a pre_build job and make html rebuilds it locally
Hardened runner UX: number input validation with bounds, a run-generation guard so resets cancel stale results, BigInt-safe formatting for balances/supplies, and SDK import retry after a failed load
New make sdk-install/sdk targets, devcontainer Node 22 support, widget CSS styling, and docs on serving _build/html over HTTP (browsers block the SDK module import from file:// pages)
Lite app esm.sh pins bumped to match the SDK version (4.1.0 -> 4.1.1)

Summary by CodeRabbit

New Features
- Added interactive testnet tutorials for connections, contracts, documents, identities, names, and tokens.
- Tutorials now support live queries, input validation, connection status, results, reset controls, and browser-code previews.
- Added responsive styling for tutorial controls, results, errors, and status displays.
Documentation
- Documentation builds now include the browser SDK automatically.
- Updated examples to use Evo SDK 4.1.1.
Maintenance
- Standardized the documentation build environment on Node.js 22.

Preview build: https://dash-docs-platform--161.org.readthedocs.build/en/161/

Add a reusable interactive-tutorial block (JS runner + CSS) that lazily loads the Evo SDK from esm.sh and executes the visible snippet against testnet. Wire it up in conf.py as a classic deferred script and embed a read-only identity fetch example in the retrieve-an-identity tutorial.

…rials Rework the runner to support multiple named inputs (data-param) and per-operation result renderers (identity, contract, name, documents, status), materializing form values as declarations in the displayed snippet so the visible code is exactly what executes. Add Try it blocks to the connect, retrieve-a-data-contract, retrieve-documents, and retrieve-a-name tutorials, and migrate the retrieve-an-identity block to the new attributes.

…ion allow-list Replace AsyncFunction evaluation of DOM-embedded snippet text with an explicit map of read-only operation functions selected via data-operation. The displayed source is derived from the same function that runs, so the markup is no longer executable and the shown code cannot drift from the executed code. Also stack the action buttons on narrow viewports.

…ples Drop the standalone Try It sections and attach each runner directly below the tutorial's code block with a compact toolbar, a text-style reset button, and a View browser code toggle. Expand the status renderer to show network, block height, sync state, peers, and component versions, and improve narrow-viewport layout for inputs, metrics, and the toolbar.

…and token info Add allow-listed operations for contract history, identity name lookup, DPNS prefix search, and token info, with matching renderers and runner blocks in the contract history, name retrieval, and token info tutorials. Support per-operation constants (DPNS contract ID) in the displayed source and rename the normalized Map key field to mapKey so the history renderer can read revision timestamps.

Interactive tutorial runners now import a self-hosted esbuild bundle (_static/vendor/evo-sdk.js) built from the npm-pinned @dashevo/evo-sdk 4.1.1 rather than fetching esm.sh at runtime. Read the Docs generates the bundle in a pre_build job; locally, make html rebuilds it via the new sdk target after a one-time make sdk-install. Also bump the lite demo apps' esm.sh pin to 4.1.1 to match the bundled version, exclude node_modules from the Sphinx build, and document the setup in CLAUDE.md.

…ycle - Validate number inputs against their min/max bounds before running and cap token position at 65535 - Guard runs with a generation counter so a reset cancels stale results instead of racing the UI - Format large integers via BigInt to avoid precision loss and cache the SDK import with retry after a failed load - Add Node 22 to the devcontainer and run make sdk-install during post-create so the SDK bundle builds - Document serving _build/html over HTTP since browsers block the SDK module import from file:// pages Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

coderabbitai · 2026-08-19T18:52:22Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0c603e94-f63b-45e8-a5a5-1ecd5508dac0

📥 Commits

Reviewing files that changed from the base of the PR and between b84ac43 and c1a8ef5.

⛔ Files ignored due to path filters (1)

package-lock.json is excluded by !**/package-lock.json

📒 Files selected for processing (21)

.devcontainer/devcontainer.json
.devcontainer/postCreateCommands.sh
.gitignore
.readthedocs.yml
CLAUDE.md
Makefile
_static/css/pydata-overrides.css
_static/dashmint-lite.html
_static/dashnote-lite.html
_static/dashproof-lite.html
_static/js/interactive-tutorial.js
conf.py
docs/tutorials/connecting-to-testnet.md
docs/tutorials/contracts-and-documents/retrieve-a-data-contract.md
docs/tutorials/contracts-and-documents/retrieve-data-contract-history.md
docs/tutorials/contracts-and-documents/retrieve-documents.md
docs/tutorials/identities-and-names/retrieve-a-name.md
docs/tutorials/identities-and-names/retrieve-an-identity.md
docs/tutorials/tokens/retrieve-token-info.md
package.json
scripts/evo-sdk-entry.js

Included review availability: Your plan provides up to 3 included reviews per hour; 2 remain after this review.

📝 Walkthrough

Walkthrough

The documentation adds a bundled Evo SDK, interactive testnet tutorial widgets, browser-side query execution, result rendering, responsive styling, and SDK build integration for local and Read the Docs builds.

Changes

Interactive Evo SDK tutorials

Layer / File(s)	Summary
SDK build pipeline `.devcontainer/`, `.readthedocs.yml`, `Makefile`, `package.json`, `scripts/`, `conf.py`, `.gitignore`, `CLAUDE.md`	The project installs JavaScript dependencies, bundles the Evo SDK, and builds the bundle before Sphinx generates HTML. Dev container and Read the Docs configurations use Node.js 22.
Interactive tutorial runtime `_static/js/interactive-tutorial.js`, `_static/css/pydata-overrides.css`	The browser runtime validates inputs, loads the bundled SDK, executes read-only testnet queries, handles stale runs and errors, and renders results. CSS styles the widgets and mobile layouts.
Tutorial widgets and SDK imports `docs/tutorials/*/.md`, `_static/dashmint-lite.html`, `_static/dashnote-lite.html`, `_static/dashproof-lite.html`	Tutorial pages add controls, source views, connection states, and result areas for network, contract, document, identity, name, and token queries. Static examples update to Evo SDK 4.1.1.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to c1a8e

This change adds read-only interactive tutorial runners and local SDK bundling; no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant TutorialWidget
  participant InteractiveTutorial
  participant BundledEvoSDK
  participant Testnet
  TutorialWidget->>InteractiveTutorial: submit operation and inputs
  InteractiveTutorial->>BundledEvoSDK: load SDK and execute read-only query
  BundledEvoSDK->>Testnet: request testnet data
  Testnet-->>BundledEvoSDK: return query response
  BundledEvoSDK-->>InteractiveTutorial: return SDK result
  InteractiveTutorial-->>TutorialWidget: render status and results

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 10.53% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: adding interactive in-browser runners to read-only tutorials.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

_{Comment @coderabbitai help to get the list of available commands.}

thephez and others added 7 commits August 17, 2026 14:10

Navigation Menu

Uh oh!

feat(tutorial): add interactive in-browser runners to most read-only tutorials - #161

feat(tutorial): add interactive in-browser runners to most read-only tutorials#161
thephez wants to merge 7 commits into
dashpay:4.1.0from
thephez:interactivity

thephez commented Aug 19, 2026 •

edited by github-actions Bot

Loading

Uh oh!

coderabbitai Bot commented Aug 19, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

thephez commented Aug 19, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Highlights

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Aug 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

thephez commented Aug 19, 2026 •

edited by github-actions Bot

Loading

coderabbitai Bot commented Aug 19, 2026 •

edited

Loading