Mobile: Complete mockup, UI/UX, action, and business-logic coverage

[TheDarkSkyXD]

Parent

Part of #122, Build StreamFusion Mobile for Android.

What to deliver

Continuously review mobile UI and UX against the approved Android mockups and interaction model. Every feature issue implements its own complete UI, interactions and behavior before it closes. Audit every screen, nested route, tab, Settings panel, shared component, feature component, overlay, and user-visible state. Fix mismatches and missing interactions, then prove the result in the real Android app. A populated route or a static screenshot alone is not completion.

This is one app-wide coverage and consistency issue, starting during development. Existing feature tickets own their complete UI, UX, behavior, integration and proof. Coordinate corrections with those owners before their feature closes. Do not accumulate unfinished pages here for release-stage implementation.

Design authority

Use the approved prototype B and all subsequent approved amendments from #104, the current Android navigation and interaction model, the implementation specification, and the StreamFusion design system. Inventory all approved mockups and review scenarios, including later additions. Rejected prototype A/C designs and superseded mockups are comparison history, not requirements to implement.

Record each source revision. Where an approved mockup is missing, document the gap and resolve the design using the existing system before marking the corresponding screen covered. Escalate genuine product-design conflicts rather than silently changing navigation or dropping outcomes.

Coverage checklist

• Create a reviewable coverage matrix with stable entries for every approved mockup/scenario, route, screen, tab, panel, component, and applicable state. Each entry identifies its design reference, implementation owner, feature issue, expected interaction, device configuration, evidence, and unresolved findings. Reconcile the matrix with actual route/component inventories so unmocked implementation and unimplemented mockups cannot disappear.
• Cover Search, Following, Watch, Activity, and More; app headers, account shortcut, independent navigation histories, Android Back, deep links, restoration, and primary navigation visibility. Preserve the user's portrait main-navigation requirement. Test supported wider-window adaptations separately and restore the emulator to portrait afterward.
• Cover Home, Categories and selected Category Detail, Channel Detail, all Search result types and local history, Following and Guest Follows, filters, sorting, refresh, pagination, and local search fields. Category Videos show VODs, not currently live streams.
• Cover live Watch, Video and Clip playback, controls, seeking, Chat/Info/Related supporting sheets, captions, movable mini-player, Android PiP, Multistream configuration and retained slots, focused audio, degradation notices, and Watch History.
• Cover Twitch and Kick chat, emotes, badges, cosmetics, replay, managed-channel selection, moderation rooms, contextual actions, role restrictions, and unavailable-provider states.
• Cover Activity filters, badges, item detail and routing, guest notifications, permission prompts, foreground/background notification entry, job progress and recovery, and duplicate ingestion that preserves read state. Verify contextual download, recording, export, and cancellation controls. Do not invent a separate Media or Downloads destination.
• Cover account connection, disconnected/expired/denied states, all 17 currently specified Settings panels, all 42 currently specified tab states, all six Diagnostics tabs, update/install prompts, reports, maintenance, and destructive confirmations. Reconcile these counts against the current approved inventory rather than treating them as a cap.
• Inventory and review shared and feature-owned buttons, icon buttons, navigation items, tabs, inputs and floating search fields, toggles, sliders, selectors, chips, cards, lists, avatars, thumbnails, category art, badges, tooltips, menus, sheets, dialogs, toasts, skeletons, progress indicators, and empty/error/retry panels wherever present or required by the mockups. Verify their actual screen usages, not only isolated examples.
• Review applicable default, pressed, selected, focused, disabled, busy, empty, loading, refreshing, partial, stale, offline, failed/retry, permission-denied, signed-out, signed-in, unsupported, and constrained states. Include long text, missing art, large lists, keyboard-open states, and destructive-action cancellation. Explain genuinely inapplicable combinations in the matrix.

Requirements, actions, and logic traceability

Audit the complete product contract, not only visual consistency. Reconcile the original grilling questions and their approved answers, subsequent decision amendments, the PRD/implementation specification, approved mockups, current Desktop outcomes, and Android implementation tickets. A closed grilling issue or an approved PRD does not prove that every action or logic path is covered.

• Create a source register with the exact issue comment or document section and revision for each decision. Identify superseded answers and unresolved questions. Follow the specification's conflict order and record later explicit user decisions. Never infer approval from an unanswered question.
• Build a bidirectional requirements matrix. Trace each requirement to its component or non-UI entry point, action/event, business rule, success/failure states, implementation owner and issue, automated tests, and observed evidence. Trace actual components, handlers, workflows, native commands, and background events back to requirements too. Detect both requirements without implementations and behavior without an approved requirement.
• For every action, record its actor, trigger, inputs, validation, permissions/scopes, preconditions, allowed state transitions, side effects, persistence authority, visible result, cancellation behavior, failure containment, and recovery. Include buttons, gestures, keyboard actions, menus, dialogs, deep links, Android notifications, timers, lifecycle callbacks, native callbacks, and relay events. Noninteractive components link to the display and accessibility rules they render.
• Inventory business rules independently of screens. Include discovery filtering/sorting/pagination, content identity, VOD-versus-live separation, Guest Follows and account follow restrictions, OAuth/token lifecycle, chat/moderation eligibility, focused playback/audio ownership, captions, measured device admission, degradation/hysteresis, and media-job transitions. Include notification deduplication/read-state preservation, registration/fanout, cache and Product Store boundaries, retention, migration, offline behavior, export, update verification, and destructive-action safeguards.
• Cover concurrency and lifecycle edges for each applicable workflow. Exercise repeated taps, duplicate/out-of-order events, stale async responses, simultaneous commands, timeout, retry, cancellation, partial failure, permission revocation, account switching, foreground/background changes, process death, reboot, and restoration. Verify idempotency and artifact preservation where required. A happy-path screenshot is not logic evidence.
• Maintain a gap register for missing requirements, ambiguous rules, contradictions, missing actions, unsupported assumptions, unowned behavior, missing implementation, and missing evidence. Each gap has a stable ID, source references, user impact, owner, blocking relationship, and resolution. Amend the PRD or supporting decision record when a requirement is missing. Obtain an explicit decision for genuine product choices instead of inventing one or rewriting historical approvals.
• Track specification, implementation, and verification separately. Use explicit missing, blocked, or not-applicable states with reasons. Define exhaustive coverage against a pinned inventory and declared scenarios, not a claim to have tested every possible input. Aggregate code coverage percentages and the existing capability/panel/tab counts cannot substitute for this mapping.
• Add a repeatable reconciliation check that flags new or removed routes, components, actions, and requirements without corresponding matrix updates. Pin source revisions and invalidate affected evidence when the implementation or approved requirements change.

Completion gate

• Publish the reviewed traceability matrix and gap register alongside the UI coverage report. Every required component, action, and business rule has a source decision, an implementation owner, and current verification evidence for its applicable outcomes and failure paths.
• Resolve all missing or contradictory required behavior and all missing required evidence before closing this issue. A linked follow-up alone does not make a gap complete. Approved exclusions require a cited decision and must respect the parity contract.
• Review the amended PRD and supporting decisions against the matrix. Report separate totals for specified, implemented, verified, blocked, and explicitly inapplicable entries, including remaining human decisions. Feed the complete report into P01: Close every Android parity record #179 and P02: Pass the complete Candidate Gate twice #180. Do not describe the grilling session, PRD, or product as exhaustively covered until this gate passes.

Acceptance criteria

• Every applicable matrix entry has an implemented outcome and current observed evidence. Every UI/UX, action, and business-logic finding is resolved and re-tested before closure. Link prerequisite feature work explicitly; placeholders, unavailable required features, and deferred findings do not count as passing coverage.
• The real app matches the approved visual hierarchy and interactions. Verify Dark Theater colors, Inter typography, spacing, density, alignment, icon consistency, radii, Platform accents, circular channel avatars, 16:9 media thumbnails, and 3:4 Category art. Document necessary Android-native adaptations with their design rationale.
• Primary controls remain reachable and visible without overlap, clipping, unintended horizontal scrolling, or lost content. Verify safe areas, system bars, keyboard avoidance, bottom-search insets, sheets, mini-player placement, and long-content scrolling.
• Verify at least 48dp touch targets, accessible labels/roles/states, logical TalkBack and keyboard focus, contrast, Android font scaling, and reduced motion. Report dimensions in density-independent units, not raw screenshot pixels.
• Exercise compact portrait phone, supported tablet/foldable layouts and resizing, API 30 and the current supported Android test target. Use the approved device verification policy for physical-device evidence. A missing device or unrun scenario remains an explicit blocker, not an inferred pass.
• Start the app through literal root npm start, select option 3 interactively, and record cold/warm launcher timings and startup failures. Use Mobile MCP for real navigation and interaction checks. Expo Go evidence covers only its supported behavior; exercise custom native modules and encrypted storage in the matching development client. Record the tested APK hash and source revision.
• Capture readable reference-versus-app screenshots at matching viewport/configuration for every approved screen scenario, plus interaction evidence for overlays, components, state transitions, navigation, and recovery. Automated snapshots can supplement, but cannot replace, observed functional checks.
• Add or update repeatable regression tests for fixed defects and coverage omissions. The normal Change Gate and applicable UI, accessibility, and lifecycle checks pass on the final candidate. Re-run affected evidence after a source or design change.
• Publish a final coverage report linked to the current Android candidate and Desktop Baseline. No open required UI/UX or logic finding, unanswered product decision, or missing required mockup, screen, component, action, rule, state, or evidence remains. Feed the report into P01: Close every Android parity record #179 parity records and P02: Pass the complete Candidate Gate twice #180 Candidate Gate acceptance.

Sequencing and ownership

No prerequisite blocks starting the inventory and approved-mockup audit. Final verification waits for the relevant feature implementations: #139, #141, #143, #145-#146, #148-#160, #164-#172, and #176. Logic traceability also covers the non-UI foundation, relay, media-engine, and notification delivery work under #122, including #144, #147, #163, #173, and #174. Track exact missing evidence per matrix entry instead of claiming unfinished features are verified.

This issue blocks #178 production artifact promotion and retains its block on #180 final candidate acceptance. Complete each feature's UI/UX inside that feature issue, review each milestone continuously, and finish integrated development-candidate UI/UX review before promotion begins. #179/#180 revalidate completed work against release evidence; they are not prerequisites for starting or completing this development review. Publisher identity setup and verification tooling remain independent. Do not create reverse blockers from feature tickets to this review. Do not skip #143 or silently waive its recorded qualification sequencing question.

Use one owner for this GitHub issue, at most two subagents across the program, and no overlapping file ownership with feature agents. Implementation belongs under apps/mobile with feature-owned responsibility boundaries. Root launch orchestration remains supported. No desktop release, release publication, new paid test service, or production signing change is authorized by this issue.

PRD amendment and per-feature closure

The user's 2026-09-07 direction requires complete UI/UX in every feature issue, before release work. The expanded PRD and normative screen and control contract bind each screen, tab, control, action and approved grilling decision to feature acceptance. No placeholder or backend-only outcome closes a user-facing feature. Pure infrastructure documents its consumer and justified no-new-UI scope.

Specification, implementation and verification remain separate. The completed audit is not completed product UI. Numeric defaults/thresholds that lack an approved source remain explicitly unresolved, not silently copied from prototype data.

Sources

• Approved integrated PRD/specification and approval record

• Current implementation specification and linked supporting decisions

• Original Android planning and grilling map

• Approved mockup decisions and amendments

• Interactive Android mockups

• Android navigation and interaction model

• StreamFusion design system

• Implementation ticket graph and coverage inventory

• Android parity closure

• Candidate verification

Published PRD amendment: part 1, including feature-owned UI/UX acceptance, part 2, including grilling decisions and remaining explicit questions, and normative screen/control contract. Repository documents are updated locally; these comments retain the amendment independently of the pending documentation commit.

Development placement and release stop

This issue is ordered after #143 in the parent list and starts review during M2. Its M6 milestone is the final completion checkpoint, not permission to wait until M6 to design or implement screens. Every feature owns its complete UI/UX before closure. #195 cannot close while required feature implementation, design decisions or verification findings remain.

#178, #179, #180 and #181 are all directly blocked by this issue. Artifact promotion is now in M7. No reverse blocker prevents early review or feature development, and this ordering does not skip #143. Final release checks revalidate finished UI/UX rather than implement it.

Full qualification completion prerequisite

#196 must complete before this issue closes. Continuous review still starts during development without a start blocker. The user requires all full-workload qualification, integrated behavior and UI/UX before release. #196 directly blocks #178 through #181. Feature owners must still finish their own UI/UX before closure; this split does not defer unfinished feature UI to qualification or release.

[TheDarkSkyXD]

Mobile coverage audit, 2026-09-07

Verdict

The audit of the current planning baseline and Mobile implementation is complete. Coverage fails. The grilling decisions and PRD cover the major capability families, but they do not establish a complete component/action/business-rule contract. The Mobile product is not fully implemented or verified. Issue #195 remains open for remediation and final acceptance.

Source revision: 4a43205f31d1e4d100d6a46020389404fcc3942c. Unlanded issue #143 work is excluded. Historical evidence is identified as historical, not rerun device proof. No application code, database, account, emulator, release, or dependency state was changed for this audit.

Scope and reconciliation

Reviewed the approved grilling resolutions in #101–#110, the #121 graph approval, #122 clarifications, #195 acceptance, the complete implementation PRD, navigation model, device policy, continuous parity contract, design system, prototype declarations, desktop capability ledger, and implementation graph. Saved issue snapshots are under ../sources/.

• All 24 desktop capability IDs have issue-family owners. This is ownership coverage, not completed behavior.
• The prototype declares 34 screens, 65 review scenarios, 17 Settings panels, 40 tab states, and 25 distinct data-action names. These counts overlap and must not be added together. Helper-generated controls are additional control sites.
• The implementation inventory covers all 63 tracked Mobile files with .ts, .tsx, .mjs, .cjs, or .kt extensions at the pinned revision, including tests, scripts, native modules, and the vendor shim. It is not a count of 63 implemented components.
• prd-source-ledger.json records 320 nonempty source rows with section and issue-family ownership. Rows include explanatory prose and table headings, so 320 is not an acceptance-criteria count.
• GitHub has 60 epic children, 20 closed and 40 open at capture. The committed graph has the original 59 tickets and excludes Mobile: Complete mockup, UI/UX, action, and business-logic coverage #195.
• No fresh full-screen, accessibility, physical-device, live-provider, media, or end-to-end runtime audit was performed. Missing product implementations prevent such proof at this revision.

Capability and action-family matrix

Each row is specified at capability level. Individual-action specification is incomplete until actor, precondition, transition, failure/retry/cancel, persistence, permissions, and test/evidence IDs are bound. The action families below identify what that binding must cover; they do not approve new behavior or infer mockup defaults as business rules.

Capability	Existing owners	Action and rule families to trace	Current Mobile implementation
home-live-discovery	#130, #131, #132, #147, #148	Refresh, paginate, select platform/channel, partial-provider recovery	Product flow not implemented
category-discovery	#130, #132, #133, #147, #150	Browse category, switch live/VOD/clip tabs, filter and paginate; Videos must exclude live streams	Product flow not implemented
search	#130, #132, #133, #147, #149	Enter/clear/submit query, switch result types/platforms, paginate, cancel stale requests	Product flow not implemented
vod-and-clip-playback	#133, #154	Open VOD/clip, seek, quality, ended/unavailable content, replay synchronization	Product flow not implemented
followed-streams-and-sync	#134, #147, #151	Guest follows, account follows, follow/unfollow, refresh, partial sync, reconnect	Product flow not implemented
platform-account-auth	#135, #145, #146	Connect, callback, cancel, select account, refresh single-flight, auth loss, disconnect	Product flow not implemented
live-chat	#136, #156, #157	Join/reconnect, read/send, send eligibility, channel changes and failure recovery	Product flow not implemented
emotes-and-cosmetics	#136, #158, #168	Picker/search, render provider cosmetics, unavailable assets, preference changes	Product flow not implemented
notifications	#136, #141, #151, #169, #172, #173, #174	Guest/account eligibility, dedupe, persist/read, permission, foreground/background routing, job events	Local Activity subset; read-state defect
app-shell-and-navigation	#139, #141	Five destinations, reselect, Back, nested routes, links, restore, corrupt-state fallback	Shell subset implemented
diagnostics-logs-and-bug-reports	#143, #170, #171	Six tabs, device limits, collection, redact/export/report, recovery	Foundation diagnostics only
multistream	#143, #160, #167	Configure up to six slots, measured active limit, focused audio, degrade/recover, retain slots	Product flow not implemented
live-playback	#152	Open stream, reconnect, provider errors, focus and lifecycle transitions	Product flow not implemented
player-controls-and-pip	#153, #167	Play/pause, quality/audio, fullscreen/PiP, exit and restoration	Product flow not implemented
watch-history	#155	Record/update history, reopen, remove/clear, no automatic playback on restoration	Product flow not implemented
chat-replay	#158	Synchronize to media time, seek, reconnect and missing replay	Product flow not implemented
moderation	#159, #168	Eligibility, moderation actions, confirmation, feedback and failure handling	Product flow not implemented
ad-blocking	#161, #169	Provider-specific filtering, fallback, visible limitation and preferences	Product flow not implemented
proxy-and-connectivity	#162, #169	Configure/select route, validate, connection failure, recovery and isolation	Product flow not implemented
downloads	#163, #164	Create job, progress, cancel/retry, capacity failure, recovery, private artifact/export	Product flow not implemented
stream-recording	#163, #165	Start/stop, segments, safe finalization, interruption/recovery, artifact validation/export	Product flow not implemented
local-captions	#166	Model install/delete, session start/stop, locale, load failure, contention and lag	Product flow not implemented
general-chat-and-theme-preferences	#167, #168, #170	17 panel inventory; edit/apply/reset/persist settings, permissions and unsupported-device states	Product flow not implemented
app-updates	#170, #175, #176, #178	Stable foreground check, 24h automatic limit, verify exact APK, install handoff, reject unsafe artifact	Product flow not implemented

Verification status for every row: complete current-candidate parity is not established. Shell, Activity, storage and native-boundary historical tests prove subsets only. Closed extraction/foundation tickets do not mean their eventual Mobile capability is done.

Gap register

ID	Finding and evidence	Classification	Existing owner and closure condition
AUD-195-01	Duplicate ingestion resets read state. Core activity/domain/index.ts:248 assigns null; Mobile product-store.ts:143–156 persists it. Core and Mobile tests explicitly expect the reset. An in-memory public-API probe returned null after a marked-read item was reconciled.	Confirmed defect against the user's preserve-read-state instruction; IMPL-195-001	#195 with #141 reconciliation scope. Correct the rule and both test expectations; prove duplicate delivery before/after restart does not duplicate or unread an item.
AUD-195-02	The existing ledger maps capability IDs to code paths, not individual acceptance criteria. PRD source rows and broad ticket acceptance cannot establish every component/action/rule. The parity contract itself acknowledges structural scanning cannot infer every behavioral change.	Specification and traceability gap	#195, #177, #179. Give each action/rule a stable criterion, source decision, implementation entry, owner, tests and observed evidence; record unresolved choices explicitly.
AUD-195-03	#143/B06 requires measured lowest-device qualification. PRD §7.2 requires two videos, captions, recording, downloads and complete diagnostics. W01/W09/M02/M03/M04/M09 implementations transitively depend on B06. The explicit graph has no cycle, but this acceptance condition depends on later work.	Semantic sequencing contradiction	#143 and #121/#122. Approve separation of foundation capability measurement from later full-workload qualification, or revise dependencies. Do not silently close #143 on synthetic load.
AUD-195-04	PRD §14.3 requires absolute performance budgets plus a 10% regression limit, but approved sources do not supply complete numeric startup/frame/memory/caption-lag budgets or measured qualification duration and hysteresis thresholds. #108 delegates those details; #106 does not finish them.	Unresolved acceptance policy	#143, #177, #179. Record measurable thresholds and workload methodology before claiming qualification. Existing exact media/scale/accessibility values remain binding.
AUD-195-05	Prototype line 2987 offers prerelease updates, background startup checks and an hourly option. Later PRD §13.4 and approved #110 specify stable-only foreground checks with automatic checks no more than once per 24 hours.	Stale mockup contradicts later approved policy	#195, #176. Align the prototype and control contracts to the approved updater policy. No new user choice is needed to remove this stale conflict.
AUD-195-06	Evidence verifier exits successfully for 18 artifact records, but all 18 are expired as of 2026-09-07. The catalog has only three keys, one a storage-foundation key rather than a desktop capability. The verifier validates retained artifact integrity, not the complete current 24-capability set, current candidate, and current-time expiry.	Missing full parity gate, not a claim that a production release gate was bypassed	#177/#179. Add complete-set/current-candidate/expiry checks and negative tests. Keep historical integrity success distinct from promotion readiness.
AUD-195-07	No complete current Android parity manifest binding all 24 IDs to individual criteria/digests was found. The #142 report exists, but its entries are absent from the central evidence catalog.	Record/index completeness gap	#142 bookkeeping, #177/#179. Reconcile central indexes and implement the promised contract records before parity acceptance.
AUD-195-08	PRD still says Draft for approval despite #107 approval. Its §8.3 placement sketch predates current feature-owned AGENTS rules. Its TanStack Query/Zustand directives are not reconciled with the current foundation. Device-policy degradation order also differs from the later PRD §7.3 order.	Source maintenance and decision reconciliation	#195/#122. Correct status and stale source references; document supersession. Do not turn a documentation audit into an unapproved architecture rewrite.
AUD-195-09	The committed graph omits new #195 and its gate into #180 while GitHub includes them.	Tracking drift	#195/#122. Reconcile the stored graph with approved GitHub relationships without reordering implementation.
AUD-195-10	Mobile has no product notification/relay/job producer feeding Activity. The diagnostics storage-proof item is the sole local producer. Guest policy in shared Core is not Android delivery implementation.	Planned but missing integration; IMPL-195-003	#141 integration boundary plus #151/#172–#174 and media owners. Verify Guest and account notification entry, permission denial, offline/retry, deduplication and preserved read state.
AUD-195-11	Most product destinations are summary/preview routes. No 17 Settings-panel implementations or complete product control library exist. Diagnostics contains working foundation/proof controls, not the six required product tabs.	Planned but missing UI and workflows; IMPL-195-004	Capability owners above and #195. Replace previews through dependency-ordered feature work, then verify every mockup scenario and action against the same candidate.
AUD-195-12	All five Kotlin modules return NATIVE_OPERATION_UNSUPPORTED at the pinned revision; development proof calls are the only native callers. Typed bridges do not implement playback, jobs, captions, resource diagnostics or updates.	Planned but missing native behavior; IMPL-195-005	#143, #152–#154, #160, #163–#166, #171, #176. Prove actual operations, lifecycle and failure containment on Android. Do not reopen #142 merely because its deliberate boundary stubs are not full features.

Decisions versus engineering work

Human decisions are limited to the unresolved qualification sequencing and acceptance thresholds, and any genuinely unspecified product rule uncovered while making the action contracts. Existing approved behavior needs no fresh approval: preserve read state, Guest notification coverage, VOD-only Videos, stable foreground updates, safe restoration without autoplay, private media with explicit export, portrait navigation requirements, and the approved workspace/root launcher boundary.

The audit does not label the whole issue ready-for-human. Most work is already specified and can proceed in dependency order. It does not authorize skipping #143 or changing its acceptance silently.

Checks and independent review

• Public Core Activity probe: reproduced the read-state mismatch without persistent writes. See read-state-probe.txt.
• Desktop parity inventory check: passed. This is a structural inventory check, not complete Mobile parity.
• Evidence verifier: exit 0, 18 verified artifact records. Independent expiry inspection found all 18 expired. See evidence-verified.json; do not interpret its success as release readiness.
• Mobile inventory: rerunnable extraction and anchor checks. Anchors validate source locations, not correctness by themselves.
• Independent source review rejected a proposed startup-race finding: requireProductStore awaits the shared initialization promise before testing readiness. No startup race is claimed on that evidence.
• No app mutation or fix is included. Existing telemetry changes remain untouched.

Deliverables and limits

See ../implementation/implementation-audit.md, ../implementation/inventory.json, ../implementation/findings.json, and prd-source-ledger.json for the source inventory, implementation actions/tests, and PRD ownership ledger. These artifacts let the next issue owner reproduce the baseline and address specific gaps.

Completing this audit means the reviewed baseline has a documented coverage verdict and owned gaps. It does not mean every future component is specified, all 65 prototype scenarios passed, or #195/#122 can close. #195 closes only after the gaps are resolved and its current-candidate acceptance evidence is complete.

[TheDarkSkyXD]

Mobile implementation audit

Scope and method

This audit reads main at 4a43205f31d1e4d100d6a46020389404fcc3942c. It does not inspect the unrelated issue 143 worktree. inventory.mjs reads the pinned Git tree and writes inventory.json. Run node .audit/issue-195/implementation/inventory.mjs from the repository root to refresh it.

The inventory counts every apps/mobile file ending in .ts, .tsx, .mjs, .cjs, or .kt. It records each path, byte size, file kind, matching public declaration or interaction line, and requirement area. The 63 files are 3 routes, 38 production files, 5 Kotlin modules, 5 scripts, 11 test files, and 1 vendor file. Counts describe the pinned inventory. They do not show implementation or verification coverage.

The approved mockup source is docs/research/streamfusion-mobile/prototypes/android-navigation-prototype.html at the same revision. Its declared inventory contains 34 screens, 65 review scenarios, 17 Settings panels, and 40 tab states. inventory.json extracts the exact screens, panels, tab groups, 25 declared data-action names, and prototype control sites. The scenario total follows the prototype code. It combines non-tabbed screens with every tab state.

Current implementation map

Area	Source files and components	Actual outcome	Ticket area
Expo routes	app/_layout.tsx, app/index.tsx, app/+native-intent.ts	One index route renders MobileRuntime. The native-intent route returns null.	F03, B01, B04
Composition	src/composition/mobile-runtime.tsx	Constructs shell, encrypted store runtime, link source, diagnostics status, and native-contract adapters. It has no product service composition.	B01
Shell	features/shell/**	Five destinations, 8 More routes, independent in-memory histories, persistence, allowlisted Activity and Watch deep links, compact bottom navigation, and a 600 dp rail. Search, Following, Watch, and most More routes render preview text.	B02, B04
Activity	features/activity/**	Lists persisted Activity items, filters All, Channels, and Jobs, marks records read, retries failed persistence, and opens allowlisted destinations. The only current producer is the storage-proof action.	B04
Storage	features/storage/**	SQLCipher key handling, Product and Cache stores, migrations, integrity checks, quarantine and restore, bounded cache eviction, Activity persistence, and shell snapshot persistence. Product tables for follows, history, policies, and jobs are schema only.	B03
Diagnostics	features/diagnostics/**	Starts persistence and displays runtime and storage proof status in More > Diagnostics. It does not implement the six Diagnostics tabs, capability profile, reports, or recovery controls.	B01, B03, B05
Native contracts	features/native-contracts/**, modules/streamfusion-native-contracts/**	TypeScript ports validate bridge responses. All five Kotlin modules return NATIVE_OPERATION_UNSUPPORTED. The sole caller is a development-only safe-stub proof.	B05
Design	src/design/tokens.ts, shell/components/destination-icon.tsx	Token values and destination icons. No reusable product control library beyond the local components.	B02
Build and compatibility	scripts/**, tests/*.test.mjs, vendor/query-string-compat.cjs	Expo Go and custom-client commands, Android build configuration checks, and query-string compatibility.	F03

inventory.json is the complete file-level mapping. It includes files that do not implement a component, such as adapters, capability types, tests, scripts, and the vendor shim. The requirement-area values identify foundation ownership. They do not claim that a future capability is implemented.

Components and public actions

Component or workflow	Trigger and transition	Evidence	Status
PrimaryNavigation	Selects Search, Following, Watch, Activity, or More. Selecting the current item returns its history to root, then requests scroll-to-top.	app-shell.tsx:637-670, shell-navigation.ts:306-375	Implemented shell behavior
Header Back	Pops the current destination trail. Android Back uses the same reducer when a trail exists.	app-shell.tsx:96-108, 192-250	Implemented shell behavior
Accounts shortcut and MoreMenu	Navigates to Accounts or one of Home, Categories, Multistream, History, Moderation, Settings, Diagnostics, and Accounts.	app-shell.tsx:233-249, 551-594	Navigation only. Each target except Diagnostics renders generic route text.
Root previews	Search, Following, and Watch each open a *-preview route.	app-shell.tsx:491-528, shell-navigation.ts:112-150	Placeholder. The selected Watch channel explicitly does not restart playback.
ActivityScreen	Filters locally held items, marks all read, opens a detail route, retries a failed load.	activity-screen.tsx:27-147, activity-controller.ts:64-170	Implemented local Activity subset
ActivityDetailScreen	Marks an unread record read on mount, retries only failed mark-read writes, then routes to an allowed destination.	activity-screen.tsx:240-343	Implemented local Activity subset. Destinations are previews or static routes.
PersistenceStatus	Runs the isolated store proof and then records one local system Activity item.	app-shell.tsx:352-439, mobile-runtime.tsx:42-49	Development diagnostics, not a product storage-control workflow
Restoration proof controls	Write malformed or unsupported snapshots for a later app reopen.	app-shell.tsx:443-489	Development only
Native stub proof	Sends safe stop, cancel, snapshot, and nonexistent-artifact calls to the five stub modules.	native-capability-stub-proof-control.tsx:11-64, android-capability-stub-proof.ts:36-70	Development only. It proves containment, not playback, jobs, captions, diagnostics, or updates.
Native port operations	Expose playback, media jobs, captions, diagnostics, and maintenance methods with parsed response types.	android-capability-contracts.ts:54-171, adapter :136-316	Interface only. No product caller starts playback, a job, captions, resource collection, APK verification, or installer handoff.

The action scan finds 13 source onPress sites. Map-generated controls expand these to five primary destinations, eight More rows, three Activity filters, two restoration-proof buttons, and list rows. There are no TextInput, onChangeText, onSubmitEditing, gesture, player, chat-composer, Settings-control, account-connect, or media-job control implementations in apps/mobile/src.

Prototype control classification

inventory.json classifies each data-action and six helper or binding groups. activity-tab is an implemented subset. The app has the All, Channels, and Jobs filter controls. The generic data-screen binding is also an implemented subset only for shell navigation. Search and chat fields, the mini-player pointer and keyboard handlers, scenario controls, variants, and question controls are design-only. settingToggle, settingChoice, settingRange, and settingField are unresolved rules. Their sample values, ranges, and defaults are not approval for product behavior.

Approved mockup comparison

The route registry lists these current reviewable route IDs. search, following, watch, activity, more, search/result-preview, following/channel-preview, watch/session-preview, activity/alert-preview, activity/job-preview, more/home, more/categories, more/multistream, more/history, more/moderation, more/settings, more/diagnostics, and more/accounts. See shell-navigation.ts:6-20.

The shell meets the five-destination shape. It does not supply the required product screens. The implementation owns only Activity's three tab states. Search, Following, Category Detail, Channel Detail, Watch, Video or Clip, and Moderation have no tab component or state implementation. None of the 17 Settings panels has a panel component. More > Diagnostics is an exception. It renders the storage and runtime foundation panels plus development-only proofs, but it does not implement the six approved Diagnostics tabs, capability profile, reports, or recovery controls. The generic NestedRouteState renders SAVED PLACE text for the other unimplemented nested routes. See app-shell.tsx:530-548.

Future work maps to existing graph ownership. Discovery and account UI map to D02 through D08. Watch, player, history, chat, moderation, multistream, filtering, and connectivity map to W01 through W11. Media jobs and captions map to M01 through M04. Settings map to M05 through M08. Diagnostics and reports map to M09. The signed updater maps to R02. This audit does not count those planned tickets as current implementation.

Findings

IMPL-195-001. Duplicate Activity ingestion resets a read item to unread.

Severity: required behavior regression.

The issue requires duplicate ingestion to preserve read state. ProductStore.recordActivity reconciles same-ID items at apps/mobile/src/features/storage/data/product-store.ts:127-170. The shared reconciliation rule unconditionally sets readAt to null for channel, job, and system records at packages/core/src/features/activity/domain/index.ts:234-261. The Product Store then writes that null value in its conflict update at apps/mobile/src/features/storage/data/product-store.ts:143-156.

Reproduce with one event ID. Record it unread. Call markActivityRead. Record a duplicate with the same event ID. The second write updates read_at to null. The mobile persistence test currently codifies the failure under the title "deduplicates Activity events, preserves occurrence, and resets unread state" at apps/mobile/src/features/storage/tests/persistence.test.ts:225-251. The core test also asserts the reset at packages/core/src/features/activity/tests/activity.test.mjs:74-90.

Owner: the Activity reconciliation rule in shared core, with mobile B04 integration and regression tests. This is not a SQL-only fault.

IMPL-195-003. Activity integration has no notification, relay, job, or lifecycle event source.

Severity: missing required feature implementation.

The only recordActivity path in Mobile is recordStorageCheck, called after a diagnostics proof. See activity-controller.ts:135-146 and app-shell.tsx:352-359. No mobile source imports an Android notification API, relay event source, or media-job callback into Activity. Therefore foreground and background notification entry, job progress and recovery, contextual download and recording actions, cancellation, and duplicate event reconciliation are not reachable from the app. Current local filtering and persistence tests are not evidence for these product outcomes.

Owner: B04 for Activity lifecycle and notification entry. Media-related events also require W01 through W04 and M01 through M04.

IMPL-195-004. Visible routes and shortcuts are placeholders for required screens.

Severity: missing required feature implementation.

The registry and More menu make Home, Categories, Multistream, History, Moderation, Settings, Accounts, and Watch reachable. ShellScreen renders only ActivityScreen and ActivityDetailScreen; otherwise it renders generic intros, preview actions, or NestedRouteState. See app-shell.tsx:286-375, 491-548. The user-visible controls navigate successfully but do not perform the outcomes named in their accessibility labels and route summaries. For example, a channel Activity destination opens watch/session-preview, whose text says playback did not restart automatically at app-shell.tsx:533-538.

Owner: B02 is the navigation foundation. The missing outcomes belong to their graph tickets, not B02 alone.

IMPL-195-005. All native capability operations are deliberately unsupported and have no product call sites.

Severity: missing required feature implementation, not a bridge parser defect.

Each Kotlin module returns NATIVE_OPERATION_UNSUPPORTED for every operation. See StreamFusionPlaybackModule.kt:10-18, StreamFusionMediaJobsModule.kt:10-18, StreamFusionCaptionsModule.kt:10-19, StreamFusionDiagnosticsModule.kt:10-17, and StreamFusionMaintenanceModule.kt:10-18. The only invoked operations are the safe development proof calls in android-capability-stub-proof.ts:41-53. Native-contract tests verify rejection containment and parser behavior. They do not verify a native product capability.

Owner: B05 owns the completed typed boundary. B06, W01, W02, W09, M01 through M04, M09, and R02 own the required behavior.

Rejected finding

The earlier startup-race candidate is rejected. requireProductStore awaits initializePromise ??= initialize() before it tests the ready state. See store-runtime.ts:233-239. A first Activity load therefore waits for initialization instead of failing only because initialization is in progress. This audit found no distinct reproducible Activity startup failure.

Test map and limits

The 11 test files are listed with their requirement areas in inventory.json. The five root Node tests cover the scaffold, native module registration, query-string compatibility, and Android command scripts. Six feature tests cover shell parsing and reducer behavior, storage policy, diagnostics composition, and native-contract parsing.

No test mounts AppShell or ActivityScreen. No test exercises a real Expo route, Android device, notification, player, chat connection, account flow, Settings panel, media job, caption session, update handoff, or mockup scenario. The persistence test detects the exact opposite of the required duplicate-read rule. These are missing tests when the corresponding behavior exists, and missing feature implementations where there is no app path to test.

Verification

node .audit/issue-195/implementation/inventory.mjs completed against the pinned tree. It produced inventory.json with 63 file records, 17 extracted Settings panels, and 40 extracted tab states. No Android, Metro, build, emulator, or process command ran.

[TheDarkSkyXD]

Normative PRD amendment: screen and control contract

User-requested update, 2026-09-07. This is the published companion to the expanded PRD. Feature owners implement this UI/UX before their issues close. Specification coverage is not implementation or runtime proof. The matching repository document has been updated locally; it is not yet committed because unrelated Desktop changes are in progress.

Mobile screen and control contract

This document is a normative companion to the mobile implementation specification. It defines the Android UI contract that feature issues must deliver before they close. It does not make the HTML prototype's sample accounts, measurements, option values, defaults, or status labels into product policy.

The source mockup is android-navigation-prototype.html. Run node docs/research/streamfusion-mobile/mobile-screen-and-control-contract-check.mjs to compare its declared screens, tabs, settings panels, and data-action names with this contract. At the current source revision, the check reports 34 screens, 40 tabs, 17 panels, and 25 actions.

Authority and delivery rule

The implementation specification and approved grilling decisions control business rules. This contract controls the required Android UI, interaction states, and navigation. Where the prototype conflicts with either, the later approved rule wins.

Each owning issue must include the complete UI and UX for its controls, transitions, accessibility labels, success state, loading state, empty state, failure state, permission state, and lifecycle state before closure. A feature cannot defer its screen or settings panel to a release milestone. Issue #195 verifies the cross-feature result. It does not postpone implementation that an owner issue already specifies.

The owner references below identify existing issue scopes. A shared control requires coordination among every listed owner. A reference does not create a new feature or change dependency order.

Shared shell and state rules

The shell has a top app bar, destination content, a movable mini-player only during active playback after navigation, a search dock when applicable, and five primary destinations: Search, Following, Watch, Activity, and More. There is no persistent currently-playing strip. The selected destination uses both a visual selected state and an accessible selected state. Nested routes show a back control that returns to their parent without losing the parent list position or selected tab.

Search, Following, category detail, channel detail, Watch, Video, Activity, Moderation, and Diagnostics use the tab sets in this document. A tab switch changes only that screen's selected tab. It must not silently start playback, mutate a remote provider, or discard an unsent local form.

Every actionable control has an accessible name, visible pressed, selected, disabled, and busy state where applicable. A control that starts work disables duplicate activation until the operation reaches a terminal state. A failed operation keeps the user input, states what failed without exposing a secret, and offers a retry when retry is safe. A success state names the result and the current destination.

Lists support these states when their data source applies:

• Loading. Show a bounded skeleton or progress state. Keep prior data visible as stale data when it is safe to do so.
• Empty. Explain why no rows exist and provide a route or action that can change the condition.
• Error. Show the failed source and a retry control. Preserve filters, query text, and selected tab.
• Offline. Mark cached data with its age. Remote mutations fail visibly unless their workflow has an approved idempotent retry contract.
• Partial provider result. Show the usable provider result and identify the unavailable provider without erasing usable rows.

Permission requests occur in context. Notification permission follows PRD 12.3. A denial leaves Activity available and exposes a settings retry path. Android installer permission states explain the capability, request platform access only after user intent, and show a recoverable denied state. Captions never request microphone permission. StreamFusion does not request broad storage permission.

On background, process death, reboot, and offline transitions, the UI follows PRD 10.3. In particular, restoring a route never silently restarts playback. The user must start playback again. Long-running media work shows its durable job state after restoration. Destructive local-data operations remain separate confirmed actions.

Screen hierarchy

The following routes are the complete prototype screen set. settings-<panel> is a route, not an inline overlay. The system route is the Diagnostics overview entry. Parentage specifies Back behavior.

Contract route	Label	Parent and required content	Existing owners
search	Search	Primary destination. Query, result-type tabs, platform filters, live-only filter, recent local searches, and results.	#130, #132, #133, #147, #149
home	Home	More. Combined discovery sections and provider-aware recovery states.	#130, #131, #132, #147, #148
categories	Categories	More. Browse games and topics. A row opens category detail.	#130, #132, #133, #147, #150
category-detail	Category detail	Categories or Search. Category identity, provider context, content tabs, filters, and paginated results.	#130, #132, #133, #147, #150
following	Following	Primary destination. Account and Guest Follow results with explicit sign-in and sync states.	#134, #147, #151
channel	Channel detail	Search, Home, Categories, Following, Activity, or notification route. Channel identity, live or ended state, follow state, and content tabs.	#130, #132, #133, #147, #148, #151
watch	Live stream viewer	Primary destination and deep destination. Player, channel context, selected audio owner, chat/info/related tabs, and safe playback errors.	#152, #153, #156, #157, #167
video	Video and clip viewer	Channel, Search, History, or deep destination. Player, media metadata, seek state, and details/comments/related tabs.	#133, #153, #154
multi	Multistream	More. Configured slots, measured active-limit feedback, audio ownership, degradation, and recovery.	#143, #160, #167
history	History	More. Durable local history with remove and clear confirmations. Reopening media does not autoplay after restoration.	#155
activity	Activity	Primary destination. Durable local notification and job inbox with read state, tab filters, and safe event routes.	#141, #151, #172, #173, #174
moderation-home	Managed channels	More. Eligible workspaces only, with clear account and provider eligibility states.	#159, #168
moderation	Moderation room	Managed channels. Channel identity, permissions, moderation tabs, confirmation, result, and provider-failure states.	#159, #168
settings	Settings	More. The 17 panels below, grouped by their declared section.	#167, #168, #170
accounts	Accounts	More. Connected account, guest mode, notification eligibility, connect, refresh, callback failure, and disconnect states.	#135, #145, #146, #151
system	Diagnostics	More. Diagnostics overview and an entry to the Diagnostics settings panel.	#143, #170, #171
more	More	Primary destination. Cards for Home, Categories, Multistream, History, Moderation, Accounts, Settings, and Diagnostics.	#139, #141

Settings routes

Contract route	Panel label	Parent and owner
settings-appearance	App and appearance	Settings. #167, #170
settings-playback	Playback	Settings. #152, #153, #154, #166, #167
settings-player-controls	Player controls	Settings. #153, #167
settings-buffer	Buffer	Settings. #152, #153, #167
settings-multiview	Multiview	Settings. #143, #160, #167
settings-notifications	Notifications	Settings. #141, #151, #169, #172, #173, #174
settings-chat	Chat	Settings. #156, #157, #158, #168
settings-predictions	Predictions	Settings. #156, #157, #168
settings-adblock	Ad blocking	Settings. #161, #169
settings-proxy	Proxy	Settings. #162, #169
settings-integrations	Integrations	Settings. #135, #145, #146, #168
settings-api-tokens	API and tokens	Settings. #135, #145, #146, #168
settings-updates	Updates	Settings. #170, #175, #176, #178
settings-diagnostics	Diagnostics	Settings. #143, #170, #171
settings-logs	Logs	Settings. #143, #170, #171
settings-report-bug	Report a bug	Settings. #170, #171
settings-about	About	Settings. #167, #170

Tab contract

Each tab is a labeled, keyboard-accessible tab with a matching tab panel. The first tab in each group is the initial UI selection only. It is not a policy default for data retention, playback, quality, notifications, or provider behavior.

Screen	Tabs	Required behavior
Search	All, Channels, Streams, Videos, Clips, Categories	Scope the same query and selected provider filters to the selected result kind.
Following	Live, Videos, Clips, Categories, Channels	Show only items the current guest or account follow source permits.
Category detail	Live, Clips, Videos	Keep category identity and filters. Videos must not include live streams.
Channel detail	Home, Videos, Clips	Keep the selected channel. An ended channel routes to a valid ended detail rather than a broken player.
Watch	Chat, Info, Related	Opening or closing Chat changes chat visibility. Chat disconnects when not visible under PRD 10.3.
Video	Details, Comments, Related	Keep the current media identity and playback position.
Activity	All, Channels, Jobs	Filter the durable inbox without changing read state.
Moderation	Chat, Retention, Mod log, Banned, Engagement, Unban, Moderators, VIPs	Enforce channel-specific provider permissions for each panel and action.
Diagnostics	Overview, Resources, I/O, Traces, Logs and reports, Developer tools	Show bounded, redacted local diagnostic data. Android does not expose arbitrary process control.

Page layout and control contract

The prototype supplies the following component order. Sample names, viewer counts, stream state, device state, and metrics are fixtures. Each route uses a vertical scroll container with the shell above it. A row is never the only representation of its content identity: live rows show channel, title, category, Platform, and live status; recorded rows show content type, title, channel, duration or position when known, and Platform.

Each prototype data-screen control is the assigned navigate:<route-id> action. It validates that the destination has the required typed identity before navigation. The source builders are searchScreen, homeScreen, categoriesScreen, categoryDetailScreen, followingScreen, channelScreen, watchScreen, videoScreen, multistreamScreen, historyScreen, activityScreen, moderationHomeScreen, moderationScreen, settingsScreen, accountsScreen, systemScreen, and moreScreen. Settings panel declarations are in settingsDefinitions and settingDetailScreen. Tab declarations are in tabReviewGroups. Toggle, choice, range, and field declarations are in settingToggle, settingChoice, settingRange, and settingField.

Search

Source anchors: searchScreen, searchResults, and searchHistory.

search renders, in order, a title, the local thumb-reachable Search dock or a focused field, result-type tabs, Platform and Live-only filters, a local-history heading and clear control, history rows, a result heading, and the selected result composition. All-results uses a best-match channel row, live stream cards, and category cards. Channels uses channel rows. Streams uses stream cards. Videos and Clips use recorded rows. Categories uses category cards.

submit-search, clear-search-field, and open-search-dock are assigned controls. They preserve the current query context and use the normal stale-request cancellation path. repeat-search, remove-search, clear-search-history, search-tab, search-platform, and toggle-live-only use the declared action contract. Search history rows contain a type marker, local-device source, repeat action, and remove action. The clear operation affects only search history.

Home

Source anchor: homeScreen.

home renders a title row with a Categories route action, then a Recommended live heading and a vertical stream-card feed. Each stream card has a 16:9 thumbnail, live and viewer metadata, title, channel avatar and name, category, Platform badge, and language tag. Activating the card routes to Watch with that stream identity.

open-categories is an assigned route action. Refresh, pagination, recommendation order, language tags, and provider recovery use the Home owner workflow. The prototype has no Home refresh button. A production refresh affordance needs an explicit owner decision and must not be represented by a fixture count.

Categories

Source anchor: categoriesScreen.

categories renders a title row, a Language button, then a grid of category cards. A category card contains 3:4 artwork, category name, and a compact live or viewer summary. open-category carries the selected category identity into category-detail.

The prototype renders Language without an action name or handler. category-language-filter is an assigned filter control. Its supported languages, whether it is single or multi-select, and its initial selection are unresolved. It remains visibly unavailable until #150 records that decision.

Category detail

Source anchor: categoryDetailScreen.

category-detail renders a category identity header with artwork, title, cross-Platform summary, and Follow control. It then renders category tabs, the ordered Platform, Language, Tags, and Sort filters, a result heading, and the selected content list. Live uses stream cards. Clips and Videos use recorded rows. The Videos tab must exclude live streams.

follow-category, category-platform-filter, category-language-filter, category-tags-filter, and category-sort are assigned controls. The prototype does not declare their handlers or option policy. #150 and the follow owner must define their permitted values, persistence, and provider support. Before then, a rendered button must show unavailable state rather than simulate a selection.

Following

Source anchor: followingScreen.

following renders a title row with Manage, Following tabs, ordered All, Live, Twitch, and Kick filter chips, then selected content. Live uses a notification-status notice followed by stream cards. Videos and Clips use recorded rows. Categories uses category cards. Channels uses channel rows that identify Guest Follow or account origin and notification state.

manage-follows, following-source-filter, and following-live-filter are assigned controls. They open the follow-management route or change only the visible source filter. The prototype does not settle the management sheet layout, filter defaults, or account-sync write behavior. #134, #147, and #151 own those decisions.

Channel detail

Source anchor: channelScreen.

channel renders a channel identity header with avatar, follower and Platform identity, Guest Follow or account relationship, and a Follow or Following control. It renders channel tabs, selected content, then an About card. Home renders current live or offline notice before recent broadcasts. Videos and Clips render recorded rows with their respective order label.

set-channel-follow is an assigned control. It follows PRD 18.3: account writes require an approved official path; otherwise the UI offers Guest Follow and an explicit provider-page action. open-channel-about is a read-only route or disclosure action. The prototype's Follow and Following labels do not prove provider mutation support.

Watch

Source anchors: watchScreen, videoStage, and chatPanel.

watch renders the player stage before the selected Chat, Info, or Related supporting sheet. Compact Watch uses closed, peek, and expanded sheet states. Only one supporting sheet or pane is active. A wide layout may place the selected sheet beside the player without losing the stream identity or playback state.

The player stage contains preview or video surface, live or media state, effective quality, channel identity, title, viewer or media metadata, and mute state. It requires play-pause, seek-back, seek-forward, set-quality, set-volume, toggle-mute, enter-fullscreen, enter-pip, and toggle-captions controls when the current media and capability support them. The prototype visibly renders only mute and a quality badge. The other named controls come from the approved player contract and must show unsupported or unavailable state where they do not apply. Player-controls Settings governs visibility only. It does not bypass capability policy.

The Info sheet renders channel and stream identity, Follow, Add to Multistream, Start recording, and local-caption status. set-channel-follow, add-multistream-slot, start-recording, and manage-local-captions are assigned controls. Recording opens a confirmation sheet that names foreground-service behavior and the active stream. Local captions opens model install, removal, unavailable, and resource-impact states. Captions use decoded program PCM only. They never request microphone permission, upload audio, or offer cloud fallback.

The Chat sheet renders a connection header, message list, composer, Send action, and close action. It also requires open-emote-picker and chat-message-action controls when the provider supports them. send-chat-message validates login, scope, message content, and current channel before one direct send. The prototype's "Message as Guest" placeholder does not authorize guest Twitch chat. Closed or hidden chat disconnects while playback remains. The list shows reconnect state and a gap marker after an unrecoverable replay gap. Message actions are provider-scoped and never notification actions or offline queued mutations.

The Related sheet renders a heading and recorded rows. Selecting one opens Video with its typed media identity. dismiss-player pauses or closes the current session before removing the movable mini-player. The mini-player appears only while active playback survives in-app navigation, never as a permanent strip, and is mutually exclusive with Android PiP.

Video and Clip viewer

Source anchor: videoScreen.

video renders a video surface, playback overlay, scrubber with current position and duration, channel and media identity row, Video tabs, then selected panel content. Details contains Download, Share, Save, and an About card. Comments contains a count, message list, composer, and Send action. Related contains typed recorded rows.

play-pause, seek-to-position, enter-fullscreen, set-quality, download-media, share-media, and save-media are assigned controls. Download creates a durable media job only after the user chooses it. Share uses an explicit Android destination and never presents incomplete output as complete. Save has no implied provider write until its owner records whether it means a local list, Guest Follow relation, or approved provider action. The prototype renders a comment composer, but no approved provider-comment workflow exists in this contract. send-video-comment remains disabled with an explanation until an owner approves a provider path.

Multistream

Source anchors: multistreamScreen and slot.

multi renders a title with configured-slot count and active-video count, Edit, a visible degradation notice when applicable, a six-slot grid, then recovery controls. Each slot has stream identity, thumbnail, active or paused mode, and audio-owner state. Selecting a capable active slot uses audio-owner.

edit-multistream, add-multistream-slot, remove-multistream-slot, reorder-multistream-slot, and set-multistream-mode are assigned controls. Edit opens a sheet with configured slots separate from active-video capacity. Add and reorder retain typed stream identity. Remove asks for confirmation if it ends active playback. Mode changes show the effective result after qualification. restore-slot and cool-device remain requests, not guarantees. The source has no handler for Edit or slot management, so #160 must complete the sheet and its validation before those controls ship.

History

Source anchor: historyScreen.

history renders a title row with Clear, then local history rows. Each row has a typed Stream, Video, or Clip marker, thumbnail, title, channel, Platform, watched time, and watched-progress indicator when progress exists. A Stream row opens Watch. A Video or Clip row opens Video. Reopening a row restores route and saved position where valid. It never silently resumes playback after process restoration.

clear-history, remove-history-row, and resume-history-item are assigned controls. Clear and remove use a confirmation sheet and affect only History. The prototype lacks per-row removal and progress UI. #155 must add both rather than treating the fixture rows as complete history behavior.

Activity

Source anchor: activityScreen.

activity renders a title row with unread count and Mark read, Activity tabs, then typed Activity rows. A row includes stable event identity, visual, title, timestamp, source or Platform, read state, and a current safe route. All combines channel, job, and system events. Channels and Jobs filter the same durable inbox.

mark-all-activity-read and open-activity-item are assigned controls. Opening an item may mark that item read after its route resolves. It does not reset other read state. An ended stream opens ended Channel or detail state. A malformed or stale destination fails safely. The prototype's Mark read control has no handler, so it is not evidence that bulk read is implemented.

Managed channels

Source anchor: moderationHomeScreen.

moderation-home renders a title, eligible managed-channel rows, a Global retention summary, and a Platform-permission notice. A row contains channel identity, Platform, current live or room status, and routes to its Moderation room. The page shows only workspaces for which the selected account has a supported moderation session.

select-managed-channel and open-global-retention are assigned controls. The latter opens the Retention tab for the selected scope. A missing scope, expired session, or unsupported provider renders an explanation rather than an editable room.

Moderation room

Source anchor: moderationScreen.

moderation renders a room title with selected channel and Platform, Switch channel, moderation tabs, then the selected panel. Chat contains current moderator-session state, typed message cards, Delete, Timeout, Ban, room-health controls, and Clear chat. Retention contains channel and global choice controls. Mod log contains filters and typed log rows. Banned contains typed rows and Unban. Engagement contains poll and prediction status with create actions. Unban contains request detail, Deny, Review log, and Approve. Moderators and VIPs contain typed membership rows and Remove.

The source leaves switch-managed-channel, remove-moderator, remove-vip, and moderation-log-filter without handlers. The assigned controls in the Moderation controls table define their minimum result. Each remote action opens the relevant confirmation or input sheet, validates current scope and channel authority, submits once, and reports success, rejection, rate limit, cancellation, or provider failure. None is queued offline.

Settings

Source anchors: settingsScreen, settingsDefinitions, and settingDetailScreen.

settings renders grouped panel cards in this order: App, Viewing, Experience, Accounts and network, then System and support. A card shows the panel label, summary, and route action. It does not expose a setting's sample state as the actual effective device or provider state. Each panel route returns to Settings without losing scroll position.

The individual panel layouts and controls are normative in Settings-control contract. Each inline field provides label, description, current safe value or state, validation feedback, and save result. Secret fields never prefill or reveal their stored value.

Accounts

Source anchor: accountsScreen.

accounts renders account rows for connected and guest mode, then Account notifications. Each row states connection mode, available features, and Platform identity. The notification area shows Live alerts and Moderation alerts as summaries of their authoritative preference and registration state. It must not render a local switch that claims delivery is enabled when Android permission, registration, or relay reconciliation has failed.

connect-account, manage-account, disconnect-account, account-live-alerts, and account-moderation-alerts are assigned controls. Connect opens the OAuth flow. Manage opens scopes, expiry, supported features, and refresh state without secret values. Disconnect requires confirmation and preserves unrelated Guest Follows, History, Activity, settings, and private media. Account alert controls route to the authoritative notification preference when a separate per-account preference exists. Their source buttons are otherwise unresolved mockup controls.

Diagnostics overview

Source anchors: systemScreen and diagnosticsTabContent.

system renders a Diagnostics title and Run check, a capability and device-health notice, Playback and chat status, then cards for device and media health, the latest diagnostic report, and accounts and notifications. run-check opens bounded progress and result state. Report Share routes to the redacted report review. The cards route to the Diagnostics, Logs, Report a bug, or Accounts settings panels as appropriate.

The Diagnostics settings tabs render these distinct content sets: Overview shows qualification, active-slot, storage, and degradation state; Resources shows bounded CPU and memory observations plus diagnostic-window; I/O shows bounded read and write observations plus diagnostic-io-window; Traces shows bounded redacted operation traces; Logs and reports shows report and runtime-log actions; Developer tools shows the Android-safe warning and diagnostic-detail. Android never exposes arbitrary process control, other-app inspection, or production logcat. Prototype metrics are fixtures, not qualification proof.

More

Source anchor: moreScreen.

more renders a title, then cards in this order: Home, Categories, Multistream, History, Moderation, Accounts, Settings, and Diagnostics. A card has an icon, label, concise purpose, and route action. More is the parent for all of these secondary routes. The account avatar in the app bar opens More. It does not skip directly to a hidden account page.

Sheets, confirmations, and lifecycle paths

Only one supporting sheet or pane is active in Watch. Android Back dismisses the nearest open sheet, then returns through route history, then leaves the task. The keyboard moves the local Search dock above it and does not obscure the active field or submit control.

Path	Required sheet or terminal path
OAuth and account connection	Show verification destination or callback waiting, cancel, expiry, denial, and retry. Commit account state only after validated credentials.
Notification enable	Explain the alert capability, request Android permission after explicit intent, preserve Activity after denial, then show registration and reconciliation state.
Download, recording, captions	Show destination or durable job intent, capacity or model requirement, progress, cancellation, failure, and recovery. Recording states foreground-service implications before start.
Multistream edit	Show configured slots, active capability result, add, remove, reorder, and mode actions. Preserve configured slots when active capacity is lower.
Destructive local action	Name the exact affected data, give Cancel and confirm, and report completion or failure. Clear history, remove media, disconnect accounts, and reset app are separate paths.
Remote moderation action	Show selected channel, user or message, scope, and any required input before one submission. Show provider result or safe retry state.
Update install	Show validation result, download progress, cancellation, storage error, rejected artifact, and explicit Android PackageInstaller consent.

Action contract

The mockup declares these 25 data-action values. When a feature implements or claims an action, it maps the action to the stated effect, exposes busy and terminal feedback, and records no secret in UI state or logs. This declaration inventory does not prove that a native workflow exists or is complete.

Action	Effect and terminal behavior	Owners
activity-tab	Select the requested Activity tab. Invalid values retain the current tab.	#141, #151
audio-owner	Make the selected eligible active Multistream slot the one audio owner. Reject an unavailable slot with an explanation.	#143, #160
category-tab	Select the requested category tab and retain category identity.	#130, #150
channel-tab	Select the requested channel tab and retain channel identity.	#130, #151
clear-search-history	Ask for confirmation, then remove only local search history. Report success or failure.	#149, #170
cool-device	Re-evaluate device capability after a user signals recovery. The measurement, thresholds, and hysteresis remain unresolved. Do not promote suspended streams solely from this signal.	#143, #160
cycle-setting	Change one enumerated setting to the next allowed value after validation, persist it, and announce the new value. The prototype option lists are not approved value sets unless an owner issue says so.	owning settings issue
diagnostics-tab	Select the requested Diagnostics tab. Invalid values retain the current tab.	#143, #171
dismiss-player	Pause or close the existing playback session, then dismiss the mini-player. It must not leave hidden audible playback.	#152, #153
following-tab	Select the requested Following tab and retain guest or account context.	#134, #151
moderation-tab	Select the requested moderation tab after eligibility checks. Show an unavailable state when the account lacks permission.	#159, #168
open-category	Navigate to category detail with the selected category identity.	#130, #150
remove-search	Remove one local search-history entry. Do not change remote search results.	#149
repeat-search	Put the selected saved query into Search and submit it through the normal query workflow.	#149
restore-slot	Request restoration of one configured Multistream slot. Capability qualification may decline the request and must explain why.	#143, #160
run-check	Start a bounded diagnostics qualification or collection run. Show progress, result, artifacts, and retry eligibility.	#143, #171
search	Focus the visible Search input or navigate to Search and focus it. It does not add a sixth primary destination.	#139, #149
search-platform	Select All, Twitch, or Kick as a query filter. A provider failure remains visible after selection.	#132, #149
search-tab	Select the requested Search result type.	#132, #149
toggle-chat	Open or close Watch chat. Closing disconnects chat when it is not visible.	#156, #157
toggle-density	Toggle the explicit compact-chat-density preference, persist it, and update the visible message spacing.	#167, #168
toggle-live-only	Add or remove the live-only Search filter and refresh the current result set.	#132, #149
toggle-setting	Toggle one boolean setting after validation, persist it, and show an unavailable reason when the capability cannot take effect.	owning settings issue
video-tab	Select the requested Video tab and retain media identity.	#154
watch-tab	Select the requested Watch tab and apply chat visibility lifecycle behavior.	#152, #156

The prototype shows Manage, Connect, Check now, Build report, Share, Open, and local-data controls without data-action names. This contract assigns the required typed actions below. A visible button with no reachable workflow is not an implementation.

Settings-control contract

Every setting and supporting action has a stable ID, visible label, value presentation, terminal result, and unavailable state. A setting change validates at the boundary. If a requested preference cannot take effect on the current provider or device, retain the preference only when the owner workflow supports deferred application, then explain the current effective state. Otherwise reject the change without overwriting the saved value.

The prototype supplies keys for toggles, choices, and ranges. This document assigns IDs to its unlabeled field controls. Assigned IDs are marked assigned. Numeric bounds, choice lists, initial values, and sample text in the prototype are examples only until the owning issue records approved values and validation rules.

App and appearance

ID and label	Control and required behavior
theme Theme	Choice. Apply the selected supported Android theme and persist the preference. Supported values and fallback policy are unresolved.
density Content density	Choice. Apply list, chat, and control spacing without changing content order.
language Language	Choice. Change the app interface language after available translation resources load. The supported locale list is unresolved.
restore-session Restore last session	Toggle. Restore a valid prior route and its local UI state after process restart. Do not restore playback.
resume-playback Resume playback	Toggle. This must never cause silent restart. Any user-confirmed resumption flow and metered-network behavior remain unresolved.

Playback

ID and label	Control and required behavior
quality Default quality	Choice. Request the preferred quality when the provider offers it. Show the effective quality and a provider fallback.
carousel Featured carousel timing	Range. Change the local discovery carousel interval. Bounds and default are unresolved.
captions Local captions	Toggle. Enable local captions only when a required model and compatible playback session are available. Route to model setup or show a recoverable unavailable state.
token-player Access-token player type	Choice. Select an eligible player-token strategy. Provider eligibility and values belong to #161 and #169.
hevc Allow HEVC (H.265)	Toggle. Allow a compatible HEVC stream. Show the effective codec and fallback reason.
stream-device-id Stream device ID assigned	Protected field. Display only a safe identifier state. Never expose a credential. Regeneration and override policy are unresolved.

Player controls

ID and label	Control and required behavior
control-0 Quality	Toggle visibility of the applicable player Quality control.
control-1 Playback speed	Toggle visibility of the applicable player Playback speed control.
control-2 Volume	Toggle visibility of the applicable player Volume control.
control-3 Fullscreen	Toggle visibility of the applicable player Fullscreen control.
control-4 Theater	Toggle visibility of the applicable player Theater control.
control-5 Video Stats	Toggle visibility of the applicable player Video Stats control.
rewind Rewind	Choice. Select the approved backwards seek interval for Video and Clip playback.
fast-forward Fast forward	Choice. Select the approved forwards seek interval for Video and Clip playback.

Buffer

ID and label	Control and required behavior
low-latency Low-latency mode	Toggle. Request live-edge tracking. Show when provider, network, or device safety limits override it.
target-latency Target live latency	Range. Set the requested segment distance behind the live edge. Bounds and capability interaction are unresolved.
forward-buffer Forward buffer	Range. Set the requested ahead-of-playback buffer. Bounds and memory policy are unresolved.
max-buffer Maximum buffer	Range. Set the requested buffer cap. The runtime must show an effective lower cap when safety rules require it.

Multiview

ID and label	Control and required behavior
multiview-cap Maximum concurrent Streams	Range. Limit configured slots. The measured active video limit can be lower while retaining configured slots. Exact thresholds and hysteresis remain unresolved.
background-quality Background-Stream quality	Choice. Request quality behavior for non-focused slots. Show effective state after device and provider qualification.

Notifications

ID and label	Control and required behavior
android-notifications Android notifications	Toggle remote Android delivery. On first enable, request permission in context. Denial leaves Activity active and shows a retry path.
live-activity Live Notification history	Toggle durable Activity creation for eligible live events. It does not grant Android notification permission.
toast In-app banners	Toggle foreground in-app banners. Activity writes remain independent.
sound Sound	Toggle notification sound for eligible delivered alerts. Respect Android channel settings.
notify-twitch Twitch	Toggle eligible Twitch live-alert coverage.
notify-kick Kick	Toggle eligible Kick live-alert coverage.
notify-guest Guest Follow notifications	Toggle eligible Guest Follow alert coverage without creating account ownership.
favorites-only Favorites only	Toggle restriction to selected followed channels. The selection source is unresolved.
restart-grace Restart grace	Choice. Set the approved duplicate or restart-alert cooldown. Exact values are unresolved.

Chat and predictions

ID and label	Control and required behavior
chat-font Font size	Range. Apply message-text size while preserving accessibility scaling.
emote-size Emote size	Range. Apply rendered emote size without overflow or hidden controls.
chat-density Message density	Choice. Apply vertical message spacing.
bttv BetterTTV	Toggle provider-supported BetterTTV emotes. Show unavailable asset or provider state.
ffz FrankerFaceZ	Toggle provider-supported FrankerFaceZ emotes. Show unavailable asset or provider state.
seventv 7TV	Toggle provider-supported 7TV emotes. Show unavailable asset or provider state.
message-limit Message limit	Range. Bound the locally retained in-memory chat window. It does not create a durable hosted chat transcript. The approved reconnect gap-marker rule remains in effect. Exact bounds are unresolved.
chat-polls Polls	Toggle display of eligible poll events.
chat-predictions Predictions	Toggle display of eligible prediction events.
deleted-messages Deletion notices	Toggle display of eligible deletion and chat-clear events.
prediction-style Style	Choice. Select the approved prediction-card presentation. It must not change provider settlement or moderation rules.

Ad blocking and proxy

ID and label	Control and required behavior
adblock Enable ad blocking	Toggle provider-specific eligible ad-block handling. It must state unsupported-provider and fallback behavior.
adblock-method Method	Choice. Choose an approved token strategy. Values and availability belong to #161 and #169.
proxy-enabled Enable proxy	Toggle selected eligible request classes through a validated proxy configuration.
proxy-host Host assigned	Text field. Validate hostname or IP address before saving. Do not attempt a connection until the user chooses a connection workflow.
proxy-port Port assigned	Numeric field. Validate the port range before saving.
proxy-username Username assigned	Protected text field. Save through the approved credential boundary when credentials are supported.
proxy-password Password assigned	Secret field. Mask input and save only through the native credential adapter. Never render, log, or export the value.
proxy-token Playback access token	Toggle whether eligible token requests use the proxy.
proxy-master Multivariant playlist	Toggle whether eligible master-playlist requests use the proxy.
proxy-media Media playlist	Toggle whether eligible media-playlist requests use the proxy.

Accounts and API status

ID and label	Control and required behavior
integration-manage Manage assigned	Action. Open the connected account's management view. It shows account, scopes, supported features, refresh result, and disconnect action without exposing token values.
integration-connect Connect assigned	Action. Start the supported platform OAuth flow with cancel, callback failure, and account-selection states.
api-token-status Token status assigned	Read-only status. Show provider connection, expiry state, and scopes. Never show a token, refresh token, or secret.

Updates

ID and label	Control and required behavior
update-status Current version assigned	Read-only status. Show installed version and whether a checked stable release is available, invalid, unavailable, or rejected.
check-for-updates Check now assigned	Action. Check only the latest stable GitHub release. Validate schema, application ID, monotonic version, expected signer, and APK digest before offering a resumable app-private download. Native code revalidates the completed artifact. Android PackageInstaller always requires explicit user action.
automatic-foreground-update-checks Check automatically while foregrounded assigned	Toggle. Permit optional automatic checks only while the app is foregrounded. When enabled, automatic checks run no more than once per 24 hours. They do not block startup.

The prototype's prerelease, startup-updates, and update-frequency controls are superseded and must not ship. PRD 13.4 permits a manual stable-release check and optional automatic foreground checks no more than once per 24 hours. There is no prerelease channel, hourly cadence, daily or weekly user cadence, or background startup check. This rule is owned by #170, #175, #176, and #178.

Diagnostics, logs, report, and about

ID and label	Control and required behavior
diagnostic-window Observation window	Range. Set the bounded current-session resources observation interval. Exact permitted values are unresolved.
diagnostic-io-window Observation window	Choice. Set the bounded current-session I/O observation interval. Exact permitted values are unresolved.
diagnostic-detail Detailed collection	Toggle bounded selected-subject detail. Android never offers arbitrary process control.
log-level Minimum level	Choice. Filter visible local log entries. It does not change redaction rules.
log-source Source	Choice. Filter visible local log entries by source.
report-description What happened? assigned	Text field. Keep the user's report locally until Build report or explicit discard.
attach-logs Attach redacted logs	Toggle inclusion of redacted logs. The report preview must show that redaction ran.
attach-profile Attach Capability Profile	Toggle inclusion of the Capability Profile and runtime-degradation state.
build-report Build report assigned	Action. Build a local diagnostic report. It uploads nothing automatically. Show report contents, redaction result, output state, and safe share or export action.
share-diagnostic-report Share assigned	Action. Open Android sharing only after the user reviews the redacted report artifact. Report an unavailable share target without losing the artifact.
open-runtime-logs Open assigned	Action. Open the filtered, redacted local runtime-log view. It must not expose production logcat, credentials, or private provider content.
open-source-licenses Open-source licenses assigned	Route to bundled license notices. It works offline.
privacy Privacy assigned	Route to the app privacy notice. It identifies local and remote data handling.
clear-history Clear history assigned	Separate destructive action. Confirm, remove only History, then report result.
remove-media Remove media assigned	Separate destructive action. Select media, confirm, remove only selected app-private media, then report result.
disconnect-accounts Disconnect accounts assigned	Separate destructive action. Confirm each account, revoke or remove local credentials as supported, then report result.
reset-app Reset the app assigned	Separate destructive action. Confirm after explaining Product Store, cache, credentials, and recoverable media handling. Follow PRD 10.2.

Moderation controls

ID and label	Control and required behavior
channel-retention Channel retention	Choice. Set one managed channel's moderation-log retention override after permission and provider validation. Approved values and retention limits are unresolved.
global-retention All managed Channels	Choice. Set the default moderation-log retention used only when a channel has no override. Approved values and retention limits are unresolved.
delete-message Delete assigned	Action. Confirm when policy requires, delete only the selected eligible message, and show the provider result.
timeout-user Timeout assigned	Action. Collect an approved duration, validate authority, submit once, and show the provider result.
ban-user Ban assigned	Action. Confirm the selected eligible user and scope, submit once, and show the provider result.
set-slow-mode Slow mode assigned	Action. Change eligible channel slow-mode state after scope validation and show the effective value.
set-followers-mode Followers assigned	Action. Change eligible channel follower-only mode after scope validation and show the effective value.
clear-chat Clear chat assigned	Destructive action. Confirm the selected eligible channel, submit once, and show the provider result.
moderation-log-filter Mod log filter assigned	Filter the local visible moderation-log view without mutating provider data.
unban-user Unban assigned	Action. Confirm the selected eligible banned user, submit once, and show the provider result.
create-poll New poll assigned	Action. Collect valid poll input and submit only when the provider and account permit it.
create-prediction New prediction assigned	Action. Collect valid prediction input and submit only when the provider and account permit it.
deny-unban-request Deny assigned	Action. Confirm and record the eligible unban-request decision.
review-unban-log Review log assigned	Route to the selected requester's relevant moderation history.
approve-unban-request Approve assigned	Action. Confirm and submit the eligible approval once.
switch-managed-channel Switch assigned	Action. Open the eligible managed-channel selector and retain the current room until the user chooses another channel.
remove-moderator Remove moderator assigned	Destructive action. Confirm the selected eligible membership and show the provider result.
remove-vip Remove VIP assigned	Destructive action. Confirm the selected eligible membership and show the provider result.

All Moderation controls belong to #159 and #168. They have permission-denied, signed-out, unsupported-provider, busy, result, retry, and provider-failure states. The prototype's sample durations, retention values, users, and messages are not approved policy.

Screen-specific state obligations

Search cancels stale requests when query, tab, or platform changes. It keeps the latest query visible. Search history is local, bounded, and independently clearable.

Discovery, categories, and Following preserve usable provider results when another provider fails. Sign-in availability, Guest Follow availability, account-sync status, and pagination errors must be distinct states.

Watch and Video show loading, live or VOD state, ended or unavailable state, recovery state, and user-visible quality or codec fallback. PiP and fullscreen transitions retain the selected item and do not duplicate playback. Chat reports connection, reconnect, gap-marker, send-eligibility, and failure state.

Multistream retains configured slots when qualification reduces active playback. It shows the selected audio owner, every paused or degraded slot, the reason, and a safe recovery action. The user cannot infer hardware qualification from prototype sample counts or labels.

Activity preserves event identity, timestamp, delivery source, read state, and relevant channel or job route across restart. Duplicate delivery must not create a duplicate entry or reset an item from read to unread.

Diagnostics reports live device and job evidence with collection age and redaction result. A successful check must identify what it measured. A failed check must retain bounded failure evidence. A diagnostic card is not proof that a capability is qualified unless its owner issue provides the required measured evidence.

Prototype linkage and unresolved decisions

The mockup supplies layout, labels, navigation IDs, tab IDs, settings keys, and action names. It does not approve any sample account, selected provider, numerical limit, timer value, option list, default value, media state, device metric, status claim, or test result.

These decisions remain open and must be recorded by their owners before implementation claims completion:

• Capability qualification thresholds, duration, hysteresis, and recovery policy for Multistream and diagnostics. B06: Measure Capability Profile and apply Runtime Degradation #143 and W09: Deliver capability-aware Multistream #160.
• Supported settings option sets, numeric ranges, defaults, migrations, and reset behavior where this document marks them unresolved. The panel owner and M05: Deliver appearance and player Settings #167, M06: Deliver chat and integration Settings #168, or M08: Deliver update, support, and maintenance Settings #170 as applicable.
• The user-confirmed resume flow after route restoration. It must remain compatible with PRD 10.3's no-silent-playback rule. W01: Resolve and watch one live Stream #152, W02: Deliver player controls, movable mini-player, and Android PiP #153, and W04: Deliver typed Watch History #155.
• Favorites selection semantics, notification restart cooldown values, and supported notification combinations. B04: Deliver Activity, deep links, and lifecycle restoration #141, D08: Deliver Following and Guest Follows #151, N01: Register native FCM delivery and present notifications #172, N02: Deliver scalable topic and direct-token fanout #173, and N03: Prove notification scale and lifecycle recovery #174.
• Proxy connection-test workflow and provider request eligibility. W11: Deliver proxy and connectivity behavior #162 and M07: Deliver notification and network Settings #169.

This contract deliberately rejects stale update mockup behavior. It does not treat a prototype's appearance as authorization to implement a product rule.

[TheDarkSkyXD]

Normative PRD amendment, part 1 of 2

User-requested update, 2026-09-07. This supersedes the underspecified PRD sections below for feature implementation. Part 2 continues with lifecycle, release constraints, source decisions and explicit remaining questions. No release or application implementation is authorized by this documentation change.

StreamFusion Mobile implementation specification

Status: Baseline approved in GitHub issue #107. Expanded on 2026-09-07 at the user's request under #195 to make mockup, interaction, and grilling coverage explicit. Specification coverage does not mean implementation or verification is complete.

Target: Android 11 and newer

Distribution: Signed APK through immutable GitHub Releases

1. Purpose

StreamFusion Mobile is the Android companion to the existing Desktop application. It must deliver the same user outcomes as Desktop while using Android-native interaction, lifecycle, storage, media, security, and release behavior.

This document is the integrated implementation contract. It combines the approved parity policy, shared-core extraction, Android architecture, Platform boundaries, navigation, persistence, background behavior, native capabilities, notification delivery, verification, signing, and release model. After approval, implementation tickets must preserve these decisions unless a later explicit decision supersedes them.

The screen and control contract is a normative part of this PRD, not optional research or a release-stage design backlog. Read it with sections 6, 18, and 19 before implementing any feature. It supplies the screen hierarchy, component inventory, individual controls, interaction outcomes, states, and ownership that the capability summary alone cannot express.

The words must, must not, should, and may are normative.

2. Source of truth and conflict order

Implementation must resolve conflicts in this order:

1. A later explicit user decision or approved GitHub decision that supersedes an earlier decision.
2. The generated Desktop parity ledger at the implementation commit, for required user outcomes subject to approved Android adaptations.
3. This specification and its normative screen and control contract.
4. The linked research and design documents.

The ledger discovers required outcomes. It does not make an implementation defect or an unapproved Desktop mechanism a Mobile requirement. Prototype B and its approved amendments define visual structure and interaction placement. Prototype fixtures, fake service responses, review tools, and arbitrary sample settings are not proof of an approved business rule. Section 18 records superseded decisions. Section 19 records unresolved details without inventing approval.

The parity ledger is generated from Desktop behavior. It is not a manually frozen checklist. A Desktop capability added or materially changed after this document is approved creates an Android parity obligation before the next public Android release.

The notification design in section 12 supersedes earlier references to the Expo Push Service. The app uses expo-notifications, but the Integration Relay sends directly through FCM HTTP v1 to native Android tokens and topics.

3. Product boundary

3.1 Included

• One Android application built with Expo and React Native.
• Twitch and Kick discovery, accounts, viewing, chat, moderation, media, settings, diagnostics, and release behavior corresponding to the 24 Desktop capability contracts.
• A portable shared core consumed by Desktop, Android, and trusted services.
• The existing token-only Kick OAuth Worker.
• A separate Integration Relay for signed-out official reads, provider webhooks, foreground Kick chat fanout, signed capability policy delivery, and Android push.
• Device-local encrypted product state, bounded cache state, and app-private media.
• Native Android services or modules where JavaScript-only execution cannot satisfy the contract.

3.2 Excluded from 1.0

• iOS, Android TV, ChromeOS-specific support, Android Auto, Wear OS, 32-bit Android, and public x86 Android builds.
• Google Play distribution, mandatory updates, and production EAS Update delivery.
• Cloud synchronization of settings, history, downloads, recordings, or Guest Follows.
• Firebase products other than FCM registration and delivery.
• A general StreamFusion account, general provider proxy, server-side user credential store, or hosted chat-history archive.
• Guaranteed per-device push receipt.

4. Continuous parity contract

Every Desktop capability must have one Android parity record with these fields:

• stable Desktop capability ID;
• Desktop outcome and current evidence anchors;
• Android outcome and adaptation class;
• implementation owner and state;
• required automated, emulator, physical-device, live-provider, and human evidence;
• current evidence IDs and expiry;
• blocking reason when not release-ready.

The allowed adaptation classes are:

• Equivalent: the Android interaction differs, but the user outcome is the same;
• Android-native: Android supplies a better native expression of the same outcome;
• Compatibility Integration: a parity-critical outcome uses an isolated, non-public provider contract under the policy in section 11;
• Unavailable: allowed only when an approved capability decision permits it. A required unavailable outcome blocks release.

Parity status is computed from the generated ledger and evidence catalog. Documentation claims cannot override a failed predicate. Temporary development exceptions must identify an owner, reason, expiry, and affected capability. An exception or quarantined test blocks public release.

5. Capability placement

The current Desktop baseline contains 24 top-level capability contracts. The generated ledger remains authoritative for their detailed facts.

Capability ID	Required Android outcome	Primary placement and mechanism
home-live-discovery	Browse live streams, channel cards, and Platform availability.	Home under More; cards use 16:9 thumbnails, channel avatars, Platform badges, live state, and viewer metadata.
followed-streams-and-sync	View followed live channels, maintain Guest Follows, and import provider follows where supported.	Following tab with bottom floating search. Account follow writes become Guest Follow plus provider-page action when no official write API exists.
category-discovery	Browse categories and the streams, videos, and clips within a selected category.	Categories under More; 3:4 art opens Category Detail. Both screens use a bottom floating search field and every approved tab state.
search	Search channels, streams, videos, clips, and categories across Platforms.	Search tab with history, filters, bottom floating field, and All, Channels, Streams, Videos, Clips, and Categories tabs.
platform-account-auth	Connect, validate, refresh, scope-check, and disconnect Twitch and Kick.	Accounts in More and Settings. Twitch uses Device Code. Kick uses browser PKCE, a verified App Link, and the token-only Worker.
live-playback	Resolve and play Twitch and Kick live streams with visible compatibility state.	Watch tab, native player adapter, and isolated Platform playback-source adapters.
vod-and-clip-playback	Open and play videos and clips with correct metadata and history typing.	Watch routes launched from Search, Category Detail, History, and channel content tabs.
player-controls-and-pip	Provide transport, quality, volume, fullscreen, orientation, movable mini-player, and Android PiP.	Watch; in-app movable mini-player during navigation and system PiP when leaving the app.
stream-recording	Record supported playback into a recoverable, segmented local media job.	Contextual Watch action; job progress and results appear in Activity and Android notifications.
local-captions	Produce one real-time local caption session without uploading microphone or playback audio.	Watch overlay backed by a native caption module and visible resource state.
ad-blocking	Apply the approved Desktop-equivalent playback filtering outcome where technically available.	Playback-source and player adapters, never screen code; failure degrades only playback and is surfaced in Watch diagnostics.
live-chat	Receive and send live chat, show badges and emotes, and preserve focused-stream behavior.	Watch chat surface. Twitch uses foreground EventSub and direct Helix send. Kick receive uses the relay; send is direct official API.
emotes-and-cosmetics	Resolve Platform and approved third-party emotes, badges, paints, and display metadata.	Chat rendering and settings, backed by shared models and bounded caches.
chat-replay	Show synchronized replay where a validated source exists.	Video or clip Watch route. Compatibility sources are isolated and fail only this capability.
moderation	Execute authorized moderation, polls, predictions, pins, and managed-channel workflows.	Moderation under More, contextual chat actions, and all child tab states. Official endpoints are preferred; approved gaps follow section 11.
multistream	Configure and watch multiple simultaneous StreamSlots with one focused audio and chat context.	Multistream entry under More opens Watch. Up to six slots may be configured; the capability profile controls active video count.
watch-history	Record and browse watched items with an explicit Stream, Video, or Clip type.	History under More. Rows include thumbnail, avatar, Platform, type, timestamp, progress where applicable, and resume or replay action.
downloads	Download supported videos or clips, inspect progress, retry, cancel, delete, and explicitly export.	Contextual Watch action; active and completed jobs appear in Activity. There is no standalone Downloads or Media Library screen.
general-chat-and-theme-preferences	Configure appearance, chat behavior, playback behavior, and related preferences.	Settings under More, using the complete Desktop-derived settings panel set and Android-native controls.
proxy-and-connectivity	Configure supported proxy and network behavior and explain active restrictions.	Settings and Diagnostics. Network adapters own application; screens only present state and actions.
notifications	Configure live alerts and receive reconciled Activity events in foreground, background, and terminated cases allowed by Android.	Activity tab, notification settings, expo-notifications, native FCM tokens, and Integration Relay delivery.
app-updates	Check, validate, download, and hand a newer signed APK to Android's installer with user consent.	Settings and update prompt backed by the native updater module and GitHub Release metadata.
diagnostics-logs-and-bug-reports	Inspect status, logs, capabilities, storage, network, jobs, and sanitized reports.	Diagnostics under More with all six approved tabs and Android-native collection.
app-shell-and-navigation	Reach every capability through a stable Android-native shell without persistent Desktop chrome.	Five top-level destinations: Search, Following, Watch, Activity, More; adaptive navigation rail on wider windows.

6. Navigation and visual contract

6.1 Top-level shell

The compact Android shell has exactly five static destinations:

1. Search
2. Following
3. Watch
4. Activity
5. More

Phones use bottom navigation. Wider tablet and unfolded layouts use an adaptive navigation rail while preserving the same destinations, state, and route identity. Home is not a bottom destination. It is the first entry in More, followed by Categories, Multistream, History, Moderation, Settings, Diagnostics, and Accounts or Maintenance.

There is no persistent branded footer, currently-playing strip, or other bottom element on every screen. Active viewing is represented by the movable mini-player, the Watch destination, or Android PiP.

6.2 Search behavior

The main Search screen includes recent search history, Platform and content filters, and the All, Channels, Streams, Videos, Clips, and Categories result tabs. Search fields on Search, Categories, Category Detail, Following, managed-channel surfaces, and Settings float above content at the bottom of the current screen. They must account for keyboard and safe-area insets and must not hide the final result row.

The bottom field expands in place, exposes clear and submit actions, preserves the current filter context, and can be dismissed without losing the current result set. It is a local overlay, not a sixth navigation destination.

6.3 Content identity

• Channel and creator surfaces show avatars.
• Stream, video, and clip rows show 16:9 thumbnails.
• Category rows show 3:4 category artwork.
• Platform, live state, duration or viewer count, and content type remain visible where they disambiguate an item.
• Selecting a category opens that category's detail route rather than applying an invisible filter.
• History identifies every entry as Stream, Video, or Clip.

6.4 Watch and mini-player

Watch supports live streams, videos, clips, chat, and multistream layouts. When the user navigates within StreamFusion while media is playing, the player may collapse into a movable in-app mini-player. The user can drag it among safe snap regions, expand it back to Watch, pause or close it, and navigate without restarting playback.

When the app leaves the foreground and the user permits it, a single focused stream may enter Android Picture-in-Picture. The in-app mini-player and Android PiP are mutually exclusive representations of the same playback session.

6.5 Settings, diagnostics, and tabs

The implementation must expose all 17 settings panels: Appearance, Playback, Notifications, Player controls, Buffer, Multiview, Chat, Ad blocking, Proxy, Predictions, Integrations, API tokens, Updates, Diagnostics, Logs, Report a bug, and About.

It must also expose these 40 directly testable tab states:

• Search: All, Channels, Streams, Videos, Clips, Categories.
• Following: Live, Videos, Clips, Categories, Channels.
• Category Detail: Live Streams, Clips, Videos.
• Channel Detail: Home, Videos, Clips.
• Watch: Chat, Info, Related.
• Video or Clip: Details, Comments, Related.
• Activity: All, Channels, Jobs.
• Moderation: Chat, Retention, Mod log, Banned, Engagement, Unban, Moderators, VIPs.
• Diagnostics: Overview, Resources, I/O, Traces, Logs and reports, Developer tools.

Tabs may be adapted into native segmented controls, top tabs, or nested routes, but no content state may disappear. Each state requires a stable test selector or routeable review scenario. The generated parity ledger and navigation inventory together define completeness.

6.6 Design system

Mobile uses the existing Dark Theater design language in DESIGN.md: Void Black and tonal surfaces establish depth, Storm Crimson is reserved for live and critical states, and Twitch Purple or Kick Green identify only their Platforms. Resting surfaces have no shadows. Touch targets are at least 48 dp. Text and controls meet WCAG AA contrast, support 200 percent font scaling, TalkBack, reduced motion, and Android system insets.

6.7 Feature-owned UI and UX completion

Every issue that implements or changes a feature must deliver that feature's complete UI and UX together with its domain behavior, adapters, persistence, and tests. UI implementation is not deferred to #195, parity closure, Candidate Gate, or a release issue. The same rule applies to account flows, settings, notifications, diagnostics, media controls, and user-visible failures in native or relay-backed work.

Each feature issue must satisfy these acceptance criteria before closure:

• Name its PRD requirements, mockup screens, tabs, components, control IDs, and source decisions. Identify reused components and all affected screen usages.
• Deliver the approved visual hierarchy, information density, content identity, layout, typography, spacing, iconography, and Android adaptations. A route summary, placeholder, mocked service response, or inert control does not satisfy the feature.
• Implement every applicable action from entry to visible result, including validation, permission or scope checks, persistence, cancellation, retry, failure containment, and recovery. Buttons and native or background entry points use the same rules.
• Complete applicable loading, refreshing, empty, partial, stale, offline, failed, permission-denied, signed-out, expired-session, unsupported, constrained, disabled, and busy states. State why a listed condition does not apply instead of omitting it.
• Verify safe areas, portrait primary navigation, keyboard avoidance, floating-search clearance, overlay stacking, final-row reachability, large text, missing artwork, and supported resizing. Wider layouts must not replace or turn the portrait shell sideways.
• Meet the accessibility rules in section 6.6 in the actual feature, including semantic roles, labels, selected and disabled state, focus order, and non-color status cues.
• Add behavior and component regressions for the feature and exercise the real Android journey using literal root npm start, option 3, and Mobile MCP. Use Expo Go only for supported behavior and the matching development client for custom native capabilities. Record the source and tested artifact.
• Attach reference-versus-app screenshots at matched viewport and configuration, observed action and recovery results, and applicable accessibility and lifecycle evidence. Screenshots alone do not prove behavior.
• Record specified, implemented, and verified status independently. Missing required evidence or an unresolved rule keeps the affected acceptance item open.

Pure infrastructure and behavior-preserving extraction issues do not invent product screens. They must identify their actual consumer, verify any changed existing UI, and cite why no new UI applies. A feature cannot use this exception merely because its first implementation is a backend or native module.

Shared components are implemented when the first feature needs them and verified in their real usages. Later consumers own integration and regressions. Cross-feature dependencies name the missing integration explicitly; linking another ticket never turns unfinished behavior into a completed feature.

6.8 Continuous consistency review

Issue #195 starts with the specification and inventory and continues during feature implementation. It reviews completed feature slices for cross-screen consistency, missing contracts, and regressions. The feature owner fixes the feature's UI and UX before closing that feature issue. #195 is not a later batch that builds all pages after their feature tickets close.

Each milestone ends with complete UI and interactions for its delivered features. The integrated UI and UX review must finish before production artifact promotion in #178. Release work revalidates the completed experience against the exact APK; it does not implement missing pages. Publisher identity setup and verification tooling may proceed independently, but they do not waive this completion rule. The updater's own UI is feature work owned by #176 and must be complete before promotion.

The screen and control contract defines the current 34 prototype screen entries, 17 Settings panels, and 40 tab states. Its 65 review scenarios are derived from those overlapping inventories, not 65 separate features. Every approved addition updates the inventory and its feature issue before closure.

6.9 Action and state record

Each control or non-UI event has a stable requirement ID linked to its owner. Its acceptance record identifies actor, trigger, input, validation, permission, precondition, transition, side effect, persistence owner, visible result, cancellation, failure, retry, and evidence. A display-only component links to the data, formatting, content identity, and accessibility rules it presents.

Tests cover repeated taps, duplicate or out-of-order events, stale requests, concurrent commands, account changes, permission revocation, backgrounding, process death, and restoration where applicable. Read-only requests may be superseded. A stale response must not overwrite a newer query, account, selected channel, or slot. A canceled destructive action has no side effect. A failed mutation must not report success or leave an optimistic state that falsely claims persistence.

The authoritative operation determines whether retry is safe. Provider mutations, chat sends, and moderation are never silently queued offline. Idempotent local and relay operations reconcile by stable identity. Mockup toasts that simulate an action must become real operation feedback, not a replacement for implementation.

7. Device and capability policy

7.1 Supported installation profile

• Android 11, API 30, or newer.
• arm64-v8a for physical production devices.
• x86_64 for emulator verification only.
• Touch phones, tablets, and foldables.
• Google Play services are required for FCM notifications, but the rest of the application must report notification unavailability without disabling unrelated capabilities.

Installation support does not imply maximum simultaneous media capacity. At first launch and after relevant environment changes, the app derives a measured capability profile from device, decoder, memory, thermal, storage, and runtime observations.

7.2 Lowest qualified profile

The lowest Parity-Qualified profile must support:

• two active live video surfaces with one focused audio source;
• one 43.11 MiB English local-caption model and one caption session;
• segmented recording with safe finalization and recovery;
• app-private downloads plus explicit export;
• complete diagnostics;
• visible performance, storage, and thermal state.

Higher profiles may allow three through six active videos. Multistream may retain up to six configured slots even when the device renders fewer active videos.

7.3 Runtime degradation

Degradation is ordered, visible, and reversible with hysteresis. It must preserve the focused task and recoverable artifacts. The order is:

1. reduce background refresh and nonessential animation;
2. lower nonfocused stream quality or frame rate;
3. replace nonfocused video with periodically refreshed thumbnails;
4. pause nonfocused decoders while retaining StreamSlots;
5. protect the focused player, recording finalization, and Product Store writes.

The UI must explain the active limitation and the recovery condition. It must not silently remove a StreamSlot or corrupt an active media job.

8. Workspace and shared-core architecture

8.1 Target workspace

The repository must converge on one root npm workspace and lockfile:

apps/
  desktop/
  mobile/
  worker/
  integration-relay/
packages/
  core/

@streamfusion/core exposes explicit subpaths only:

@streamfusion/core/platform
@streamfusion/core/content
@streamfusion/core/discovery
@streamfusion/core/auth
@streamfusion/core/chat
@streamfusion/core/reliability
@streamfusion/core/relay
@streamfusion/core/testing

There is no root barrel export. Package exports, TypeScript project references, eslint-plugin-boundaries, and no-restricted-imports enforce the dependency direction from the first extraction commit.

8.2 Core ownership

The core owns portable domain models, schemas, validation, use cases, ports, reliability policies, capability contracts, and shared test fixtures. @streamfusion/core/relay owns serialization-safe request, response, event, error, and version-envelope schemas shared by Mobile and the Integration Relay. Service internals and persistence records remain private. Core must not import React, React Native, Expo, Electron, Node-only APIs, Cloudflare bindings, SQLite, SecureStore, provider SDKs, or Kotlin types.

Desktop, Mobile, the OAuth Worker, and the Integration Relay own their concrete transports and adapters. Every Platform adapter runs the shared adapter contract suite plus Platform-specific tests.

8.3 Mobile module layout

apps/mobile/
  app/                 Expo Router route declarations
  src/features/<feature>/
    routes/            thin entry points
    components/        feature UI and input collection
    domain/            framework-independent rules and workflows
    capabilities/      application-owned ports
    adapters/          provider, relay, device, and native integrations
    data/              persistence, migrations, queries, and mappers
    utils/             pure feature-private helpers
    composition/       feature dependency wiring
    tests/             feature-owned verification
  src/composition/     application dependency wiring
  src/design/          mobile tokens and primitives derived from DESIGN.md
  modules/             narrow Kotlin Expo modules

Only composition modules may import both a consumer and its concrete implementation for dependency wiring. Domain, route, and component modules must not import concrete Twitch, Kick, Cloudflare, SQLite, SecureStore, Expo native module, or Kotlin implementations. Adapters and data modules own those integrations. This layout follows the current repository feature-ownership rules and replaces the earlier flat adapter and persistence sketch.

8.4 Runtime state ownership

• TanStack Query owns remote request state and invalidation.
• Encrypted SQLite repositories own durable product state.
• The bounded Cache Store owns disposable provider responses and media metadata.
• Zustand owns presentation-only state such as active sheets, local navigation affordances, and temporary layout state.
• The player session coordinator owns active playback and mini-player state.
• Android services own recoverable background media jobs.

No state is duplicated across owners without an explicit projection and reconciliation rule.

9. Platform, authentication, and relay boundaries

9.1 Direct-first rule

Signed-in documented Platform operations run directly from Android with the user's access token. The Integration Relay is not an ordinary signed-in proxy and never receives user access or refresh tokens.

Signed-out discovery may call narrowly scoped relay read endpoints backed by server-held app credentials. Those endpoints return shared schemas, apply rate limits, and expose no reusable app token.

9.2 Twitch authentication

Twitch uses Device Code Grant directly from Android. The credential coordinator must:

• show the verification URI and code accessibly;
• poll within provider intervals and cancellation rules;
• store access token, refresh token, expiry, scopes, user ID, and generation atomically;
• validate the session as Twitch requires;
• serialize refreshes because Device Code refresh tokens rotate and are one-time use;
• disconnect and erase credentials without removing unrelated local product data.

9.3 Kick authentication

Kick login opens in the system browser with S256 PKCE and state. The callback uses one verified HTTPS Android App Link tied to the production application ID and signing certificate. The app retains the verifier and expected state for the active attempt, then sends the authorization code, exact redirect URI, and verifier to the existing token-only Worker.

The Worker adds the Kick client secret for exchange and refresh. It must allow only the exact approved mobile callback in addition to its existing Desktop callbacks. It must not become a general Platform proxy or persist user tokens.

Current Kick documentation still requires client_secret for both exchange and refresh. The Worker cannot be removed until Kick documents and ships a public-client registration and secretless token contract, and StreamFusion validates that contract.

9.4 Integration Relay

apps/integration-relay is a separate Cloudflare Worker with these responsibilities only:

• narrow signed-out official Platform reads;
• Twitch and Kick webhook subscription management and verification;
• foreground Kick chat receipt, deduplication, and channel fanout;
• Live Notification registration, topic or token routing, and delivery ledger;
• delivery of an independently signed Capability Manifest;
• health and compatibility status needed by Settings and Diagnostics.

The relay may use D1 for minimal installation registrations, native push-token mappings, channel subscriptions, provider subscription records, and a bounded delivery ledger. A channel-sharded Durable Object may own active Kick chat WebSockets, deduplication, and fanout. It stores no chat history.

Each installation has a random Installation Identity and a rotating relay credential stored in SecureStore. The FCM token is neither identity nor authentication.

9.5 Capability Manifest

An offline operations key signs an expiring Capability Manifest. The relay serves but cannot sign it. The app verifies signature, schema, environment, monotonic version, issued time, and expiry before use.

The app caches the last valid monotonic manifest. Expiry falls back to baked safe defaults. Compatibility Integrations remain disabled unless the active valid policy explicitly allows them. A manifest may disable an unsafe narrow capability, but it may not force an update, erase local data, disable unrelated capabilities, or replace the parity release gate.

[TheDarkSkyXD]

Normative PRD amendment, part 2 of 2

Continuation of the expanded PRD. Every feature owns its complete UI/UX before closure; #195 is continuous consistency review, complete before #178 promotion.

10. Persistence, offline behavior, and lifecycle

10.1 Storage classes

Class	Storage	Contract
Secrets	Expo SecureStore backed by Android Keystore	Tokens, relay credential, and secret references only; excluded from backup.
Product Store	SQLCipher-encrypted SQLite	Settings, Guest Follows, history, Activity, capability policy, media-job metadata, and durable user state.
Cache Store	Separate encrypted SQLite database and app cache directory	Disposable provider data, bounded by a 256 MiB least-recently-used target and seven-day default freshness.
Media	App-private Android files	Recordings, downloads, caption model, temporary segments, and explicit user exports.

Android cloud backup and device-to-device transfer must exclude preferences, Installation Identity, SecureStore data, encrypted databases, app-private media, and signing-sensitive metadata. StreamFusion provides no implicit cloud synchronization of app-owned data.

10.2 Migrations and recovery

Product Store migrations are ordered, transactional, restart-safe, and tested from the oldest supported schema. Before migration, the app runs integrity checks and retains one encrypted local pre-migration backup. If repair and restore fail, it quarantines the Product Store, preserves recoverable media, offers artifact recovery, and requires an explicit reset. It never silently deletes product data. Clearing Cache Store must never clear Product Store, preferences, secrets, downloads, or recordings.

Media jobs use explicit durable states such as queued, preparing, running, pausing, paused, finalizing, completed, failed-retryable, failed-terminal, and canceled. Job commands are idempotent. On process restart, the native service and JavaScript coordinator reconcile from durable metadata and filesystem evidence.

10.3 Offline behavior

Cached discovery may render with its age and offline status. Previously stored History, Activity, settings, Guest Follows, downloaded media, and completed recordings remain usable offline.

Provider mutations that cannot be proven idempotent must not be silently queued for later execution. They fail visibly and can be retried by the user. Relay registration projections may use stable operation IDs and bounded retry because their reconciliation contract is idempotent.

Lifecycle behavior is explicit:

Capability	Background or PiP	Process death or reboot	Offline
Playback	One selected primary stream may continue in Android PiP; other Multistream tiles pause.	Playback stops. The route may restore, but playback never silently restarts.	Previously downloaded media only.
Chat	Disconnect when chat is not visible.	Reconnect when visible, deduplicate supported replay, and show a gap marker.	Unavailable.
Recording	User-started visible foreground service may continue for the certified four-hour window.	Finalize and retain playable partial output when possible; restart requires user action.	No new remote job starts. Normal transient stream recovery may continue an already reachable source.
Download	User-started visible service continues while Android permits.	Reconcile journal, files, and native state; safely resumable work may resume.	Pause until the required network is available.
Export	User-started visible service continues while Android permits.	Reconcile and resume only when safe; never present incomplete shared output as complete.	Private source remains usable.
Discovery	No background polling.	Reload or use bounded cache.	Timestamped cached pages are read-only.
Product state	Durable local changes continue where applicable.	Restore History, Guest Follows, Activity, settings, diagnostics, and jobs from Product Store.	Fully available.

10.4 Activity retention

Activity is the durable local inbox for notifications and media-job events. Completed events are retained for 90 days or 2,000 entries, whichever bound is reached first. Active jobs remain until terminal reconciliation regardless of that bound. Unread state, event identity, timestamps, Platform and channel identity, media-job links, and delivery source survive process death.

Ingesting the same event ID updates the existing Activity Item. It must not create a second row or reset a non-null read timestamp to unread. Native job events, relay retries, foreground receipt, notification entry, and restart reconciliation obey the same rule. A genuinely new event has a new stable ID and may start unread. Mark-read and mark-all-read operations persist locally; the badge derives from the persisted unread projection. Test a duplicate before and after restart after the item has been marked read.

11. Playback, chat, media, and Compatibility Integrations

11.1 Native modules

Narrow Kotlin Expo modules may implement:

• playback session and Android PiP integration;
• foreground recording and download services;
• segmented media finalization and recovery;
• local caption runtime and model management;
• Android diagnostics and resource observations;
• APK verification, download handoff, and update maintenance.

TypeScript adapters translate these modules into core ports. Native module errors use stable typed codes and actionable diagnostics rather than raw exception strings.

11.2 Playback and media

Native HLS rendering is Android-owned. Platform adapters resolve playback sources. A playback-source failure affects only the selected item and must expose Platform, integration mode, last successful stage, and safe recovery action.

One playback session is focused for audio, chat, captions, recording context, and PiP. Multistream coordinates multiple StreamSlots without giving each slot independent background ownership.

Recording runs as a visible Android foreground service and is certified for at least four hours on the lowest qualified device. It writes segments, checkpoints metadata, monitors storage, and finalizes a playable partial artifact after interruption when possible. Downloads are app-private until the user chooses an explicit Android export destination. Broad storage permission is forbidden.

Local captions support one active English model session in 1.0. Playback audio is processed locally and is never uploaded for captioning. The UI shows download size, installed state, active resource cost, errors, and removal action.

11.3 Chat

Twitch foreground chat uses one managed EventSub WebSocket and direct Helix send. Reconnection recreates subscriptions and reports gaps because EventSub does not replay missed chat events.

Signed-out Twitch viewing remains available, but opening Twitch chat requires login. The chat sheet explains this requirement without blocking playback. Anonymous IRC is not retained as a signed-out fallback. Closed or hidden chat disconnects without discarding the playback session. Only one supporting sheet or pane is active at a time.

Kick foreground receive uses provider webhooks verified by the Integration Relay and a channel-sharded fanout connection to active clients. Kick chat send remains a direct documented user-token call from Android. The relay deduplicates provider message IDs and stores no chat transcript.

Emotes and cosmetics are parsed into shared message models. Rendering caches are bounded. Moderation commands enforce provider scopes and channel authority in the adapter and surface partial Platform support explicitly.

11.4 Compatibility Integration policy

A Compatibility Integration is permitted only when all of these conditions hold:

• the outcome is parity-critical;
• no documented provider path delivers it;
• the integration is isolated behind a narrow port;
• it has fixtures, contract tests, a live canary, diagnostics, and an independent signed kill switch;
• failure affects only that capability;
• a safe fallback or explicit unavailable state exists;
• release notes disclose the compatibility dependency;
• its removal condition is recorded.

The approved initial compatibility set is:

• native Twitch and Kick playback-source resolution;
• Kick videos and clips;
• Twitch VOD chat replay or gap sources;
• Kick chat replay, predictions, and pins.

Twitch account follow writes and Kick account follow reads or writes are not approved compatibility work. Android uses Guest Follows and opens the provider page for account-level follow actions. Twitch playback may fall back to the approved web embed when technically possible. Kick playback becomes unavailable if its native source integration is disabled. Signed-out discovery asks the user to sign in if its narrow relay read path is unavailable.

When a documented replacement becomes available, it must pass the same contract and release gates. The compatibility implementation is deleted after one stable release on the official replacement.

12. Live Notifications and Activity

12.1 Client and credential boundary

Android uses expo-notifications for permission, channels, native token registration, receipt, response handling, and local presentation. It calls getDevicePushTokenAsync() and registers the native FCM token with the Integration Relay. It does not request or store an ExpoPushToken, and the relay does not use the Expo Push Service.

Firebase is used only for FCM registration and delivery. StreamFusion must not add Firebase Auth, Firestore, Realtime Database, Storage, Analytics, Cloud Functions, Remote Config, or Firebase Test Lab.

The production Firebase Android configuration registers only com.thedarkskyxd.streamfusion. The FCM HTTP v1 service credential exists only in the Integration Relay's protected production secret store. It never enters the APK, EAS client credentials, logs, diagnostics, or source control. Development and production use separate application IDs, Firebase projects, FCM credentials, relay namespaces, topics, tokens, and test data.

12.2 Routing and scale

Product Store is authoritative for Live Notification preferences. A versioned Live Notification Projection tells the relay which native token belongs to which enabled Platform and Channel pair. Each pair maps to a stable, non-secret FCM topic. A topic is a delivery address, not source of truth or authorization. The app and relay reconcile membership after preference changes, launch, foregrounding, token rotation, reinstall, account changes, and network recovery.

A small audience may use direct native-token fanout. A burst uses one topic event rather than one request per follower.

A single logical event chooses exactly one delivery mode, topic or direct token. A stable event ID deduplicates webhook retries, relay retries, client receipt, Activity reconciliation, and mode transitions.

FCM limits an app installation to 2,000 topic subscriptions. When an installation would exceed that limit, the relay keeps the preference and routes the overflow through direct native-token delivery. It never silently drops a subscription. Account, device, media-job, and other private notifications always use direct tokens.

The relay queues work, smooths bursts, respects Retry-After, and applies bounded exponential backoff with jitter. Invalid or unregistered tokens are retired. Delivery records distinguish accepted by FCM, retryable failure, terminal token failure, and local reconciliation. StreamFusion does not claim that FCM acceptance guarantees device receipt.

12.3 User behavior

Permission is requested in context when the user enables the first live alert, chooses notification setup, or starts notification-dependent media work. A denial never disables Activity, and Settings provides a retry path. Once permission exists, remote delivery defaults to enabled while at least one Live Notification is enabled. Users can configure the global setting and per-channel preference.

Guest Follows are eligible for live alerts without a connected Platform account. The notification projection includes the enabled Guest Follow Platform and Channel identities. Account disconnect must not remove unrelated Guest Follows or their eligible notifications. Activity and Settings expose permission state, native registration status, last relay reconciliation, and actionable delivery failures without displaying the push token or relay credential.

Payloads contain only a schema version, stable event and source identifiers, safe display metadata, and an allowlisted destination. They never contain credentials, secrets, chat content, or playable media URLs. Android validates the payload and resolves current data before routing. An ended stream opens its ended Channel or detail state rather than a broken player.

Android keeps separate Live, Media, and Account/Device notification channels. Required foreground-service notifications remain visible. Notification actions are restricted to safe local controls such as Watch, Pause, Resume, Stop, and Dismiss. Chat and moderation mutations are never notification actions.

• Foreground event: write Activity and show an in-app banner.
• Background or terminated event: write or reconcile Activity and request a system notification.
• Missed event whose stream is still live: notify and show the original stream start time.
• Missed event whose stream has ended: add Activity only.
• Force-stopped app: make no delivery promise until the user opens the app and reconciliation runs.

The app must not run a persistent provider listener, notification foreground service, or frequent notification polling loop. Notification actions open the correct channel in Watch and preserve stable event identity. Android upserts registration on launch, foregrounding, and token rotation; removes it when remote delivery is disabled or an associated account is disconnected where possible; and relies on relay expiry for inactive registrations and uninstall.

13. Build, identity, signing, and updates

13.1 Release identities

• Production application ID: com.thedarkskyxd.streamfusion.
• Development application ID and signing identity: separate from production.
• Production Expo project: owned by the StreamFusion Expo organization.
• Production Android publisher: the project owner's full-distribution individual Android Developer Console identity.

The publisher account uses two hardware security keys, offline recovery codes, and a dedicated browser profile. The production key is an EAS-managed operational key with two encrypted offline backups stored separately. A recovery drill is required before 1.0, every six months, and after credential or owner changes.

13.2 Version and build authority

versionName and monotonic versionCode are committed in the repository. Remote auto-increment is disabled. The Publisher explicitly starts the production EAS cloud APK build. Protected GitHub automation promotes one exact EAS build ID after a second Publisher approval.

The promotion must prove source commit, workflow inputs, lockfile digest, toolchain versions, EAS build identity and logs, application ID, version, ABI set, signer fingerprint, APK SHA-256, APK size, SBOM, and verification manifest.

13.3 Immutable Android Release Set

GitHub immutable releases must be enabled. A public stable release contains one internally consistent Android Release Set:

• universal signed APK;
• android-update.json;
• SHA256SUMS;
• signed verification manifest;
• build-info.json provenance record;
• SBOM;
• release notes and compatibility disclosures;
• parity snapshot;
• redacted release evidence index;
• installation and update instructions.

Every file must reference the same commit, version, application ID, signer, and APK digest. Promotion fails closed on a missing, mutable, mismatched, expired, failed, or quarantined element.

13.4 In-app update flow

The app checks only the latest stable GitHub release, manually or at most once per 24 hours while foregrounded. It validates metadata schema, application ID, monotonic version, expected production signer, and APK digest before offering an update. Download is resumable and app-private. A native module revalidates the completed artifact and hands it to Android PackageInstaller. Installation always requires explicit user action.

Updates are never mandatory. StreamFusion does not silently downgrade, uninstall, or overwrite data. A bad release is removed from update metadata while its evidence is retained, then replaced by a higher version signed with the same trusted key. A signed Capability Manifest may disable only the unsafe narrow capability while the forward fix is prepared.

The Settings Updates screen contains manual Check now, current version, last check and result, optional automatic foreground checks, and the available update's progress and actions. It must not offer the prototype's prerelease toggle, hourly frequency, or background polling. Check failure never blocks startup. Drafts and prereleases are ignored.

The update manifest contains schema version, tag, version name, numeric version code, APK asset name, SHA-256, byte length, minimum API, and application ID. It supplies no executable download URL. The updater selects the matching asset through GitHub release metadata and verifies immutable release state and bounded metadata. Before installation it rechecks asset name, length, hash, application ID, version, and pinned signer. Unknown-source installation access is requested only after Install. Cancellation, offline state, rate limits, low storage, malformed metadata, invalid APK, and installer rejection have explicit recovery states. Staged files are removed after completion, cancellation, or expiry. History, Activity, settings, diagnostics, local media, and export remain available on outdated builds.

14. Verification and public release predicate

14.1 Four gates

1. Change Gate: every change runs deterministic static analysis, unit, component, contract, native configuration, dependency, secret, and permission checks appropriate to its blast radius.
2. Main Gate: main runs the Change Gate plus clean API 30 and current-API emulator smoke journeys and publishes indexed evidence.
3. Candidate Gate: nightly or release-candidate runs cover phone, tablet, foldable, physical devices, accessibility, performance, security, live providers, install, upgrade, interruption, and recovery. The complete candidate must pass twice consecutively.
4. Public Release Gate: an independent reviewer, capability owners, and Publisher approve fresh evidence for the exact signed APK. Signer recovery must be current, and the immutable Android Release Set must match the promoted digest.

One visible diagnostic retry is allowed for infrastructure noise, with the original result retained. A release still requires two clean complete Candidate Gate results. Quarantined tests and Development Exceptions block release.

14.2 Required environments

The project-owned lab uses local or EAS emulators and five physical roles:

• lowest-qualified API 30 phone;
• constrained phone;
• current mainstream phone;
• tablet;
• foldable.

Dedicated Twitch and Kick test identities and channels cover auth, discovery, chat, moderation, webhooks, live state, and notification behavior. Firebase Test Lab is not part of the plan.

14.3 Quality thresholds

• Shared core: at least 90 percent branch coverage.
• Mobile domain and adapters: at least 80 percent branch coverage.
• Parity-critical scenarios: explicit tests regardless of aggregate coverage.
• Cosmetic UI: no arbitrary line-coverage quota.
• Accessibility: zero serious or critical findings, 200 percent font scaling, 48 dp targets, contrast checks, and physical-device TalkBack proof.
• Performance: absolute budgets on the lowest profile plus a release block for regressions greater than 10 percent from the accepted baseline.
• Media: constrained playback and a four-hour recording soak with artifact validation.
• Notification scale: accept and dispatch a 100,000-recipient logical event within 30 seconds without relay loss. This measures StreamFusion dispatch, not guaranteed FCM device delivery.
• Security: dependency, lockfile, action and package signature, secret, permission, network, environment-isolation, APK static, and SBOM checks.

14.4 Evidence catalog

A versioned machine-readable catalog is keyed by Desktop capability ID. Each record includes source commit, APK digest, test and verifier version, environment, device and API, artifact hashes, result, timestamp, expiry, and links.

One project-local verifier and mobile proof skill run the same checks locally and in CI and resume from retained artifacts. Automated redaction removes credentials, push tokens, provider content not needed for proof, and user data before publication.

Retention is 14 days for development evidence, 30 days for main evidence, and permanent for the redacted release index and release artifacts. Maximum ages at promotion are:

• exact artifact, promotion, and live-provider evidence: 24 hours;
• emulator evidence: 72 hours;
• physical-device and accessibility evidence: seven days;
• human review: 30 days;
• signing-key recovery drill: six months.

Install evidence covers clean install, upgrades from the previous two versions, migration from the oldest supported Product Store schema, wrong signer, downgrade attempt, low storage, interrupted download, and reinstall. Recoverable app-owned data must survive every supported path.

The final release predicate is true only when every current Desktop capability has an allowed Android outcome, fresh required evidence, two clean complete Candidate Gate runs, no blocker, exception, or quarantine, all approvals, current signer recovery, and an immutable Release Set matching the exact APK digest.

15. Implementation sequence

Implementation tickets must be cut into verifiable units in this order:

Phase 0: repository and build foundation

• Expand the root workspace to Desktop, Mobile, Worker, Integration Relay, and packages.
• Establish the single lockfile, project references, package exports, dependency-boundary linting, Expo development client, dev and production identities, and CI skeleton.
• Create the evidence catalog schema and project-local verifier shell.

Phase 1: shared-core extraction

• Execute the ten approved checkpoints: unify installation; create the boundary; extract leaf contracts; clean data contracts; extract discovery behavior; expand capability ports; extract auth semantics; extract chat and notification policy; finish Desktop migration; open Android feature work only after the extraction predicate passes.
• Keep Desktop behavior green through adapter contract suites.
• Track narrow Desktop migration exceptions and remove all of them before Android product feature work begins.

Expo and build scaffolding may proceed during extraction. Android product features may not bypass the extraction gate by recreating domain logic inside screens or adapters.

Phase 2: mobile shell and device foundation

• Implement route shell, design primitives, adaptive navigation, route inventory, accessibility foundation, Product and Cache Stores, SecureStore, migrations, capability profiling, and diagnostics plumbing. Temporary route placeholders are foundation-only and cannot satisfy a later feature's acceptance.
• Prove install, launch, offline state, process death, schema migration, and storage separation on API 30 before feature slices depend on them.

Phase 3: identity, discovery, and relay

• Implement Twitch Device Code and Kick App Link PKCE flows.
• Extend the token-only Worker allowlist without expanding its role.
• Build Integration Relay identity, signed-out reads, signed Capability Manifest, webhook verification, registration, and environment isolation.
• Deliver Home, Search, Categories, Category Detail, Following, Accounts, and Guest Follows as vertical slices.

Phase 4: Watch and engagement

• Implement playback source ports, native player, Watch, movable mini-player, Android PiP, videos, clips, live chat, emotes, replay, moderation, History, and Multistream.
• Add each Compatibility Integration independently with its kill switch, canary, fallback, diagnostics, and disclosure.

Phase 5: native media and maintenance

• Implement downloads, segmented recording, local captions, media-job Activity, proxy and connectivity, complete Settings, complete Diagnostics, and Android maintenance services.
• Pass lowest-profile, interruption, storage-pressure, thermal, and four-hour recording gates.

Phase 6: notifications and release path

• Implement native FCM registration, topic and direct-token routing, Activity reconciliation, permission behavior, scale controls, and failure handling.
• Implement exact-APK verification, GitHub metadata, updater module, EAS promotion, signed manifest, SBOM, immutable Release Set, and signer-recovery procedure.

Phase 7: parity closure

• Reconcile the generated ledger against the exact candidate.
• Revalidate every already-completed capability and tab state with fresh evidence. Missing feature UI or interactions return to the owning feature issue rather than becoming release-stage implementation work.
• Pass the complete Candidate Gate twice, complete independent review, and promote the exact signed APK.

Each implementation ticket must name affected capability IDs, architectural layer, allowed dependencies, acceptance evidence, failure containment, and rollback or forward-fix behavior. A ticket is not complete when code merely exists; its required evidence must be indexed.

Section 6.7 applies throughout phases 2 through 6. Feature UI, business behavior, integration, and observed evidence finish together, before the next dependent feature relies on them. #195 reviews continuously and must finish its integrated UI and UX acceptance before #178 promotion. Phases 6 and 7 contain no deferred general UI implementation milestone.

16. Approval criteria

This specification is ready for implementation-ticket creation when the reviewer confirms that it:

• preserves all 24 current Desktop capability outcomes;
• reflects the approved five-destination navigation and complete nested screen or tab inventory;
• keeps shared business logic portable and concrete transports app-owned;
• confines trusted services and secrets to the approved boundaries;
• uses direct FCM without adding other Firebase products;
• defines recoverable Android lifecycle and media behavior;
• makes Compatibility Integration risk explicit and independently controllable;
• defines the exact signed APK, evidence, and immutable GitHub Release contract;
• leaves no product or architecture decision that would materially change implementation-ticket boundaries.

Approval of this document authorizes decomposition into implementation tickets. It does not by itself authorize a public release or waive any parity or verification gate.

17. Supporting decisions

• Desktop parity inventory
• Continuous parity contract
• Shared-core boundaries and extraction sequence
• Android navigation and interaction model
• Android device support and capability policy
• Android feasibility
• Twitch and Kick integration constraints
• Signed GitHub APK delivery and update safety
• Kick native OAuth recheck
• StreamFusion design system
• Wayfinder map

18. Grilling decisions and implementation contracts

This register reconciles approved decisions and later corrections with the build contract. Earlier questions and rejected options are history, not additional features. Each source remains linked so an implementer can check the exact approval. The screen and control contract supplies the visual and per-control detail; this section supplies cross-screen rules.

Source decision	Binding requirements	PRD location and implementation ownership
#101 approved parity contract	Track specification, delivery, progress, freshness, blockers, approvals and exceptions independently. Bind proof to semantic Desktop outcomes and the Android candidate. An unavailable required outcome is not a successful adaptation. Public prereleases require the full public predicate.	Sections 2, 4 and 14; #126, #177, #179–#181. UI acceptance belongs to each feature, not these release gates.
#102 extraction resolution	One workspace and lockfile. Private Core internals, explicit exports, serialized timestamps, pure shared rules, app-owned adapters and shared contract suites. No module-load provider registration, blanket Mobile boundary exception, or product work before extraction completion.	Sections 8 and 15; #123–#137. Production must not import testing exports. Reuse portable provider code only after the unchanged implementation passes both runtimes.
#103 runtime architecture	One application composition root plus feature wiring; explicit state ownership; narrow typed native modules; direct signed-in calls; token-only OAuth Worker; separate Relay with no user Platform credentials or chat archive. Capability fallback is domain policy, not a silent adapter choice.	Sections 8, 9, 11 and 12; #138, #142, #144–#147, #172–#174.
#104 navigation amendment, complete panels and tabs, Media removal, selected category	Search replaces Find. Five destinations remain fixed. Bottom local search retains its scope. No permanent Now Playing strip or standalone Media library. Category routes carry the selected identity. Movable mini-player and Android PiP replace the old strip. All Settings panels and tab states are mandatory.	Section 6 and the screen and control contract; #139, #141, all screen-owning feature issues, #195.
#105 lifecycle resolution	Device-local Product Store authority, separate bounded cache, secret custody, backup exclusion, explicit quarantine/reset, private media and export. Durable media intent precedes native effects. Reconcile journals, service generations and files. No silent playback or recording restart and no offline provider mutation queue.	Sections 10 and 11; #140, #141, #153, #155, #163–#165, #170–#171.
#105 final FCM resolution	Direct FCM supersedes Expo Push Service, while retained permission and missed-event UX remains binding. One delivery mode per logical event, stable IDs, private direct-token messages, topic-overflow fallback and no guaranteed device receipt.	Section 12; #151, #169, #172–#174. No ExpoPushToken or sender credential in the client.
#106 verification resolution	Four progressive gates, isolated environments, dedicated provider identities, five physical roles, retained diagnostic retry, two clean full candidate passes, coverage and accessibility requirements, expiry and immutable exact-artifact evidence.	Section 14; per-feature evidence under section 6.7, #177, #179–#181. Existing artifact-integrity success alone cannot satisfy the complete current-candidate predicate.
#107 PRD approval	Approved planning baseline. Approval does not authorize a release or waive extraction, parity, evidence or Publisher controls.	Entire PRD; this amendment expands previously underspecified screen and action detail.
#108 device resolution and approved detailed answers	Installation and qualification are distinct. Retain six configured slots, measure two through six active videos, protect focused work and artifacts. Four-hour recording, private downloads/export, one local caption session and app-owned diagnostics remain constrained outcomes.	Sections 7, 10 and 11; #143, #160, #164–#167, #171. Later section 7.3 defines the degradation order where the earlier document differs.
#109 provider policy	Official first, isolated approved compatibility only, independent signed disable, safe fallback, diagnostics and removal after one stable official replacement. Guest Follow/provider-page adaptations; Twitch chat requires login even when viewing is signed out.	Sections 9 and 11; #145–#162, #169. Scope and role failures never become fake success or blanket app failure.
#110 signing and updater resolution	Separate identities and authority; two explicit Publisher approvals; permanent signer with offline recovery; stable immutable APK delivery; no production OTA; optional foreground updater with artifact rejection and consent. Account controls, succession and signer-compromise handling remain required.	Sections 13, 14 and 18.6; #175, #176, #178, #181. Mockup prerelease/hourly/background choices are superseded.
#121 graph approval	Preserve existing issue identities and dependency-ordered implementation. The original 59-ticket graph is the baseline, not proof that every UI action was specified.	Section 15 and the roadmap. The user's 2026-09-07 amendment makes UI/UX part of every feature's closure and adds the pre-promotion #195 checkpoint.

18.1 Navigation, discovery and content rules

• The account shortcut opens Accounts inside More. Selecting the current primary destination returns its nested history to root; the next repeat scrolls the root to the top. Android Back dismisses the nearest overlay before leaving a nested route or the task.
• Search History retains at most ten unique Channel, Stream and Category queries per search type locally. Repeat, remove and clear are distinct actions. Typing, submitting, clearing, changing a filter and switching a tab preserve the owning screen's context. Local search does not become global Search.
• Search uses All, Channels, Streams, Videos, Clips and Categories. Following uses Live, Videos, Clips, Categories and Channels, with live channels before offline channels and explicit Guest or account relationship identity. Recommendations do not appear as followed channels.
• Category cards open their own category identity, artwork, title, summary, scoped search and shareable route. Category tabs retain Live Streams, Clips and Videos plus Platform, language, tag and sort controls.
• The user's Category Videos correction requires Twitch VOD results rather than live streams in that tab. Live streams belong in Live Streams. Kick recorded-content support remains a separate approved compatibility capability elsewhere; this correction does not silently remove all Kick videos or clips from the app.
• Typed identity survives every transition: circular Channel avatar, 16:9 Stream/Video/Clip thumbnail, 3:4 Category artwork, Platform identity and disambiguating type/time metadata. Missing art uses a labeled fallback, not unrelated sample art.
• Partial-provider errors preserve successful results, show the failed Platform, and expose scoped retry. Refresh, pagination and filter changes must not duplicate records, merge unlike content types, or allow a late response from an old context to replace the current result set.

18.2 Watch, engagement and media rules

• Single and Multistream share one focused session for audio, chat, captions and PiP. Converting Single to Multistream preserves the current stream as focused. Returning to Single retains the configured room until explicit clear/end.
• Compact Watch has closed, peek and expanded supporting-sheet states. Chat, Info, Related and playback tools use that region instead of stacked independent overlays. Wider layouts use a supporting pane without losing selection or media state.
• The mini-player moves among safe snap regions without covering primary navigation or floating search. Expand, pause and close act on the existing session. Android PiP and the mini-player are mutually exclusive. Backgrounding pauses nonfocused video slots and preserves their configuration.
• Provider login, scopes and channel authority control chat and moderation actions. Unsupported tools have a capability-specific explanation. Pending commands, rejection, rate limits, cancellation and reconnect gaps are visible. Remote chat/moderation commands never become offline queued work or notification actions.
• Recording, download and export state appears at the originating content, in Activity and in required Android notifications. There is no separate Downloads destination. Commands reconcile by job identity and generation. A stale running flag is not proof that a native service still runs.
• Downloads resume only when source/range or segment validation allows it. Partial output remains private and incomplete until verified and finalized. Export copies through an explicit Android destination and preserves the private source unless separately deleted.
• Recording warns before the four-hour certified background window, finalizes recoverable segments at cutoff or interruption, and permits explicit foreground continuation when constraints allow. Stop, crash, reboot, network loss, low storage and OS timeout must report honest state and preserve recoverable output.
• Captions use one English 43.11 MiB model and one focused session. The user sees model size, download/install state, resource impact, errors and removal. Decoded program PCM stays local. There is no microphone-permission request, uploaded audio or cloud-transcription fallback.
• Device qualification derives from measured workloads rather than a model/RAM/version allowlist. Requalification follows a native update, Android update or material profile change. Temporary heat, memory, battery, network or storage pressure degrades visibly rather than silently revoking support. Safety demotion may be immediate; recovery requires stable evidence and hysteresis.

18.3 Accounts and follow rules

Twitch Device Code exposes readable/copyable code, verification destination, waiting state, provider-controlled polling, cancellation, expiry, denied scopes and retry. Kick PKCE retains one active attempt's verifier and expected state, validates the exact callback, and rejects stale or mismatched attempts. Neither flow reports connection before validated credentials are committed atomically.

One coordinator per Platform serializes refresh, checks generation and scopes, and exposes auth-lost state to affected features. Account switch or disconnect invalidates affected requests and secrets without deleting unrelated Guest Follows, History, Activity, settings or private media. Credentials and raw callback secrets never enter logs or report previews.

Guest Follow is a device-local mutation available while signed out and offline. Account follow actions without an approved official write path use Guest Follow plus an explicit provider-page action. Do not infer provider-account synchronization from a local follow toggle. A partial or unavailable provider read must not erase a previously valid follow set as if an authoritative empty result had arrived.

18.4 Activity, notifications and recovery rules

Activity includes channel alerts, media-job progress and recovery, actionable device degradation, eligible moderation alerts, updates and account/maintenance notices. All, Channels and Jobs filter the same durable inbox. Read count and item state agree after mutations and restart.

Duplicate ingestion preserves the existing read timestamp as required in section 10.4. Opening an item resolves its current destination; an ended stream opens ended Channel/detail state. An alert for a job returns to its actual source content and job controls. Malformed, unsupported or stale routes fail safely without creating a sixth destination or restarting playback.

Permission-denied and unavailable-FCM states keep local Activity usable. Guest notification eligibility does not require Platform login. Registration and preference reconciliation runs after launch, foregrounding, token rotation, reinstall, account or preference changes and network recovery. One logical event uses topic or direct delivery, never both deliberately. Overflow preferences retain direct-token delivery eligibility. Permanent payload, credential and unregistered-token failures are surfaced rather than retried blindly.

After force-stop, delivery is not promised until reopening. Reopening reconciles identity, registration, preferences, jobs and Activity and exposes relevant interruption health. A missed still-live event uses its original start time; an ended missed event adds Activity without a stale system interruption.

18.5 Settings, diagnostics and destructive actions

All 17 Settings panels and their individual controls belong to the feature issue that implements the relevant behavior. The screen and control contract lists each control, its expected outcome and any unresolved default or range. Settings changes update the authoritative owner, show failure, and survive restart where durable. A displayed toggle must not claim that an OS permission, provider integration or native capability is enabled when only a local preference changed.

Clear Cache affects only disposable cache and images. Product reset, account disconnect, deleting private media, removing a caption model and clearing history are distinct operations with exact scope and appropriate confirmation. Cancel has no side effect. Storage pressure does not silently delete completed media. Recovery preserves artifacts before an explicit destructive reset.

Diagnostics adapts Desktop support outcomes to app-owned Android observations: structured redacted logs, memory/storage/network/battery/thermal state, media decoder and dropped-frame health, caption/job health, available ANR and process-exit evidence, capability/degradation state, report bundles and recovery. It does not promise arbitrary process signaling, other-app inspection or production logcat access. All six tabs remain distinct and testable.

Report creation offers a redacted preview, collection/progress/failure state, and explicit share/export action. Reports exclude credentials, push tokens, relay secrets, private provider content and unnecessary device identifiers. Debug proof controls and simulated prototype metrics do not satisfy user-facing Diagnostics or support workflows.

18.6 Publisher and update safeguards

The Publisher uses the approved individual Android Developer Console identity and controls the StreamFusion Expo organization. Package registration binds the permanent application ID and production signer before publication. Repository access, Expo membership and signing/publication authority remain distinct. Production credentials are unavailable to ordinary pull-request workflows.

Signing-key recovery uses two encrypted offline backups with secrets stored separately. EAS is the operational copy, not a backup. A drill restores in isolation and confirms the pinned certificate using a nonproduction test artifact. A lost operational copy pauses production until recovery. Confirmed compromise freezes signing/publication; the application ID is retired unless a tested rotation protects every supported API. Checksums do not revoke a compromised signer.

Publisher succession uses official package-account transfer, Expo/GitHub role transfer, authenticated encrypted keystore handoff, rotation of nonsigning credentials, preserved package/signer continuity and a witnessed recovery drill. These are Publisher tasks, not authority granted to an implementation agent.

The update prompt is optional. Install requests unknown-source access only after user intent and always delegates final consent to Android. Unsafe remote capability disablement cannot lock local data, force an update or erase data. Public prerelease, stable release and production OTA policies remain those in sections 3, 4 and 13.

18.7 Later user amendments and delivery ownership

The 2026-09-07 user direction is binding: implement the full UI and UX inside every feature issue and complete integrated UI review before release promotion. #195 owns continuous reconciliation and cross-feature consistency, not deferred page construction.

The root launcher retains Electron option 1 and Mobile option 3. Mobile source, configuration, assets, tests and dependency declarations belong under apps/mobile; root owns orchestration and the approved single workspace/lockfile. npm may hoist generated dependencies at the ignored root. Real launch proof uses the root menu. The Expo Go fast path must reuse a warm emulator and meet the accepted under-one-minute cold-start requirement on the measured workstation; custom-native proof uses the matching development client. Expo Go cannot prove unsupported native capabilities.

Portrait primary controls remain upright, visible and reachable. Tablet/foldable adaptations are separate supported layouts, not permission to replace the requested portrait presentation. No desktop release, paid device service, production signing change or publication is authorized by this PRD amendment.

19. Remaining explicit decisions and build readiness

This expansion makes approved screens and discussed workflows binding. It does not invent answers to questions the source material did not settle.

ID	Unresolved detail	Required resolution and owner
OPEN-PERF	Exact absolute startup, frame, memory and caption-lag budgets, measurement durations and hysteresis thresholds for device qualification are incomplete in the approved sources.	#143 and #177 propose reproducible measured limits for review before qualification claims. The existing two-video floor, 43.11 MiB model, four-hour recording, 10% regression bound and section 14 limits remain binding. Do not substitute arbitrary mockup metrics.
OPEN-SEQUENCE	#143 full lowest-profile qualification requires playback, Multistream, captions, recording, downloads and complete Diagnostics that currently depend on #143.	#143/#122 must explicitly resolve foundation-versus-full-workload acceptance and dependencies before closure. UI ownership does not authorize silent issue reordering or synthetic-load qualification.
OPEN-CONTROLS	Some mockup control defaults, numeric limits or unsupported Platform choices are sample data rather than an approved rule.	Each owning feature resolves the entries identified in the screen and control contract from approved Desktop behavior and Android policy, or records a specific product decision. Do not remove the control silently or implement a sample value as policy.
OPEN-PROOF	Required physical-device and exact-candidate evidence may not yet exist.	Feature owners record missing evidence honestly under section 6.7. #195 and release gates cannot turn it into a pass. Evidence collection is separate from the specification's completeness.

An unresolved detail blocks only the affected acceptance, unless the dependency graph makes it a prerequisite. Unaffected approved work continues in issue order. No feature closes with required UI deferred, an unresolved business rule hidden behind a working button, or missing proof labeled complete.

[TheDarkSkyXD]

PRD and feature-acceptance update complete

The user-requested PRD amendment is published in part 1 and part 2, with the normative screen/control contract.

Updated and read back 36 feature issue bodies with issue-specific UI/integration scope and required visual, interaction, state, accessibility, lifecycle and real-device evidence. Also updated #195 and #178–#180. Existing issue states were preserved.

Every feature implements and verifies its own complete UI/UX before closing. #195 reviews continuously from development and finishes integrated review before #178 promotion. Native GitHub blockers now include #195 on #178 and retain #195 on #180. Release gates revalidate the completed experience; they do not build deferred pages.

The contract reconciliation passes for 34 screens, 17 panels, 40 tab states, 25 declared actions, 62 setting keys and 6 dynamically generated player controls. Page composition and additional unbound buttons have named workflows or explicit unresolved decisions. Seven positive/negative checker cases, 15 local links, graph validation with 60 tickets and zero cycles, formatting and whitespace checks pass. This proves document/inventory reconciliation, not runtime UI completion.

Repository PRD, companion, roadmap, graph and checker are updated locally. No commit/push was made because unrelated Desktop edits are in progress in the shared worktree. The comments above retain the complete amendment on GitHub independently of that pending documentation commit. No application code, release, production credentials or issue completion status was changed by this documentation task.

[TheDarkSkyXD]

Desktop feature parity, mobile-ready UI

User clarification: Mobile screens and UI/UX must offer the same features as the current Desktop application, with mobile-ready interactions. The mockup is a presentation reference, not a reduced feature list or a cap on functionality.

Each feature owner compares Desktop screens, components, settings, menus/context actions, business rules, states and tests. Map every outcome to a discoverable touch-accessible Mobile control or a specifically approved Android adaptation. Add missing mockup content and PRD requirements within the feature issue. Do not defer the UI or this comparison to release.

Adapt layout, input, safe areas, accessibility and lifecycle for Android. Preserve existing explicit adaptations for device capacity, private media/export, contextual jobs, provider policy and app-owned Diagnostics. Do not copy Electron-only mechanisms or silently approve a missing outcome through an unavailable label.

This rule is added as PRD section 4.1 and to the normative screen/control contract. The mockup update is in progress with Desktop-source-backed controls and explicitly simulated fixture states. This is not a claim that the Android feature implementation is complete.

[TheDarkSkyXD]

Mobile mockup expansion, 2026-09-07

The user requested missing Desktop features in the mobile-ready mockup. This update changes the HTML design reference and its PRD/control contract, not production Android or Desktop code.

Changes

• Added touch-accessible player controls and caption/model interactions, media-job entry points, chat tools, typed History actions, slot editing and merged/channel chat.
• Added moderation channel-tools sheets plus Activity and Active moderators tabs. Tools include Shield Mode, AutoMod policy/queue, blocked terms, stream information, suspicious users, community, whispers, rewards and provider-native handoffs.
• Expanded Diagnostics history and collection-gap presentation; added account/notification permission fixtures. Removed obsolete prerelease/hourly/background updater controls in favor of the approved stable foreground policy.
• Kept the five primary destinations and approved Android adaptations. Secondary tools use sheets rather than extra primary destinations. The no-query default opens approved variant B.
• Updated the PRD, screen/control contract, roadmap and ticket graph. The inventory is 34 screen entries, 42 tab states, 17 settings panels, 67 review scenarios, 62 literal action IDs and 63 settings keys including six dynamic player visibility controls. The volume range has its own input binding.
• Added a Desktop-to-Mobile outcome comparison acceptance clause to 36 owning feature issues and read each back. No issue state or label changed. Features must complete their UI/UX alongside behavior, not defer it to release.

Verification and limits

Inline JavaScript syntax and required action/settings declarations pass. The declaration contract reconciles exact coverage markers. Seven positive/negative checker tests pass, local document links resolve, and the 60-ticket dependency graph has no cycles.

node docs/research/streamfusion-mobile/mobile-mockup-fixture-check.mjs passes 106 pure Node assertions. These generate all 67 scenario HTML strings and exercise selected local state transitions, including targeted History removal, slot order/grid consistency, caption routing and escaped fixture text. They do not run a browser, prove pixel layout, focus behavior, native playback, authentication, provider writes, persistence or Android performance. Prettier and scoped git diff --check also pass.

Browser verification is incomplete. The installed browser CLI returned the file title, then subsequent commands saw about:blank and an inconsistent session. Its local diagnosis passed. The fallback browser explicitly blocked navigation to the local-file URL. No alternate route was used to bypass that policy. No current browser screenshots or interaction pass are claimed.

The mockup still has explicit unresolved controls whose detailed provider policy/workflow belongs to their owning issue. This update does not declare exhaustive semantic coverage or close #195. The PRD rule requires each owner to compare current Desktop controls, states and tests before closure.

Changes remain local and uncommitted. Concurrent unrelated Desktop edits and telemetry are preserved. The repository pre-commit hook requires a fully staged/clean worktree and runs E2E; it was not bypassed and unrelated work was not staged or stashed.