callstack / callstack/agent-device

refactor(snapshot): one shared model for occluding system surfaces across Android and iOS

Open
#2,489 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
4.6k
Forks
299
Avg merge
10h 14m
Merged PRs (30d)
537

Description

Raised in #2448 review and deliberately filed rather than blocked on, because it is cross-platform scope.

**The shape.** `SnapshotState` now carries two parallel channels for the same concept:

- `systemSurfaceOnly?: boolean` — Android: the capture is an occluding system surface (notification shade, quick settings) rather than app content.
- `iosSystemSurfaceBundleId?: string` — iOS: the capture is an in-place system surface (a web sign-in sheet, `com.apple.SafariViewService`) presented over the app.

`withSystemSurfaceDisclosure` (`src/daemon/system-surface-disclosure.ts`) then branches on which field is set to pick a platform-specific sentence. As the reviewer put it, that is a missing shared model, not a nit.

**Why it matters beyond tidiness.** Both fields answer the same two questions — "is this capture app content?" and "what should the agent be told?" — and every new consumer has to learn that the answer lives in two places with different types. The iOS side additionally needs the identity (which surface) because it feeds comparison refusal; the Android side only needs the boolean today, but the shade/quick-settings distinction is latent.

**Rough direction** (not prescriptive): one optional `systemSurface?: { platform-neutral kind; identity? }` that both producers populate, with the disclosure derived from the kind rather than from which field happens to be set. The Android boolean becomes the degenerate case. Wants a look at whether the Android `systemSurfaceOnly` producers can supply an identity cheaply, and at the `SnapshotState` field checklist rules before adding or replacing fields.

**Not urgent.** Both channels work and are tested today. This is about preventing a third platform from adding a third channel.

Context: #2448 added the iOS side; the Android side predates it.

Contributor guide

Open the contributing guide

Research direction

Start with SnapshotState and src/daemon/system-surface-disclosure.ts, then trace the Android systemSurfaceOnly and iOS iosSystemSurfaceBundleId producers and review the SnapshotState field checklist rules. Done means both platforms populate one shared optional system-surface model, disclosure derives from its kind, existing comparison behavior remains covered, and the current tests still pass.

Written by the indexing model from the issue text.

Assessment

Tech stack
android, ios, typescript
Domain
mobile-dev
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.