Turn a playtest round into a revision worklist.

1. Open the app and see a complete round

1. Extract the buyer ZIP into a folder. Open UrdTrace.html in desktop Google Chrome. No installation, account or server is required.
2. Choose Load example. The app loads the original story The Ferry at Low Water and three example transcript files.
3. Open Map and Notes. You should see 17 of 20 counted passages visited, three of four endings reached, four runs, 30 passage displays and six notes.
4. Open Passages → Not reached: Sinking, TideTable and EndingTide are absent from these runs.

The aliases ana, bo and cy are fictional. These are scripted verification runs, not customer testimonials or a human usability study. The story has 21 passages in total; its StoryInit code passage is excluded from the 20-passage coverage denominator. Of 27 parsed static links, 21 have matching recorded transitions.

The free example pack contains this manual, the original story, transcripts and readable outputs. It does not contain the author app or recorder. Open example-results/round-report.html in that pack to inspect the finished result.

2. Start a round with your own story

Publish your story from Twine using Build → Publish to File. The verified publisher is Twine 2.12.0 with SugarCube 2.37.3; a separate example was compiled with Tweego 2.1.1. UrdTrace accepts published SugarCube 2.37.3 HTML. It does not accept Twee source, Twine archive JSON, Harlowe, ink or Yarn.

1. Keep an unchanged copy of the published .html file.
2. Use Open published story, or the open-file control, and select that HTML. Importing parses it without running the story in the author app.
3. Read 1 · Story check. Check the title, format, counted passages, starting passage and any static-link warnings.
4. Give the round a useful name, such as Chapter 1 — beta 2. Open 2 · Tester copy, add optional instructions and download the tester HTML.
5. Use Save round and keep that file with the original published story. Send the tester copy and instructions to your testers.

The original story is not overwritten. The tester copy preserves the story’s tw-storydata and adds the recorder. Files are bound to the exact original HTML bytes and the round: republishing, rearranging the Twine map or changing the engine can change the fingerprint. Start a new round with a newly published build; do not mix transcripts from different builds.

If your story loads images, audio or scripts from other files, preserve its relative folder layout when sharing the tester copy. UrdTrace does not bundle your external assets or remove network code from your story.

3. Ask a tester to record and return a run

Open the tester HTML in desktop Chrome. Enter an alias and choose Start recording. Play normally. Use Note (Alt+N) while the relevant passage is visible. Use New run if you want to play again. Before closing, choose Download transcript and send the resulting .urdtrace.json file back to me.

The consent panel appears before recording starts. Declining lets the tester play without captured steps; choosing to record later starts at the passage currently visible. Notes contain the tester’s text, selected kind and passage/run/step context. Avoid putting personal or confidential information in an alias or note.

Passage displays, navigation type, elapsed timing and link-target information where available are recorded. Back and forward navigation create distinct steps. Reloading the same passage retains the current run without adding a duplicate display; the recorder tracks the reload. New run restarts the story and retains previous runs and notes in that transcript.

The recorder attempts to save locally in the same browser. If storage is denied or full, it shows a warning and keeps recording in memory. Download before closing or reloading in that case. A different browser, profile, file location or cleared browser data may not contain the earlier recording. A transcript download is the reliable handoff; nothing is automatically sent to the author.

At the 2,000-display or 200-note limit, finish and download the existing transcript. Plan another round instead of assuming further activity was recorded.

4. Import and turn observations into work

1. Reopen your saved round, or open its unchanged original published HTML.
2. Open 3 · Transcripts and choose the returned files together. A round accepts at most 10 transcript files.
3. Confirm the tester names, runs, displays and notes. Wrong-build, wrong-round, malformed and duplicate-session files are refused. An invalid batch leaves the open round unchanged.
4. Use Map to select a passage. Turn route checkboxes on to show recorded runs. The inspector shows visits, notes and parsed links.
5. In Notes, filter by passage, kind or status. Change a note’s kind or mark it fixed or won’t fix. The tester’s original text remains unchanged; exports use your classifications.

Repeated visits remain separate displays. Coverage excludes SugarCube special/code passages, including StoryInit and widget passages; Story check names excluded passages. An ending tag initially marks an ending. Select a passage on the map and change Count as an ending to override that choice for this round.

Interpret coverage as evidence from the files you imported. No visits means no imported run recorded that passage. It does not prove the passage is unreachable. A matching transition can mark a parsed static link as followed; it is not proof that a particular dynamic choice was clicked.

Macro-generated and JavaScript links, conditional choices, variables and save states are not fully analyzed. Next-round hints use possible paths through parsed static links. They are not observed routes, a solver or guaranteed playable instructions. Review them against the actual story before asking a tester to follow them.

5. Export the worklist and keep an editable round

Open Export and choose Download round ZIP. Extract the result before opening its files.

To reopen, use the app’s open-file control or drop the saved round file into it. Confirm replacement if another round is open. Save the current round first if you need both. Browser autosave is a convenience for the last round, not a backup.

For a PDF, open the report in Chrome, use Print and select Save as PDF. Review the preview before sharing or printing. A maximum test with 2,000 notes produced a 223-page A4 PDF with every note’s beginning and end present. Physical printer behavior and other PDF engines are unverified.

Supported scope and tested limits

MiB means 1,048,576 bytes. Character limits follow the browser’s JavaScript string-length rules; some emoji use two units. An over-limit import is refused without replacing the open round.

Verified on Linux desktop Google Chrome 152, including local-file operation without HTTP/HTTPS requests from the app or first-party example. Narrow layouts were checked at 390 pixels. Windows, macOS, mobile operating systems and other browsers have not been independently verified.

There is no automatic gameplay, bug diagnosis, variable capture, cloud collection, live collaboration or complete dynamic-branch analysis. Human playtest usefulness and willingness to pay remain unverified.

Troubleshooting

“Different build” or “different round”

Use the saved round and original published HTML from which the tester copy was generated. Do not republish to recover an older file. Keep each beta round in its own folder. If the old original file is missing, start a fresh round; do not edit a transcript’s fingerprint.

A later download is reported as a duplicate session

Save the round, remove that tester’s earlier transcript in 3 · Transcripts, then import the newer download. Do not import both as different testers. Note edits are retained when the same note IDs return.

The map has no useful positions or the hint is incomplete

The map uses positions from the published story where available and otherwise uses a regular layout. Macro/JavaScript links may be missing from the static graph. Use recorded passage routes and notes as the primary evidence.

Local saving is unavailable

Use Save round in the author app and Download transcript in the recorder before closing. Browser restrictions, file location changes or storage cleanup may remove local state.

The download does not open

Wait for the browser download to finish, extract ZIPs fully, and open the HTML file rather than a compressed preview. Check browser download permissions. Keep the whole manual folder so its images remain available.

The example totals differ

Start with a fresh example after saving your own work. The shipped result is 17/20 passages, 3/4 endings, four runs, 30 displays and six notes. Changing ending flags changes ending totals. Filtering Notes changes the visible list, not exported round totals.

Privacy, backups and removal

UrdTrace processes files locally. The author app does not upload imported stories or transcripts. The recorder itself sends nothing automatically. Your own story can contain network requests, remote assets or third-party code; running the tester copy also runs that story.

A saved round contains your complete published story and tester data. Share it only with people who should receive both. Reports and CSVs include aliases and notes. Keep private backups of originals, transcript downloads and saved rounds.

To remove UrdTrace, close its tabs and delete the extracted app folder and any downloads you no longer need. Local browser copies can persist: in Chrome’s developer tools, use Application → Storage for the relevant app/tester context. The author app uses IndexedDB; the recorder uses localStorage. Clear only the relevant UrdTrace entries if other local apps share that storage. Export anything you need first. Deleting the app folder alone does not clear browser storage.

For support, start with the product page at perunlight.com/store/urd-trace/. Describe the browser version and exact error. Use a small fictional reproduction when possible.