Show today's AI uses, a round's cost, and the website's limit dialogs

Each tool's header says how many AI uses are left today, read again after
every request. Crossfire and Sparring say what a round costs before it
starts and check it first, as the website does. A limit or model refusal
opens the website's dialog as a sheet with its words: a paid plan's daily cap
and the weekly allowance say when access returns, other limits lead to the
plan in You (purchases wait for in-app purchase), and a model refusal can
switch the tool to low reasoning.

The screenshot script shoots both sheets and the cost notes, answers the
quota check in its Crossfire and Sparring fakes, and sends a debrief that
fits the current schema.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: Programcode

apps/mobile/AGENTS.md

@@ -18,13 +18,15 @@ The iOS app DebateOwl (`@debatelab/mobile`; the bundle id is still `com.adam.deb
 
 ## Layout
 
-- `src/app/`: routes. `sign-in.tsx`; `(tabs)/` with one route group per tab: Debate, Prepare, Practice, Library, You; the form sheets `debates.tsx` (switcher), `new-debate.tsx`, `delete-account.tsx`, `delete-data.tsx`, `add-link.tsx`, `new-note.tsx` and `source/[id].tsx`; and `ask.tsx`, `generate.tsx`, `case/[id].tsx`, `attack/`, `brainstorm/`, `factoids/` and `sparring/` (each a form `index.tsx` and a document `[id].tsx`), `crossfire.tsx` and `timer.tsx` (a full-screen modal), `flowchart/` (the screen `index.tsx` with its `card`, `claim` and `maps` form sheets), and `history.tsx`, full screen above the tabs. All are declared in the root `_layout.tsx`. Every Practice tool is in the app, so `(practice)/soon/[tool].tsx` is no longer reached from the Practice tab.
+- `src/app/`: routes. `sign-in.tsx`; `(tabs)/` with one route group per tab: Debate, Prepare, Practice, Library, You; the form sheets `debates.tsx` (switcher), `new-debate.tsx`, `delete-account.tsx`, `delete-data.tsx`, `add-link.tsx`, `new-note.tsx`, `source/[id].tsx` and `limit.tsx` (the website's limit-reached and model-restricted dialogs); and `ask.tsx`, `generate.tsx`, `case/[id].tsx`, `attack/`, `brainstorm/`, `factoids/` and `sparring/` (each a form `index.tsx` and a document `[id].tsx`), `crossfire.tsx` and `timer.tsx` (a full-screen modal), `flowchart/` (the screen `index.tsx` with its `card`, `claim` and `maps` form sheets), and `history.tsx`, full screen above the tabs. All are declared in the root `_layout.tsx`. Every Practice tool is in the app, so `(practice)/soon/[tool].tsx` is no longer reached from the Practice tab.
 - `src/components/`: shared UI. `app-tabs.tsx` uses native tabs; `app-tabs.web.tsx` draws the mock's tab bar for the web preview.
 - `src/lib/`: auth (`auth.tsx`), `native-capabilities.ts` (what the running binary has beyond Expo Go), the Supabase client, session storage (AES key in SecureStore, ciphertext in AsyncStorage) and i18n. `debates.ts`, `settings.tsx`, `subscription.ts` and `account.ts` read and write the website's tables the way its stores do (`src/lib/stores/debate-store.ts`, `settings-store.ts`, `src/hooks/use-subscription.ts`, `src/lib/account.ts`), so the app and the website share one Current Debate and one set of settings. Change them together with the website code they mirror.
 - `sources.ts` mirrors the session store's `addSource` and `removeSource` and `src/lib/source-import.ts`. The Library always shows the Current Debate, also in one-off mode, as on the website. Adding a file (the website parses files in the browser) and Scan pages are not in the app yet.
 - Ask mirrors `src/lib/ai/streaming.ts` and `askChat` in `src/lib/ai/client.ts`: `ask.ts` sends the requests (plain questions stream from `ai-stream` through `expo/fetch`; with Citations, Web search, Pros/Cons or Argument map on, the whole answer comes from `ai`, because `ai-stream` refuses those options), `ai-request.ts` holds the shared POST with the website's headers, timeout and error kinds, `feature-config.ts` reads each tool's model from `user_settings.feature_configs` (the model picker, `components/model-picker.tsx`, writes it back through `settings.tsx`'s serial queue in the website's canonical shape; tools read it through the same queue, so they run with the model just picked), `context-request.ts` builds the Current Debate context with the website's default selection and pins, and `chats.ts` saves finished exchanges to `chats` and `messages`. The SSE parser is shared in `packages/core/src/ai/sse.ts`. `markdown.ts` reads answers, because react-markdown needs the DOM.
 - Generate and Attack mirror `generateCase` and `attackCase` in `src/lib/ai/client.ts` and the session store's `recordResult`: `results.ts` sends the requests through `ai-request.ts`'s `postAI`, which streams them as the website does (`stream: true` with a `resultKey`; the reader is `packages/core/src/ai/live.ts`, shared with the website's `src/lib/ai/live.ts`) and reads a dropped stream's answer back from `ai_run_results` (`packages/core/src/ai/run-recovery.ts`). The four tool screens show the draft with `components/live-run.tsx` (the website's `LiveToolRun`; the sections come from `packages/core/src/ai/live-sections.ts`). `results.ts` also checks the output with the website's transform (moved to `packages/core/src/ai/generate-output.ts`), keeps researched sources in the debate's Auto-saved folder (`packages/core/src/ai/discovered-sources.ts`), saves the server's source rankings onto the Library sources a result used (`packages/core/src/ai/source-assessments.ts`, also for Ask's whole answers), says when the server shortened the input, and saves rows to `cases` and `attacks`. `motion.ts` and `motion-gate.ts` are the website's motion gate. `open-results.ts` holds results made in this session, so one-off work and failed saves still open as documents. It and the last Generate and Attack forms live in `session-memory.ts`, which the auth provider clears on every account change, including sign-out. `components/document.tsx` draws results as documents (mock 03); Brainstorm and Factoids reuse it. Export renders `export-html.ts` to a PDF with expo-print and shares it (`export.ts`); the web preview cannot print, so `export.web.ts` keeps the HTML and copied text on `window` for the screenshot script. Word export and Google Docs are not in the app.
 - Brainstorm and Factoids mirror `brainstorm` and `factoids` in `src/lib/ai/client.ts` and their pages, through the same `results.ts`: the brainstorm transform and the verified-factoid selection live in `packages/core/src/ai/brainstorm-output.ts` and `factoids-output.ts`, rows go to `brainstorms` and `factoids`. Brainstorm has the motion gate; Factoids, like Attack, follows the Current Debate and saves with side `neutral`. A factoid's bookmark saves it to the Current Debate's `Factoids` folder, and a search suggestion reopens the Factoids form with that query. `prepareToolHref` in `components/prepare-tools.ts` is where both tabs open a tool.
+- A case's and an attack's next steps are `result-links.ts`: "Open in Crossfire" fills the next Crossfire form through the one-shot `crossfirePrefill` slot (the website's route state; the builders are `packages/core/src/crossfire/prefill.ts`), and a case is built into an unsaved map with `flowchartFromCase` (`packages/core/src/flowchart.ts`, shared with the website), only in the debate the Flowchart is on, as on the website.
+- Limits mirror the website's subscription dialogs: `refusal.ts` turns a 402 or 403 refusal (with the limit details `errorFrom` keeps) into the `limit` sheet's parameters and holds the website's messages (`limit-message.ts`); the tools open the sheet instead of an inline error, and Ask, Crossfire and Sparring open it beside theirs. Upgrading waits for in-app purchase, so the sheet's next step is the plan in You. `usage.ts` reads today's uses for the line under each tool's title (`DailyUsageLine`, the website's DailyUsage) and reads again after every AI request (`onAIRequestSettled`). `session-quota.ts` asks what a Crossfire or Sparring round costs (`quotaCheck`), shows it above Start (`SessionCostNote`) and opens the sheet before a round the day cannot cover.
 - Timer mirrors `src/pages/TimerPage.tsx`: `timer.ts` holds the formats and a clock made of start timestamps, never counted ticks, so it is right after the app returns from the background (`timer.test.ts`). `timer-signals.ts` plays the bundled beeps in `assets/sounds` (made by `scripts/render-timer-sounds.ts`) with expo-audio, taps with expo-haptics and keeps the screen awake while a speech runs; `timer-signals.web.ts` only records the signals for the screenshot script. Lock-screen timers wait for the development build (`TODO(live-activity)`).
 - Crossfire is the website's typed mode: `crossfire.ts` sends `crossfire` and its signal requests as `src/lib/ai/client.ts` does (Ask's model settings, 75 s and 5 s deadlines), with the round's id as `quotaSession` on turns and the debrief so the round is charged once, as the website does and saves a finished round to `crossfires` in its debate, as CrossfirePage's `recordResult` call; the reducer and schemas are `packages/core/src/crossfire`. The unfinished round is a session slot, so leaving the screen keeps it. Voice rounds need the development build, so the voice switch shows disabled. The website cannot reopen a saved round, so neither can the app.
 - Sparring is the website's typed mode: `sparring.ts` sends the opponent's turns and the judge as `generateSparringTurn` and `judgeSparringSession` in `src/lib/ai/client.ts` do (the Sparring model settings, a transcript-only debate context), and the round's moves (turn order, the deadline clock, judging, saved rows) are `packages/core/src/sparring/session.ts`, shared with the website's sparring store. The server saves the judged round to `sparring_sessions` when it scores it; the app then files it in its debate with `attach_to_debate` and the student's side, as the store does. The side is asked when the round starts. The unfinished round is a session slot (`sparringDraft`), so leaving the screen keeps it, and a request cut off by leaving is offered again. The flow button opens the Flowchart on the Current Debate's map, above the round, which keeps running. Practice lists the Current Debate's judged rounds and the Debate tab lists them by side; both open `sparring/[id]`, which can delete them. Voice rounds need the development build, so the voice switch shows disabled.

apps/mobile/scripts/screenshots.ts

@@ -11,7 +11,7 @@
  * ONLY=iphone-light-en limits a run to the combinations whose name starts with it;
  * separate several with commas (ONLY=iphone-light-en,ipad-dark-hu).
  * SCREENS=you,timer limits the signed-in screens to those groups: debate,
- * library, prepare, practice, you, empty, ask, results, brainstorm, factoids,
+ * library, prepare, practice, you, empty, ask, results, brainstorm, factoids, limits,
  * timer, crossfire, sparring, flowchart, one-off, history, announcements,
  * account, model. Sign-in screens are always shot.
  * ONLY=offline runs only the offline reading check (see shootOfflineScreens).
@@ -587,6 +587,25 @@ async function shootResultScreens(context: BrowserContext, prefix: string, langu
   await pdf.close();
   console.log(`${prefix}: PDF file name ${exported.fileName}, copied ${exported.copied.length} characters`);
 
+  // The case's menu leads on: Open in Crossfire with the case filled in, and the case built into a map.
+  // Nothing is saved: the Crossfire form is not started and the map is not saved.
+  await page.getByTestId('document-more').click();
+  await page.getByRole('menu').waitFor();
+  await shoot(page, `${prefix}-case-menu`);
+  await page.getByRole('menu').getByRole('menuitem').first().click();
+  await page.getByTestId('crossfire-imported').waitFor({ timeout: 15_000 });
+  await settle(page);
+  await shoot(page, `${prefix}-crossfire-from-case`);
+  await page.goBack();
+  await page.getByTestId('case-document').waitFor({ timeout: 15_000 });
+  await page.getByTestId('document-more').click();
+  await page.getByRole('menu').getByRole('menuitem').nth(1).click();
+  await page.getByTestId('flowchart-screen').waitFor({ timeout: 15_000 });
+  await page.waitForTimeout(500);
+  await shoot(page, `${prefix}-flowchart-from-case`);
+  await page.goBack();
+  await page.getByTestId('case-document').waitFor({ timeout: 15_000 });
+
   await page.getByTestId('attack-this-case').click();
   await page.getByTestId('attack-case-text').waitFor({ timeout: 15_000 });
   await page.waitForFunction(() => (document.querySelector('[data-testid="attack-case-text"]') as HTMLTextAreaElement | null)?.value.startsWith('THESIS:'));
@@ -595,6 +614,14 @@ async function shootResultScreens(context: BrowserContext, prefix: string, langu
   await page.getByTestId('attack-document').waitFor({ timeout: 30_000 });
   await page.waitForTimeout(400);
   await shoot(page, `${prefix}-attack-result`);
+  // The case stays mounted under the attack, so its menu is looked up inside the attack.
+  await page.getByTestId('attack-document').getByTestId('document-more').click();
+  await page.getByRole('menu').last().getByRole('menuitem').first().click();
+  await page.getByTestId('crossfire-imported').waitFor({ timeout: 15_000 });
+  // Not settle(): the attack's score meter (a progressbar) stays mounted under Crossfire.
+  await page.waitForLoadState('networkidle');
+  await page.waitForTimeout(400);
+  await shoot(page, `${prefix}-crossfire-from-attack`);
   await page.close();
 }
 
@@ -666,6 +693,39 @@ async function shootTool(context: BrowserContext, prefix: string, language: stri
   await page.close();
 }
 
+/**
+ * The limit and model sheets: Generate answered with the ai function's
+ * refusals (402 limit_reached with its counts, then 403 upgrade_required).
+ * Nothing is sent to a model; "Use low reasoning instead" is never pressed.
+ */
+async function shootLimitSheets(context: BrowserContext, prefix: string, language: string, problems: string[]) {
+  const refusals = [
+    { name: 'limit-sheet', status: 402, json: { error: 'Daily limit reached', code: 'limit_reached', limit: 20, current: 20, units: 1 } },
+    { name: 'model-sheet', status: 403, json: { error: 'This model requires a Pro subscription.', code: 'upgrade_required' } },
+  ];
+  for (const refusal of refusals) {
+    const page = await context.newPage();
+    // The browser logs the refused request itself; only that error is expected.
+    const seen: string[] = [];
+    watchErrors(page, seen, `${prefix} ${refusal.name}`);
+    page.on('dialog', (dialog) => void dialog.dismiss());
+    await pinSettings(page, language);
+    await page.route(`https://${STAGING_HOST}/functions/v1/ai`, (route) =>
+      route.fulfill({ status: refusal.status, headers: { 'access-control-allow-origin': '*' }, json: refusal.json }),
+    );
+    await page.goto(`${ORIGIN}/generate?from=prepare`);
+    await page.getByTestId('generate-motion').waitFor({ timeout: 30_000 });
+    await page.waitForFunction(() => (document.querySelector('[data-testid="generate-motion"]') as HTMLTextAreaElement | null)?.value.trim());
+    await page.getByRole('button', { name: /^(Generate debate case|Vitaeset generálása|Generar caso de debate)$/i }).click();
+    await page.getByTestId('limit-sheet').waitFor({ timeout: 15_000 });
+    await settle(page);
+    await page.waitForTimeout(500);
+    await shoot(page, `${prefix}-${refusal.name}`);
+    await page.close();
+    problems.push(...seen.filter((problem) => !problem.includes(`status of ${refusal.status}`)));
+  }
+}
+
 // Made-up saved maps in the website's React Flow shape, after mock A.
 const FLOW_NODE = (id: string, x: number, y: number, label: string, type: string, strength?: string) => ({
   id, type: 'custom', position: { x, y }, width: 220, height: 96,
@@ -908,11 +968,15 @@ const CROSSFIRE_TEXT = {
 } as const;
 
 /** Fakes Crossfire's AI calls and its save for this page (see the header). Replies follow the request, as the client checks them. */
+// The round's cost, as the ai function answers a quotaCheck: one use, 16 of 20 left today.
+const FAKE_QUOTA = { quota: { allowed: true, units: 1, limit: 20, current: 4 } };
+
 async function fakeCrossfire(page: Page, language: keyof typeof CROSSFIRE_TEXT) {
   const text = CROSSFIRE_TEXT[language];
   await page.route(`https://${STAGING_HOST}/functions/v1/ai`, async (route) => {
     const body = route.request().postDataJSON() as { feature?: string; input?: { operation?: string; expectedReply?: 'question' | 'answer'; transcript?: { id: string }[] } } | null;
     if (body?.feature !== 'crossfire') return route.abort();
+    if ((body as { quotaCheck?: boolean }).quotaCheck) return route.fulfill({ status: 200, headers: { 'access-control-allow-origin': '*' }, json: FAKE_QUOTA });
     const input = body.input ?? {};
     const turns = input.transcript ?? [];
     const exchange = Math.floor(turns.length / 2) % text.answers.length;
@@ -927,8 +991,9 @@ async function fakeCrossfire(page: Page, language: keyof typeof CROSSFIRE_TEXT)
     } else {
       const d = text.debrief;
       output = {
-        concessionsSecured: [{ turnIds: ['T3', 'T4'], claim: d.concession }],
-        controlledQuestions: [{ turnIds: ['T1', 'T2'], claim: d.controlled }],
+        // Concessions and controlled questions name one turn each (SingleTurnReferenceSchema).
+        concessionsSecured: [{ turnIds: ['T4'], claim: d.concession }],
+        controlledQuestions: [{ turnIds: ['T1'], claim: d.controlled }],
         weakOrRepetitiveQuestions: [],
         evasiveOrIncompleteAnswers: [],
         missedFollowUps: [{ turnIds: ['T2'], claim: d.missed }],
@@ -958,6 +1023,10 @@ async function shootCrossfireScreens(context: BrowserContext, prefix: string, la
   await page.getByTestId('crossfire-argument').fill(text.argument);
   await settle(page);
   await shoot(page, `${prefix}-crossfire-setup`);
+  // The round's cost sits above the start button, below the fold on a phone.
+  await page.getByTestId('session-cost').scrollIntoViewIfNeeded();
+  await page.waitForTimeout(300);
+  await shoot(page, `${prefix}-crossfire-cost`);
 
   await page.getByRole('button', { name: /^(Start crossfire|Keresztkérdezés indítása|Iniciar interrogatorio)$/ }).click();
   await page.getByTestId('crossfire-live').waitFor({ timeout: 15_000 });
@@ -1026,6 +1095,7 @@ async function fakeSparring(page: Page, language: keyof typeof SPARRING_TEXT) {
   await page.route(`https://${STAGING_HOST}/functions/v1/ai`, async (route) => {
     const body = route.request().postDataJSON() as { feature?: string; input?: { action?: 'respond' | 'score'; speeches?: { speaker: string }[] } } | null;
     if (body?.feature !== 'sparring') return route.abort();
+    if ((body as { quotaCheck?: boolean }).quotaCheck) return route.fulfill({ status: 200, headers: { 'access-control-allow-origin': '*' }, json: FAKE_QUOTA });
     const action = body.input?.action ?? 'respond';
     if (holding[action]) await new Promise<void>((resolve) => { held[action] = resolve; });
     let output: unknown;
@@ -1078,6 +1148,10 @@ async function shootSparringScreens(context: BrowserContext, prefix: string, lan
   await page.getByRole('menuitem', { name: 'Lincoln-Douglas' }).click();
   await settle(page);
   await shoot(page, `${prefix}-sparring-setup`);
+  // The round's cost sits above the start button, below the fold on a phone.
+  await page.getByTestId('session-cost').scrollIntoViewIfNeeded();
+  await page.waitForTimeout(300);
+  await shoot(page, `${prefix}-sparring-cost`);
 
   fake.hold('respond');
   await page.getByRole('button', { name: /^(Start round|Forduló indítása|Iniciar ronda)$/ }).click();
@@ -1747,25 +1821,29 @@ async function main() {
             shots += 3;
           }
           if (want('results')) {
-            await shootResultScreens(signedIn, prefix, language, problems);
-            shots += 10;
+            await shootResultScreens(signedIn, prefix, language, problems).catch(failedIn(signedIn, prefix, 'results'));
+            shots += 14;
           }
           for (const tool of ['brainstorm', 'factoids'] as const) {
             if (!want(tool)) continue;
             await shootTool(signedIn, prefix, language, problems, tool);
             shots += 7;
           }
+          if (want('limits')) {
+            await shootLimitSheets(signedIn, prefix, language, problems).catch(failedIn(signedIn, prefix, 'limits'));
+            shots += 2;
+          }
           if (want('timer')) {
             await shootTimerScreens(signedIn, prefix, language, problems);
             shots += 3;
           }
           if (want('crossfire')) {
-            await shootCrossfireScreens(signedIn, prefix, language, problems);
-            shots += 3;
+            await shootCrossfireScreens(signedIn, prefix, language, problems).catch(failedIn(signedIn, prefix, 'crossfire'));
+            shots += 4;
           }
           if (want('sparring')) {
             await shootSparringScreens(signedIn, prefix, language, problems);
-            shots += 6;
+            shots += 7;
           }
           if (want('flowchart')) {
             await shootFlowchart(signedIn, prefix, language, problems);