Skip to content

Native apps for the App Store and Google Play (draft, do not merge) - #37

Draft
0xkkonrad wants to merge 55 commits into
mainfrom
native-apps
Draft

0xkkonrad wants to merge 55 commits into
mainfrom
native-apps

Conversation

@0xkkonrad

Copy link
Copy Markdown
Contributor

Draft only. Do not merge. This PR exists so ci.yml (typecheck, docs, format, audits, Vitest with Postgres, web build, Docker build, e2e-unfurl) runs on every push to native-apps.

The branch builds the Peanut Split iOS and Android apps with Capacitor 8: a static export of the app surface bundled into each binary, talking to https://peanutsplit.com through CORS. The web build stays the standalone server it is today.

Wave 1 contents:

  • Static-export build target, IS_NATIVE_APP seam, typed native stubs, and the android/ and ios/ projects.
  • Server: CORS for the two app origins, AASA and assetlinks, app-config.json version gate, Dockerfile build arg.
  • Push: transport column and APNs and FCM senders next to web push; 503 NATIVE_PUSH_UNAVAILABLE until credentials exist.
  • Store listing texts and the privacy page update for the apps.
  • New copy in all seven catalogs, join-gate analytics events, ?slug= redaction.
  • native.yml: export, Android, iOS and web e2e base-versus-head.

Server pieces reach production through a separate small server-prep PR, not through this one.

🤖 Generated with Claude Code

The store apps wrap the static export with Capacitor 8.2.0 and its official
plugins. All pins are exact and pass the 14-day release-age floor. They land
in one commit before wave 1 so no agent relinks node_modules under a running
build. THIRD_PARTY_LICENSES.md is regenerated for the new packages.
…or projects

The store apps bundle a static export of the app surface, so one tree has to
build both the unchanged standalone web server and the export. SPLIT_NATIVE_BUILD=1
switches next.config.js to output: 'export' with .native.tsx pages, and
native:build bakes the production API origin and product flags. postbuild.mjs
checks the exported route set, forbidden strings, the baked origin and size.

IS_NATIVE_APP in platform.ts is the one compile-time seam, and every
@capacitor import stays under src/lib/native/capacitor so the web bundle never
pulls the bridge in. The native module files are typed stubs that later waves
fill against fixed signatures. The android and ios projects come from
`cap add` (both ran on Linux); generated copies stay gitignored.
…on files

The bundled app calls https://peanutsplit.com from capacitor://localhost (iOS)
and https://localhost (Android), so the proxy answers CORS for exactly those
origins, without credentials, after the canonical redirect; preflights get 204.
The proxy also sets x-split-room-slug for /r/<slug> pages and strips any copy a
caller sends. The AASA and assetlinks files let room links open the app, and
app-config.json is the static version gate that fails open. The Dockerfile
takes NEXT_PUBLIC_IOS_APP_STORE_ID as a build arg (empty keeps the web as today).
App installs get push tokens from APNs or FCM, not Web Push endpoints. A
transport column (default webpush) and nullable p256dh/auth let the existing
table hold them as apns:, apns-sandbox: or fcm: endpoints; the migration only
adds that column and drops two NOT NULLs. The fan-out picks a sender per row
and skips transports without server credentials. Subscribe and status answer
503 NATIVE_PUSH_UNAVAILABLE until credentials exist, so the app hides the row;
DELETE always works. Native payloads carry the analyticsKey, never the slug.
The senders use no new dependency; APNs can go through the CONNECT tunnel
because the containers have no egress. The FCM credential test uses a plain
escaped string, since a PEM-shaped fixture trips the secret hook.
Both stores need listing copy, privacy answers and review notes before a first
submission, and check-listing.mjs keeps them inside the field limits and free
of banned words. The privacy page now covers the apps: device push tokens,
APNs and FCM as recipients, rooms and backups kept on the device, and ad tags
on the website only. ROADMAP and CLAUDE.md record the native apps as in progress.
Later waves code against fixed keys, so all 17 new strings land now in all
seven catalogs. The join gate now reports shown and completed (via new or
claim) without identity, to compare join completion on web and in the app.
App routes carry the room slug as ?slug=, so Sentry redaction removes every
slug= parameter before any native build ships with a DSN.
Every push to native-apps should prove the export, an Android debug APK and
unsigned AAB, and an iOS simulator build and unsigned archive. The three
existing Playwright suites run on the merge base and on head, and
web-e2e-compare fails only on new failures, so the store work cannot quietly
regress the live web app. Actions are pinned to commit SHAs; no secrets used.
Three integration gaps kept the wave-1 gates red:
- native:build set its env only for `next build`, so postbuild.mjs never saw
  NEXT_PUBLIC_BASE_URL and failed. The script now exports the values for both.
- The export still contained `serviceWorker.register` from use-push.ts, which
  postbuild forbids (the app has no service worker). An inline
  NEXT_PUBLIC_NATIVE_BUILD comparison lets the bundler drop the call from the
  export; the web build is unchanged.
- The i18n audit allowed the translate="no" policy only in the product layout.
  The app export has its own root layout, so it is a second document root.
The push transport column and the widened push-subscription bodies change the
generated data-model inventory and API route reference.
The splash test pins the folders under public/ so a new one is either
precached or recorded as online-only. The app-link association files in
.well-known are served from the site, never needed offline, so they join
dev/ and press/ on the online-only side. This made ci.yml red on the draft PR.
…gned

The "no .so" check failed on the first run: firebase-messaging (needed for
Android push) pulls in androidx.datastore, which ships
libdatastore_shared_counter.so for each ABI. The real Play rule is 16 KB page
alignment for 64-bit libraries, so the step now allows that one library,
checks its LOAD segments are 16 KB aligned, and still fails on any other .so.
The first full run failed web-e2e-compare on five tests that passed on base.
Base itself had 17 failing and 20 flaky tests in the same run: the suite runs
six workers against a dev server on a small runner, and traces on both sides
show Fast Refresh rebuilds and slow route compiles mid-test. Two of the five
failed on base in the other viewport; three were flaky on base.

The head leg now re-runs its failures once with one worker (--last-failed),
and the compare step blocks only on a test that fails there too. A real
regression fails both times. The e2e job timeout rises to 70 minutes for the
extra pass.
Next builds an output: 'export' app inside .next and only copies the export
to .next-native, so native:build silently replaced any web build in .next.
A later next start, standalone copy or .next/static check would then use the
app build. postbuild.mjs now removes everything in .next except cache, so
those steps fail loudly instead. Run native:build first and pnpm build last.
The earlier '@capacitor' grep matched nothing even in the native export,
because minified bundles keep no import path. The boundary check that every
pnpm build runs (ci.yml, Docker, native.yml) now fails on Capacitor's own
identifiers in .next/static/chunks. A negative control with an export chunk
copied in fails as expected.
… one helper

The app is served from capacitor://localhost, so relative API paths would hit the
bundle instead of peanutsplit.com. saveFile keeps the web <a download> path and uses
the share sheet in the app, where downloads do not exist. The app also sends
Accept-Language from <html lang> and prewarms the room's link-preview image.
…a test

The export has no /r/<slug> route, so a hand-built room path works on the web and
breaks in the app. native-boundary.test.ts fails on such paths outside an explicit
allowlist and on Capacitor imports outside src/lib/native/capacitor. The app home
shows the empty-list line once storage is read and holds no rooms.
One pure decision (decideEntry) picks boot path, launch URL, push tap or /app/, and
one dispatcher handles a link whether it arrives at launch or while running, so a
cold start from a room link navigates once. Native pages validate the slug and the
app home carries the Privacy link both stores require.
…s to the browser

The storage mirror copies rooms and member tokens to Preferences so an evicted
WebView store does not lose them. The share polyfill lets Android share files,
external links leave the WebView, and analytics tag the surface without loading
remote code in the app.
With NEXT_PUBLIC_IOS_APP_STORE_ID set, iOS browsers get a 'store' install state and
the Smart App Banner on room pages; a store tap snoozes the automatic offer for 30
days. With the ID unset, and on Android, the web behaves exactly as before.
… scans

Both stores require a privacy link, and Apple requires consent before a photo goes
to the AI model. The consent is shown only in the app (orchestrator ruling); the
web scan flow is unchanged and an e2e spec pins that.
The WebView has no Cache Storage, install handoff or recap, so those paths check
first. When the device is offline the room error says so, offers Your rooms next
to Retry, and retries on reconnect.
The apps have no over-the-air updates, so a breaking API change needs a way to stop
old binaries. The gate fails open on any fetch error, and version-code.mjs gives
monotonic build numbers for both stores.
…de now calls

initAnalytics now registers the surface super property, and SettingsSheet reads
useSettings for the app-only scan consent toggle. Three older tests mocked those
modules without the new members, so init threw and the sheet failed to render.
The landing e2e checks that /app carries no <footer>, because a footer there means
the marketing chrome leaked into the installed app. The Privacy link is one line
under the room list, so a paragraph says the same without tripping that check.
The spec waited for the first /card/crew response, which can be the shelf tile, then
tapped once. The share button fetches its own copy, so a tap before that copy lands
shares nothing. The test already failed this way on the merge base (native runs
43547081381 and 43551545649) and only passed through retries.
A room read that starts after the browser fired 'offline' does not fail; React Query pauses it
with no error, so the room and the import screen showed their skeleton with no Retry and no way
back for as long as the person stayed offline. roomReadBlocked() treats a paused read without
data like a failed one. Found in the wave-2 spec review.
Nothing tested that the store app asks for consent before POST receipt-parse, and no later task
owned it (Apple 5.1.2(i)). The test renders ScanFlow and fails when the gate is removed; it needs a
DOM, so happy-dom 21.0.4 (released 2026-10-20, past the 14-day floor) becomes a devDependency.
…s reply

The chained queue could lose a remove that a hard reload follows (Remove from device, Leave): the
page unloaded before the earlier native reply, Preferences kept the member token, and the next
hydrate restored it. Capacitor already runs one plugin's calls in dispatch order.
WKWebView's own navigator.share refuses a call made after an awaited fetch (NotAllowedError), so
the history export failed in the iOS app. The polyfill now replaces it on both platforms.
Opening a room by pasting its link was the one app entry that sent no app_room_opened event, so
the entry funnel undercounted it. The web keeps its events unchanged.
ci.yml's licenses:check failed because the new happy-dom devDependency (consent gate test) added
seven packages that THIRD_PARTY_LICENSES.md did not list.
ExistingRoomImportScreen now decides its load-error screen with roomReadBlocked from
@/lib/queries; the test's module mock did not export it, so all four cases failed in CI.
The scaffolded projects lacked what both stores check before review: iOS
16.4 iPhone-only portrait, the encryption and camera plist keys, the
privacy manifest that matches store/privacy-answers.md, per-config
entitlements with applinks:peanutsplit.com, and Release manual signing.
AppDelegate forwards the APNs token to Capacitor so push can register.
Android gets the verified /r/ App Link, only the permissions Split uses
(AD_ID removed), keystore- and google-services-gated Gradle signing, and
env-driven version codes for the release lane.

Icons and splash come from resources/ via @capacitor/assets so the app
matches the PWA artwork; the tool replaced the old default assets.
assert-native-config.mjs pins these settings in CI (source and built
plist), set-identifiers.mjs changes bundle IDs in one step, and
link-contract.test.ts keeps the AASA and assetlinks paths in step with
the in-app link mapper.
The app runs from capacitor:// or https://localhost and calls the web
server across origins, which no existing suite exercises. E1-E8 (plus
E8b) run the static export against a real web build on Chromium and
WebKit; a negative control removes the app origin from CORS and requires
E4 to fail, so a green run means CORS is actually tested.

native.yml also checks the association files, the merged release
manifest's permission set (a new permission must be reviewed against the
Play data-safety answers), the native config in source and built form,
and adds non-gating emulator and simulator launch smokes with
screenshots.
Web Push does not exist in a Capacitor WebView, so the app needs its own
client for the same per-room opt-in. usePush picks the native hook in the
app and leaves the web hook unchanged. The status combines OS permission,
a device token (raced against a 10 s timeout) and the server's status
answer; no token, push compiled out or a 503 reads as unsupported and
hides the rows rather than offering a switch that cannot work.

A push tap opens its room on cold start and while running through one
shared claim with sendId dedupe, and sends the opened beacon once. Leave
and forget drop the stored room subscription before the network call so
a failed request never leaves a forgotten room subscribed.
awaitColdPushTap() in cold-push-tap.ts already sends the opened beacon
and app_room_opened { via: 'push' }; the note said NativeEntry would,
which invites a second, duplicate send.
The share sheet offers 'Save Image' for a share-card PNG. Without
NSPhotoLibraryAddUsageDescription iOS terminates the app on that tap.
assert-native-config.mjs pins the key in the source plist and in the
built app's plist, so it cannot silently go missing again.
use-push.ts picked the hook through IS_NATIVE_APP, which webpack did not
fold across the module boundary, so about 10 KB of native push code
shipped in a web chunk loaded on /app and other pages. Selecting with the
inline NEXT_PUBLIC_NATIVE_BUILD literal (as host.ts does) lets webpack
drop it. The PWA boundary check now also fails the web build when the
native push hook's error text appears in .next/static.
The old step backgrounded simctl --console-pty and slept, so run
43698164332 showed SpringBoard with an empty console and proved nothing.
Launch now writes the app's stdout to console.log, polls for the
SPLIT_CORS line while checking the app is still running, and attaches
the os_log and any crash report when it died. The step stays
continue-on-error (device smokes never block).
Run 43703832986 failed the smoke on a system_server line ('JavaBinder:
Uncaught remote exception') although the app launched, opened the room
link and logged SPLIT_CORS. The check now reads only Capacitor/Console
lines, which carry the WebView's own uncaught errors.
native-release.yml builds a signed iOS archive and a signed Android bundle from a native-v* tag.
Each platform job first lists only its own missing secret names, so the lane stays inert until
Hugo adds them and one platform can ship without the other. The version comes from the tag and one
build number is computed in the export job. google-services.json is checked against the package
before Gradle, because a push-enabled build without it crashes on the first room screen.
check-review-readiness.mjs tells a person whether production is ready for store review (CORS,
AASA, assetlinks, receipt scan); it exits 1 until the server-prep PR is deployed.
NATIVE.md is the current reference for building and changing the apps. API.md and
SECURITY-MODEL.md record the cross-origin callers and the rule that the API stays compatible with
every shipped app build, since store binaries have no over-the-air update. NATIVE-HANDOFF.md lists
each account, secret, production change, device check and decision between this branch and a
store submission. seed-review-room.mjs creates the demo room the store reviewers open.
Both stores need these images before a first submission. The spec renders five screens at the
iPhone 6.9in, iPhone 6.3in and Android sizes from the real export against a seeded local server,
so the images match the app. check-assets.mjs fails when a file is missing, the wrong size or has
an alpha channel, which both stores reject. The images still need Konrad's approval.
The export job now runs check-assets.mjs, so a missing or wrong store image fails CI instead of a
store upload (4C request). docs/README.md links NATIVE.md as current and NATIVE-HANDOFF.md as
decision context, so readers can find them (4B request).
Android verifies App Links once at install and does not retry. Before
step 9.6 peanutsplit.com serves a placeholder assetlinks.json, so link
checks 1, 5 and 6 would fail on a phone that installed the internal
build early. The handoff now says to run them after 9.6 and how to
re-verify a phone that installed before it.
The store app is already the installed app, but Settings > This device
still showed "Add Split to Home Screen" / "Install Split" and sent
install_row_shown (INTERACTION 3 says never shown in the app; wave-5
store-readiness finding). DeviceSheet now mounts InstallRow only on the
web; the web sheet is unchanged. Native e2e E3 asserts no install-row
element in the device sheet (fails with 2 nodes without the guard).
A notification whose room key this device no longer knows opened /app/,
where RecentRoomAppEntry then jumped to the most recent room, which reads
as the wrong notification (wave-3 minor (c), wave-5 interaction audit).
Warm and cold taps now open /app/?manage=1, the rooms list without that
redirect: awaitColdPushTap returns { slug: null, sendId } and decideEntry
replaces to the list. Tests cover the warm, cold and entry paths.
Every launcher open, cold link and cold push tap reaches its room by
replace, so back had no history and replaced to /app/, where
RecentRoomAppEntry sent it straight into the same room: back never left
the app (wave-5 interaction audit, major). Back now goes to the rooms
list (/app/?manage=1, no redirect), and the next back minimizes. The
decision is a pure backAction() in native-entry.ts with Vitest cases;
HANDOFF device check 10 covers launcher -> room -> back -> list -> back.
file_paths.xml exposed external-path '.', the whole shared storage, to
the FileProvider although the app only shares files from its cache
(wave-5 privacy audit, minor). Only the cache path stays.
… test

CodeQL flagged the plist reader's comment stripping and first-occurrence
replace, the partial regex escape of pbxproj keys, and an unanchored host
regex in the version-gate test. The reader now drops comments as tokens,
keys are fully escaped, and the test compares exact hosts and the origin.
… Android back check

The handoff did not say that store.ios in app-config.json stays a
placeholder until someone fills it, and device check 10 still described
Android back before the rooms-list fix.
…headlines

Each screenshot is now a raw capture of the real app inside a flat brand frame with a two-line
headline, so the store pages read like the landing page and show no device or OS chrome. The seed
data fills every frame, the receipt-scan window starts on a whole item card, the feature graphic
is rendered at 2x so the condensed headline stays sharp, and the Play icon is a 32-bit PNG as
Play asks. Roboto Flex comes from @fontsource so the render needs no network.
…ffline truth

The description gains the how-it-works steps, names Google Gemini through OpenRouter for receipt
photos and links the AGPL source (Konrad, 15 Nov). The old 'rooms stay on your phone' heading
contradicted the declared server-side names, so it now says 'no account' and states what the
phone keeps. Room links no longer promise to open from any chat, and the review notes only claim
the offline hold the app really has.
Apple 5.1.2(i) needs the AI provider named where the data goes; the consent sheet already names
it, and Konrad ruled the privacy page does too. model.ts notes that switching transport or model
by env var makes these texts untrue.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants