Skip to main content

​
Notebook Studio

Notebook Studio is the canonical local prototyping surface for the paid notebook experience. It runs in a browser, uses synthetic fixtures, and composes the same first-party Report V2 engine used by the production code path. It does not require Expo, a simulator, Clerk, Convex, Supabase, a provider API key, or customer data.
Studio is a design and deterministic contract tool. It does not prove native sheets, gestures, haptics, safe areas, app backgrounding, or real provider behavior. Those need separate device and staging certification.

​
Start Studio

From the repository root:
Open:
The shared-package build matters. Mobile imports @tiwih/* packages from their generated dist output; stale output can make a valid source change look missing at runtime or during typecheck.

​
Ten panels

Panel and scenario selections are stored in the URL as studioPanel and studioScenario, so a specific proposal can be shared as a deterministic deep link.

​
Scenario matrix

Studio currently provides 29 scenarios. Use the pairwise matrix instead of checking only the known-strain happy path. At minimum, every change should compare:
  • one happy path;
  • one unknown or ambiguous input;
  • one stale or failed research state;
  • one cancellation or recovery state;
  • one immutable update state;
  • free and paid entitlement behavior;
  • a long or payload-pressure boundary.
1

State the product question

Example: “How should an unknown strain appear while research is pending?” or “What remains readable if an update fails?”
2

Choose the nearest fixture

Start with a built-in scenario. Avoid changing production data just to explore a design question.
3

Inspect every affected panel

Review the user journey, matching, research, lessons/evidence, lifecycle, and validation panels—not only the final card.
4

Compare adjacent states

Check before, during, successful, failed, canceled, and retry states. For updates, compare current, update available, generating, promoted, and history.
5

Export or deep-link the proposal

Use Studio’s bounded fixture export or copy the deep link. Never import production customer records or secrets.
6

Lock accepted behavior in code

Update the shared engine or fixture contract, add a deterministic test, and rerun the browser interaction and static build gates.

​
Safe fixture rules

  • Use synthetic names, orders, URLs, and evidence.
  • Do not paste emails, account IDs, addresses, phone numbers, receipts, tokens, provider payloads, or raw production database rows.
  • Preserve explicit null or unavailable values; do not replace them with plausible defaults.
  • Keep research URLs synthetic unless the fixture is specifically testing a public-source parser.
  • Treat fixture import as untrusted input; validation must pass before rendering.

​
Verification commands

Run these after changing Studio, the shared notebook engine, or Report V2 contracts:
For a broader release-quality change, also run the full mobile unit, Convex, UI, typecheck, lint, design-system, and geometry gates documented in Notebook launch runbook.

​
What Studio can and cannot certify

​
Troubleshooting

Rebuild @tiwih/report-contracts and @tiwih/notebook-engine. The mobile app consumes built workspace packages, not their source files directly.
Stop the existing local Storybook process or use the already running instance. Do not start multiple Studio servers against different branches and assume they show the same code.
Check the Validation panel first. Historical or imported content intentionally fails closed when its safe Report V2 projection is incomplete.
Treat that as an integration or native-certification gap. Record the scenario and run the equivalent app flow; do not weaken the shared contract to match an accidental mobile behavior.