feat: playwright recorder for example-app walkthroughs

package.json

@@ -10,7 +10,12 @@
     "test:read-only": "node --test --test-timeout=120000 test/read-only.test.mjs",
     "test:read-write": "node --test --test-timeout=300000 --test-concurrency=1 test/read-write.test.mjs",
     "test:all": "node --test --test-timeout=300000 --test-concurrency=1 test/read-only.test.mjs test/read-write.test.mjs",
-    "test:setup": "mocha --slow 500 test/setupDashClient.test.mjs --exit"
+    "test:setup": "mocha --slow 500 test/setupDashClient.test.mjs --exit",
+    "walkthrough:dashmint-lab": "node scripts/walkthroughs/record.mjs dashmint-lab",
+    "walkthrough:dashnote": "node scripts/walkthroughs/record.mjs dashnote",
+    "walkthrough:dashnote-starter": "node scripts/walkthroughs/record.mjs dashnote-starter",
+    "walkthrough:dashrate": "node scripts/walkthroughs/record.mjs dashrate",
+    "walkthrough:token-ops": "node scripts/walkthroughs/record.mjs token-ops"
   },
   "repository": {
     "type": "git",

scripts/walkthroughs/README.md

@@ -0,0 +1,102 @@
+# Walkthrough Recorder
+
+Reusable Playwright scripts for generating narrated-by-caption walkthrough
+videos of the example apps.
+
+Start the target app first, then run one of:
+
+```sh
+npm run walkthrough:dashmint-lab
+npm run walkthrough:dashnote
+npm run walkthrough:dashnote-starter
+npm run walkthrough:dashrate
+```
+
+The recorder assumes the app is available at `http://127.0.0.1:5173/`. Override
+that when needed:
+
+```sh
+npm run walkthrough:dashmint-lab -- --url http://127.0.0.1:5174/
+```
+
+## Authenticated Walkthroughs
+
+If `.env.walkthrough` exists at the repo root, it is loaded automatically. Put a
+testnet mnemonic there to let walkthroughs sign in:
+
+```sh
+PLATFORM_TUTORIALS_IDENTITY_MNEMONIC="word1 word2 ..."
+PLATFORM_TUTORIALS_IDENTITY_INDEX=0
+```
+
+The recorder also accepts `WALKTHROUGH_MNEMONIC`, `PLATFORM_MNEMONIC`, or
+`MNEMONIC`.
+
+The default authenticated walkthroughs show the signed-in UI. DashMint Lab
+performs one card mint so the token-paid create flow is visible; the recorder
+still avoids token transfers, purchases, burns, and contract registration. Other
+walkthroughs stop before writes such as creating notes. To force a
+browse-only/no-login recording:
+
+```sh
+npm run walkthrough:dashmint-lab -- --no-login
+```
+
+Outputs are written to a per-app directory under `walkthrough/`:
+
+```text
+walkthrough/<app>/<app>-walkthrough.webm
+walkthrough/<app>/<app>-preview.png
+```
+
+## Caption Copy
+
+Overlay text lives in plain JSON files so copy can be edited without touching
+the recorder code:
+
+```text
+scripts/walkthroughs/captions/dashnote.json
+scripts/walkthroughs/captions/dashnote-starter.json
+scripts/walkthroughs/captions/dashmint-lab.json
+scripts/walkthroughs/captions/dashrate.json
+```
+
+Each entry is a stable step name with the text shown in the video:
+
+```json
+{
+  "rememberedReload": "After logout, Dashnote reloads with remembered read-only access and cached notes."
+}
+```
+
+Only edit the string values. The recorder keeps timing, clicks, waits, and
+testnet write behavior in code. The JSON file is the sole source of caption copy
+— the recorder errors out if the file is missing or a referenced key is absent
+or blank.
+
+## Browser Setup
+
+The script looks for Playwright in the app's dependencies and the repo root. If
+Playwright lives somewhere else, set `PLAYWRIGHT_REQUIRE_PATH` to that
+`node_modules/playwright` location.
+
+If the normal Playwright browser cache is not available, point at a Chromium
+executable directly:
+
+```sh
+PLAYWRIGHT_CHROMIUM_EXECUTABLE="/path/to/chromium" \
+  npm run walkthrough:dashmint-lab
+```
+
+In PowerShell, set environment variables before running npm:
+
+```powershell
+$env:PLAYWRIGHT_CHROMIUM_EXECUTABLE = "C:\path\to\chromium.exe"
+npm run walkthrough:dashmint-lab
+```
+
+For local debugging, add `--headed` after the npm argument separator:
+
+```sh
+npm run walkthrough:dashmint-lab -- --headed
+```

scripts/walkthroughs/captions/dashmint-lab.json

@@ -0,0 +1,22 @@
+{
+  "intro": "DashMint Lab opens directly into browse-only mode on Dash Platform testnet.",
+  "collectionLive": "The Collection tab is live without signing in: cards are queried from the shared contract.",
+  "cardDetails": "Each card shows rarity, price, stats, owner, and marketplace actions when a price exists.",
+  "marketplace": "Switch to Marketplace to see cards that are listed for purchase.",
+  "marketplaceBuy": "Listed cards expose a Buy action that opens a purchase confirmation when signed in.",
+  "sorting": "Sorting is available on all Collection views; here it cycles the card grid ordering.",
+  "signInUnlocks": "Signing in unlocks account-specific actions alongside the public marketplace data.",
+  "afterLogin": "After login, the Yours tab and account balance become available alongside browse-only data.",
+  "ownedCardMenu": "Cards you own expose owner-only actions through the ⋯ menu: Transfer, Copy ID, View on Explorer, and Burn.",
+  "mintUnlocked": "The Mint tab uses DashMint tokens: each new card burns 1 token.",
+  "mintReadOnly": "The Mint tab exposes the full form, but write operations are gated until login.",
+  "mintPrepare": "This card will be created as a Platform document paid for with one DashMint token.",
+  "mintSubmitting": "Minting submits the card with tokenPaymentInfo, authorizing the one-token burn.",
+  "mintComplete": "The mint is complete; the supply count and token balance update from Platform.",
+  "tokensIntro": "The Tokens tab shows the signed-in identity's remaining DashMint balance for this contract.",
+  "tokensTransfer": "DashMint tokens can also be sent to another identity or DPNS name from this form.",
+  "loginPath": "Opening Login shows the account access path without requiring a sign-in.",
+  "fundedIdentity": "A funded testnet identity unlocks mint, transfer, pricing, purchase, and burn functionality.",
+  "howItWorks": "The How it works tab explains the SDK pieces behind the marketplace.",
+  "outro": "DashMint Lab is an example application highlighting just some of Dash Platform's many features."
+}

scripts/walkthroughs/captions/dashnote-starter.json

@@ -0,0 +1,15 @@
+{
+  "intro": "Dashnote Starter: a minimal React app for notes on Dash Platform testnet.",
+  "identityAccess": "Start here: the app explains what it stores and asks for identity access only when you are ready.",
+  "signInForm": "The sign-in form keeps access local and links to the testnet identity setup path.",
+  "signedInWriteAccess": "Signing in unlocks the write actions that are otherwise unavailable in the starter preview.",
+  "authenticatedWorkspace": "Authenticated view shows the resolved identity, active contract, note editor, and note list.",
+  "noWritesDefault": "The default walkthrough does not create, update, or delete notes; it stops before any testnet write.",
+  "writeAccessCrud": "With write access, this same flow can exercise a full CRUD demo when needed.",
+  "readOnlyTour": "Without sign-in, the walkthrough stops before write actions and tours the read-only starter screen.",
+  "sampleNotes": "Sample notes preview the authenticated workspace without loading the SDK or touching the network first.",
+  "exampleConcepts": "The examples call out the core concepts: identity-owned data, shared contracts, and revisions.",
+  "aboutSection": "The About section summarizes how the starter maps React UI to a hardcoded Dash Platform contract.",
+  "fullAppFlow": "With write access, the full app flow is create, list, edit, refresh, and delete notes.",
+  "outro": "That is Dashnote Starter: deliberately small, readable, and focused on the SDK calls."
+}

scripts/walkthroughs/captions/dashnote.json

@@ -0,0 +1,28 @@
+{
+  "intro": "Dashnote is a full notes app: a two-pane notebook backed by Dash Platform documents.",
+  "signInFullAccess": "Signing in enables full access for your identity.",
+  "identityFullAccess": "After login, the identity card switches to full access and the note list loads for your identity.",
+  "identityMenu": "The identity card menu exposes Settings, Switch identity, and Log out options.",
+  "rememberedReload": "After logout, reloading uses the remembered identity to show cached notes without signing in.",
+  "rememberedSearch": "Search works in remembered read-only mode.",
+  "signBackInCrud": "Signing back in restores write access.",
+  "readOnlyMode": "Without sign-in, the recording stays in read-only mode.",
+  "leftPane": "The left pane has search, note counts, cached results, and background refresh state.",
+  "editorPane": "The editor pane shows title, body, revision metadata, timestamps, and a byte-budget progress bar.",
+  "createNote": "Now we click Create Note to make a real note document on testnet.",
+  "saveCreate": "Saving calls sdk.documents.create and the note appears with Platform metadata.",
+  "createdMetadata": "The editor now shows the created note, including a revision chip and created/updated timestamps.",
+  "updateNote": "Next we update the note and save, which bumps the document revision.",
+  "updatedMetadata": "After updating, the revision metadata reflects the newer on-chain document state.",
+  "deleteNote": "Finally, we click the delete button and confirm on the delete modal before calling sdk.documents.delete.",
+  "deletedNote": "Our added note is removed, leaving the app clean after the demo.",
+  "readOnlyEditPrompt": "In read-only mode, Dashnote can display remembered notes, but edit actions prompt for sign-in.",
+  "activityDrawer": "The activity drawer captures SDK operations and status messages as the app works.",
+  "howItWorks": "How it works maps the UI back to the note contract and SDK helper files.",
+  "settings": "Settings collects identity, contract, local cache, and appearance controls in one place.",
+  "settingsRememberedIdentity": "Remembered identity keeps the identity ID and cached notes on this device, so notes are viewable read-only after logout.",
+  "settingsClearCache": "Clear local cache removes the local, browser-stored notes. The actual Platform documents are not deleted and the cache rebuilds on refresh.",
+  "settingsForgetDevice": "Forget this device removes the remembered identity and clears its cached notes from this browser.",
+  "settingsContractOptions": "Contract controls let you paste a different note contract ID, switch with Use this ID, or register a fresh testnet contract.",
+  "outro": "That is Dashnote: read-friendly, write-capable, and careful about identity state and local cache."
+}

scripts/walkthroughs/captions/dashrate.json

@@ -0,0 +1,25 @@
+{
+  "intro": "DashRate opens directly on live tutorial-resource ratings from Dash Platform testnet.",
+  "resourceList": "The resource list summarizes each tutorial or app with its current average and review count.",
+  "resourceDetail": "Selecting a resource reveals its detail panel, external link, and review activity.",
+  "aggregateStats": "Aggregate stats are derived from count queries, including average rating and total reviews.",
+  "histogram": "The histogram shows the per-star distribution and each row can filter the review list.",
+  "filteredReviews": "Filtered review browsing uses the same resource plus rating index shape shown in the app.",
+  "noHistogram": "This resource has no distribution yet, so DashRate keeps the empty aggregate state readable.",
+  "recentReviews": "Recent reviews stay browseable without signing in, including reviewer identity labels when available.",
+  "settingsLogin": "Settings is where you login with a testnet mnemonic for write access.",
+  "signedIn": "After login, DashRate resolves the identity and unlocks account-specific review views.",
+  "myReviews": "My reviews loads documents owned by the signed-in identity and summarizes that account's average.",
+  "myReviewCards": "Each review card shows the resource, star rating, latest edit time, and review text.",
+  "editReview": "Edit review returns to the resource page with the existing review prefilled.",
+  "prefilledReview": "The signed-in resource page shows the existing review prefilled for editing.",
+  "createReview": "On the signed-in resource page, choosing stars and entering text creates the identity's review for this resource.",
+  "saveCreatedReview": "Saving creates a real review document on testnet for the signed-in identity.",
+  "saveUpdatedReview": "Saving again updates the same identity-owned review document instead of creating a duplicate.",
+  "showHistory": "After an edit, DashRate can load retained document history for the selected review.",
+  "previousVersions": "Previous versions expose document history for edits retained by the DashRate contract.",
+  "emptyMyReviews": "If this identity has not reviewed anything yet, the signed-in state shows an empty account view.",
+  "contractSettings": "Advanced settings let you view the current contract ID, set an alternate one, or register your own copy of the contract to experiment.",
+  "readOnlyLoginPath": "Without walkthrough credentials, Settings still shows the sign-in path while the app remains read-only.",
+  "outro": "That is DashRate: public aggregate browsing, identity-owned reviews, and review history in one small app."
+}

scripts/walkthroughs/captions/token-ops.json

@@ -0,0 +1,21 @@
+{
+  "intro": "TokenOps makes multi-signer token governance on Dash Platform visible from one dashboard.",
+  "signIn": "With walkthrough credentials available, TokenOps signs in locally to reveal identity-specific governance status.",
+  "signedIn": "The signed-in dashboard shows whether this identity belongs to an operator group or has proposals awaiting approval.",
+  "readOnly": "Browse-only mode still exposes the live token, authority model, approval groups, and active proposals without an identity.",
+  "proposalStatus": "The priority cards summarize proposals needing attention, all active proposals, and the current identity's governance access.",
+  "authoritySummary": "Who controls what groups token capabilities by their live operator authority, keeping operational control easy to scan.",
+  "tokenDetails": "The compact token panel connects governance to live supply, status, contract, and token identifiers.",
+  "actionTypes": "Actions exposes mint, burn, access, emergency, and transfer paths while explaining which approval group controls each operation.",
+  "pendingActions": "Group-managed operations follow propose, co-sign, and automatic execution when the required signing power is reached.",
+  "signingProgress": "Each active proposal shows its target, proposer, signing progress, and whether the current identity can add a signature.",
+  "emptyActions": "When no proposals are active, the same view remains ready to surface the next group-governed action and its signing progress.",
+  "accessControl": "The governance matrix separates who can perform each capability from who can later reassign that authority.",
+  "groups": "Approval groups are append-only bodies with visible membership, signature thresholds, and assigned capabilities.",
+  "groupDetails": "Expanding a group reveals its members and makes the threshold behind multi-signer control concrete.",
+  "authenticatedSettings": "Settings confirms the signed-in identity and provides contract tools without requiring any action during this walkthrough.",
+  "readOnlySettings": "Settings clearly marks browse-only mode and points to sign-in when contract registration or token operations are needed.",
+  "contractResolver": "A contract or token ID can select another TokenOps deployment; token IDs resolve back to their owning contract.",
+  "registrationPath": "Authenticated owners can register a fresh contract and approval groups here, but this walkthrough performs no Platform writes.",
+  "outro": "That is TokenOps: live authority mapping, approval groups, and multi-signer token actions without hiding the governance model."
+}