Corpan 0.18.1

[skyl]

PR Type

Enhancement, Tests

---

Description

• Add monetization gates and daily locks

• Enable trials, codes, purchase analytics

• Redesign immersive Corpán Plus paywall

• Add streak and store tooling

---

Diagram Walkthrough

flowchart LR
  gate["Shared paywall gate"]
  host["App host overlays"]
  offer["Subscription offer"]
  store["Store/code backend"]
  analytics["Funnel analytics"]
  gate -- "request unlock or daily lock" --> host
  host -- "renders" --> offer
  offer -- "trials, codes, purchases" --> store
  offer -- "tracks events" --> analytics

Loading

File Walkthrough

	Relevant files
Enhancement	15 files purchase.ts Add trials, codes, review, analytics hooks                              +417/-24 SubscriptionOffer.tsx Enable trial framing and code redemption                                  +295/-77 PaywallSheet.tsx Replace themed dialog with immersive paywall                          +196/-118 paywallGate.ts Implement shared metered paywall gate                                        +396/-0  DailyLockOverlay.tsx Add universal daily quota lock overlay                                      +305/-0  App.tsx Wire daily locks and gate analytics                                            +56/-0    UpdatePrompt.tsx Adjust update backdrop for browser support                              +2/-1      types.ts Define shared monetization gate contracts                                +183/-0  index.ts Export shared monetization helpers                                              +18/-0    streak.ts Add shared pack streak tracking                                                    +123/-0  StreakBadge.tsx Display current pack streak progress                                          +41/-0    bestFit.ts Add onboarding best-fit selection logic                                    +88/-0    paywall.ts Integrate pronunciation coach paywall gating                          +24/-0    hostApi.ts Expose entitlement and paywall host seams                                +94/-0    analytics.ts Add monetization funnel tracking events                                    +134/-0
Tests	2 files paywallGate.test.ts Cover shared paywall gate behavior                                              +533/-0  streak.test.ts Test shared streak calculations                                                    +123/-0
Configuration changes	3 files asc_monetization.py Add App Store monetization tooling                                              +1328/-0 play_monetization.py Add Play Store monetization tooling                                            +777/-0  load_seed.py Add offer code seed loader                                                              +174/-0
Additional files	101 files PIPELINE_STATE.md +3/-0      BOOK_META.md +27/-0    00-title.md +1/-0      01-where-rainforests-grow.md +51/-0    02-the-weather.md +37/-0    03-the-land-and-water.md +39/-0    04-the-plants.md +53/-0    05-the-animals.md +65/-0    06-the-people.md +45/-0    07-the-rainforest-today.md +35/-0    08-closing.md +11/-0    manifest.json +13/-0    narration.yaml +239/-0  segments.json +2566/-0 generate_segments.py +175/-0  post_generate_fixup.py +201/-0  run_lang_pipeline.sh +146/-0  CONVENTIONS.md +56/-0    LANG_PITFALLS.md +5/-0      series.yaml +25/-0    LANGS_EP5.txt +6/-0      book.yaml +37/-0    00-script.md +281/-0  manifest.json +23/-0    narration.yaml +756/-0  segments.json +1823/-0 apply_pacing.py +121/-0  audio_gate.py +107/-0  audit_translation.py +74/-0    concat_with_pauses.py +60/-0    drive_concept_update.sh +20/-0    drive_remaining.sh +36/-0    find_leading_silence.py +22/-0    fixup_short_reactions.py +91/-0    generate_cover.py +78/-0    generate_dialog_segments.py +170/-0  merge_concept.py +29/-0    phonetics.py +380/-0  recover_drops.sh +80/-0    reset_segments.py +18/-0    run_lang_pipeline.sh +116/-0  update_concept_lang.sh +49/-0    CLAUDE.md +7/-3      CORPAN_PLUS_AGENT_BRIEFING.md +12/-7    CHANGELOG.md +60/-0    ANALYTICS_FUNNEL.md +107/-0  common.json +15/-0    ContentPackOverlay.tsx +11/-0    MainExperience.tsx +69/-1    OnboardingFinish.tsx +18/-4    RatingPrompt.tsx +2/-1      SettingsModal.tsx +2/-2      HomeHub.tsx +2/-2      PackCard.tsx +7/-1      ContentPackHost.tsx +7/-13    types.ts +96/-0    OnboardingEngine.tsx +6/-0      graph.ts +35/-6    types.ts +6/-0      paywall.ts +43/-5    rating.ts +56/-1    browser.ts +17/-0    APPLE_OFFER_SETUP_BRIEF.md +106/-0  PHASE3_CODES_CONTRACT.md +512/-0  STORE_AUTOMATION.md +65/-0    README.md +235/-0  seed.json +23/-0    generate-catalog-assets.py +20/-0    patch-catalog.py +9/-0      README.md +125/-0  PRICING_RESEARCH.md +197/-0  pricing-matrix.json +97/-0    PHASE3_APPLY_BRIEF.md +69/-0    codes.js +870/-0  codes.test.js +544/-0  package.json +5/-0      verify_purchase.js +264/-38 main.tf +93/-0    outputs.tf +10/-0    presence_ec2.tf +6/-0      README.md +73/-0    analyze.py +122/-0  battery.py +32/-0    evaluate.py +168/-0  judge_export.py +64/-0    langs.py +116/-0  metrics.py +310/-0  prompts.py +65/-0    report.py +117/-0  requirements.txt +5/-0      REPORT.md +102/-0  recommendations.json +78/-0    run.py +201/-0  search.py +81/-0    server.py +129/-0  setup.sh +12/-0    test_harness.py +93/-0    App.tsx +19/-1    Shell.tsx +26/-1    tsconfig.json +5/-1      Additional files not shown

---

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪

🧪 PR contains tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Trial Detection introOfferFromProduct only treats a zero-micros phase as a free trial when the formatted price has no digits. If Play Billing returns a free-trial phase as priceAmountMicros: 0 with a localized numeric display like $0.00, the offer is not classified as a free trial, so the trial CTA/framing is skipped even though the store offer exists. // Free trial: explicit zero micros (Android) OR a no-digit display price // when micros are unreliable (iOS, which sends 0 for every phase). const isFreeByMicros = microsKnown && micros === 0 && isFreeDisplayPrice(phase.formattedPrice) const isFreeByDisplay = isFreeDisplayPrice(phase.formattedPrice) if (isFreeByMicros || isFreeByDisplay) { return { kind: "free_trial", periodLabel: periodLabelFromIso(phase.billingPeriod), cycles: phase.billingCycleCount ?? 1, } Retry No-op The retry button trims the current code, but when the value is already trimmed React receives the same state value and the resolve effect does not rerun. After a transient /code/resolve failure, tapping Retry can therefore do nothing unless the user edits the field. <button type="button" onClick={() => setAffiliateCode((c) => c.trim())} className="underline underline-offset-2 hover:text-foreground"

[github-actions]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Fix free-trial detection Android free trials are commonly formatted as "$0.00", which contains digits, so isFreeByMicros currently rejects the authoritative zero-micros signal. Use the recurring paid phase to distinguish Android zero-priced trials from the iOS plugin's all-zero micros behavior. corpan/corpan-app/src/contentPacks/purchase.ts [412-420] -const isFreeByMicros = microsKnown && micros === 0 && isFreeDisplayPrice(phase.formattedPrice) +const isFreeByMicros = + microsKnown && + micros === 0 && + typeof recurringMicros === "number" && + recurringMicros > 0 const isFreeByDisplay = isFreeDisplayPrice(phase.formattedPrice) if (isFreeByMicros || isFreeByDisplay) { return { kind: "free_trial", periodLabel: periodLabelFromIso(phase.billingPeriod), cycles: phase.billingCycleCount ?? 1, } } Suggestion importance[1-10]: 8 __ Why: This correctly identifies a real bug: Android zero-priced trial phases may have formatted prices like "$0.00", so requiring isFreeDisplayPrice() defeats the authoritative priceAmountMicros === 0 signal. The proposed recurringMicros > 0 guard also preserves the intended protection against the iOS plugin's all-zero-micros behavior.	Medium
	Prevent reload quota bypass Do not exempt the initial load from paywallGate.isBlocked(). A user who is already capped can reload the pack and receive a fresh solvable phrase, allowing them to exceed JUICE_DAILY_LIMIT. corpan/packs/juice-squeeze/src/game.ts [2186-2874] -const createWordBlocks = async (opts?: { initial?: boolean }) => { +const createWordBlocks = async () => { // Hard daily cap: loading a NEW phrase to solve is the metered action. // Once the free user has reached JUICE_DAILY_LIMIT completed phrases they // get EXACTLY that many — re-show the accomplishment-lock overlay instead - // of loading another. The initial mount load is exempt (so a returning, - // already-capped user still sees the board), and subscribers never block. - if (!opts?.initial && paywallGate.isBlocked()) { + // of loading another. Subscribers never block. + if (paywallGate.isBlocked()) { paywallGate.requestDailyLock() return } ... -createWordBlocks({ initial: true }).catch((err) => { +createWordBlocks().catch((err) => { console.error("[juice-squeeze] Failed to load utterances:", err) }) Suggestion importance[1-10]: 8 __ Why: The concern is valid because exempting the initial createWordBlocks call can load a fresh solvable phrase for a user who is already capped, allowing one extra completion past JUICE_DAILY_LIMIT. Removing the initial exemption better enforces the hard daily quota.	Medium
	Avoid deleting regional configs Do not remove a rejected region's regionalConfigs entry from the patch body. With updateMask="basePlans", deleting that entry can unintentionally make the base plan unavailable or clear its regional configuration; abort or restore the original config instead. corpan/infra/play/play_monetization.py [696-698] -રconfigs[:] = [r for r in rconfigs if r.get("regionCode") != bad] -by_region.pop(bad, None) -dropped.append(bad) +if bad in by_region: + if orig_price.get(bad) is None: + by_region[bad].pop("price", None) + else: + by_region[bad]["price"] = orig_price[bad] +raise SystemExit( + f"set-prices: store rejected region {bad}; aborting to avoid removing its regionalConfig. " + "Fix or skip it explicitly before retrying." +) Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies that removing a regionalConfigs entry while patching with updateMask="basePlans" may unintentionally remove regional availability/configuration. The proposed fail-safe behavior is conservative but appropriate for avoiding destructive store configuration changes.	Medium
	Re-show daily lock correctly Use quotaGate.requestDailyLock() here instead of quotaGate.onInteraction(). For dailyLimit hard caps, onInteraction() is the legacy paywall seam and may not re-dispatch the corpan:daily-locked overlay for an already-blocked user. corpan/packs/tutomaton/src/chat.ts [1531-1537] if (quotaBlocked()) { - // Hard daily cap reached: surface the paywall (the gate fires it when - // armed) and don't send. Free messages return tomorrow, or with Plus. - quotaGate.onInteraction() + // Hard daily cap reached: re-show the accomplishment-lock overlay and + // don't send. Free messages return tomorrow, or with Plus. + quotaGate.requestDailyLock() syncSendEnabled() systemNote(t("quotaEmptyNote")) return } Suggestion importance[1-10]: 7 __ Why: The suggestion is accurate: for a dailyLimit hard cap, quotaGate.requestDailyLock() is the API intended to re-dispatch the daily lock overlay, while onInteraction() is not guaranteed to do that for an already-blocked user. This fixes an important blocked-state UX/functionality issue in send.	Medium
	Validate discount percentage Validate args.percent_off before resolving price points. Values outside (0, 100) can produce a zero/negative target or a higher-than-base price, causing the script to create an invalid or non-discount offer. corpan/infra/asc/asc_monetization.py [934] +if not (0 < args.percent_off < 100): + sys.exit(f"--percent-off must be in (0,100); got {args.percent_off}.") duration = _duration_from_months(args.months) if args.months else "ONE_MONTH" Suggestion importance[1-10]: 7 __ Why: cmd_code_discount currently accepts invalid --percent-off values that can produce non-discount or nonsensical price-point targets. This is a valid input-validation fix with meaningful correctness impact, though it is not a critical runtime bug.	Medium
General	Notify entitlement snapshot changes This only observes subscription object identity, so changes to subjectId, entitlementToken, or lastRefreshed will not notify packs despite being part of the snapshot. Compare the actual snapshot fields that buildEntitlementSnapshot() returns. corpan/corpan-app/src/contentPacks/hostApi.ts [1153-1165] onChange: (cb) => { - let prev = useEntitlementStore.getState().subscription + let prev = buildEntitlementSnapshot() // Fire on any change to the subscription / subject / token so packs // see purchases, restores, and refreshes. Compares the fields that // feed the snapshot to avoid spurious callbacks on unrelated writes. - return useEntitlementStore.subscribe((state) => { - const next = state.subscription - if (next !== prev) { + return useEntitlementStore.subscribe(() => { + const next = buildEntitlementSnapshot() + if ( + next.plus !== prev.plus || + next.subjectId !== prev.subjectId || + next.entitlementToken !== prev.entitlementToken || + next.checkedAt !== prev.checkedAt || + next.subscription.active !== prev.subscription.active || + next.subscription.plan !== prev.subscription.plan || + next.subscription.expiresAt !== prev.subscription.expiresAt || + next.subscription.autoRenew !== prev.subscription.autoRenew + ) { prev = next - cb(buildEntitlementSnapshot()) + cb(next) } }) }, Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies that onChange only tracks subscription identity despite buildEntitlementSnapshot() also including subjectId, entitlementToken, and checkedAt. Comparing the snapshot fields makes the documented entitlement change notification behavior reliable.	Medium
	Make retry actually retry The Retry button is a no-op when affiliateCode is already trimmed, so failed code checks cannot be retried unless the user edits the input. Add an explicit retry nonce and include it in the resolver effect dependencies. corpan/corpan-app/src/components/packs/SubscriptionOffer.tsx [105-697] const [codeStatus, setCodeStatus] = useState< | { kind: "idle" } | { kind: "checking"; code: string } | { kind: "resolved"; code: string; response: Extract<CodeResolveResponse, { status: "ok" }> } | { kind: "error"; code: string; error: string } >({ kind: "idle" }) +const [codeRetryNonce, setCodeRetryNonce] = useState(0) ... useEffect(() => { ... -}, [affiliateCode, selectedProductId, t]) +}, [affiliateCode, selectedProductId, t, codeRetryNonce]) ... <button type="button" - onClick={() => setAffiliateCode((c) => c.trim())} + onClick={() => setCodeRetryNonce((n) => n + 1)} className="underline underline-offset-2 hover:text-foreground" > {t("code.retry", "Retry")} </button> Suggestion importance[1-10]: 6 __ Why: The current retry handler can be a no-op when affiliateCode is already trimmed, so failed resolveCode() calls may not be retried without editing the input. Adding a codeRetryNonce is a sound, localized fix for this UX issue.	Low
	Avoid scroll-lock race Opening the paywall before closing the daily lock can race the two body scroll-lock effects: the daily-lock cleanup may restore document.body.style.overflow after the paywall has set it to "hidden". Close the lock first, then open the paywall so the paywall owns the final scroll-lock state. corpan/corpan-app/src/components/paywall/DailyLockOverlay.tsx [134-142] const upgrade = () => { trackDailyLockUpgradeTapped(context.packId) - // Hand off to the ONE universal paywall. + onClose() + // Hand off to the ONE universal paywall after releasing this overlay. usePaywallStore.getState().openPaywall({ surface: context.surface, packId: context.packId, }) - onClose() } Suggestion importance[1-10]: 4 __ Why: The concern is plausible because both DailyLockOverlay and PaywallSheet manipulate document.body.style.overflow, and unmount cleanup could interfere with the paywall's scroll lock. The impact is limited to a transient UI behavior, and React batching may already avoid some cases, but the proposed ordering is a reasonable defensive improvement.	Low
Security	Restrict generated code files Generated one-time offer codes are bearer-like secrets, but open() uses the process umask and may leave the CSV group/world-readable. Create or truncate the file with 0600 permissions before writing the codes. corpan/infra/asc/asc_monetization.py [871-872] -with open(out_path, "w", newline="") as f: - f.write(r.text) +fd = os.open(out_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600) +try: + os.fchmod(fd, 0o600) + with os.fdopen(fd, "w", newline="") as f: + f.write(r.text) +except Exception: + os.close(fd) + raise Suggestion importance[1-10]: 7 __ Why: The generated one-time-use codes are sensitive, so writing them with explicit 0600 permissions is a relevant security improvement. The proposed cleanup code could mask an exception if fdopen already closed the descriptor, but the main permission-hardening change is valid.	Medium

[skyl]

Requesting changes. I would not ship this PR as-is.

Blockers:

1. Build is red. corpan-app · tsc + build fails in npm run build at check:i18n (corpan/corpan-app/package.json runs that before Vite). Locally, npm run check:i18n reports 23 static t() keys absent from public/locales/en/common.json (code.*, trial/intro subscription strings, paywall.dismiss, onboarding.engage.explore) plus dailyLock.* and streakBadge.label missing from every non-English locale.

2. Apple offer-code redemption does not attribute purchases. The REDEEM_APPLE_SHEET branch in corpan/corpan-app/src/components/packs/SubscriptionOffer.tsx:233 presents StoreKit and returns after refresh(), so the resolutionToken never reaches /verify-purchase. The iOS plugin emits purchaseUpdated from Transaction.updates, but the app does not listen to it; local refresh only checks ownership. Result: Apple offer-code conversions can unlock locally but never write PURCHASE#, ATTRIBUTION, or initial LEDGER rows.

3. /entitlement-token cannot work for normal verified purchases. codes.readLatestEntitlement() requires PURCHASE# rows with a future expiresAt (corpan/infra/terraform/lambda/codes.js:799), but attributePurchase() writes its PURCHASE# row without expiresAt (corpan/infra/terraform/lambda/codes.js:447) and only when a resolution token exists. Non-code subscriptions do not persist any such row. refreshEntitlementToken() can therefore clear the token despite an active local subscription.

4. Initial affiliate ledger rows lose payout percentage. attributePurchase() writes revenueSharePct: claims.revenueSharePct (corpan/infra/terraform/lambda/codes.js:495), but real tokens minted by /code/resolve do not include revenueSharePct (corpan/infra/terraform/lambda/codes.js:155, corpan/infra/terraform/lambda/codes.js:692). The tests inject that field manually via verifiedClaims(), so this escapes coverage and payout exports get null pct.

Checks run:

• PASS: cd corpan/corpan-app && npm run tsc
• FAIL: cd corpan/corpan-app && npm run check:i18n
• PASS: cd corpan/infra/terraform/lambda && npm test
• PASS: npm run --prefix corpan/packs/corpan-city test:run (760 tests)

[skyl]

Review — Corpán 0.18.1 (monetization overhaul)

Verdict: ready for on-device testing. CI is green, the production build passes, the backend is live and smoke-tested, and the diff is clean of secrets. The remaining unknowns are all things only a real device build can validate (native StoreKit/Play bits) — that's exactly the next step.

Scope

250 files / 36 commits. Delivers the full monetization program: universal dark paywall · free trials (live both stores) · daily-quota gates with the accomplishment-lock + per-pack visit streaks · server-authoritative affiliate/discount codes · anonymous opt-in funnel analytics · onboarding aha auto-launch · regional pricing (applied live) · plus low-end-Android hardening (GPU-blur ANR, tutor OOM floor) and three new languages. Localized across all 54 locales.

Verified ✅

• CI green (run after the i18n fix). npm run build passes: i18n gate 717 keys × 54 locales in sync, tsc clean, vite build OK.
• Tests: monetization gate 31/31, streak 12/12, hover-runner 16/16.
• Backend live + smoke-tested: /code/resolve returns REDEEM_APPLE_SHEET (iOS) / USE_OFFER_TOKEN (Android) for IAN30, and fail-closed ATTRIBUTE_UNVERIFIED for unknown codes (no fail-open). HMAC signing works; 8-partner/8-code registry seeded.
• Stores live: Apple — 7-day trial (175 territories) + 8 affiliate codes ×2000 + giveaway batches. Google — 7-day trial + 8 affiliate offers (created this round; fixed a missing-duration bug in the Play tool). Regional pricing applied both platforms.
• Daily wall now actually enforces on every metered surface (was tutomaton-only — phrase-flip + 4 packs were counting but never blocking; also caught the "Random sentence" bypass).
• Secret-clean: no .p8/keys/service-account JSON/.env in the diff (only docs + placeholders).

Must test on device (native paths can't be CI-verified)

1. tauri-plugin-iap new request_review command (iOS SKStoreReviewController / Android Play ReviewManager + the new Gradle dep) — needs an Android + iOS build to compile.
2. Free-trial rendering from real StoreKit sandbox / Play license tester.
3. Code redemption end-to-end: IAN30 → Apple offer sheet (iOS) / discounted Play purchase (Android); bogus code denied.
4. The daily wall + accomplishment lock + streak badge, and subscriber-bypass.
   (Full step-by-step device checklist available — say the word and I'll drop it in.)

Known follow-ups (non-blocking, tracked)

• Minor paywall polish: trial badge per plan tile (monthly-only trial hidden until selected); iOS empty periodLabel can suppress the trial panel; trial_started analytics undercounts the plain intro-trial path. All minor; tune after you feel the copy.
• Renewal attribution: the Lambda handles ASSN V2 + Google RTDN already; the store/cloud wiring (secret fields + GCP Pub/Sub + 2 Console settings) is documented in infra/RENEWAL_ATTRIBUTION_SETUP.md. Not release-blocking (first-purchase attribution works). I'll run the scriptable parts on your go.
• Remote-config for paywall A/B — recommended as a separate endpoint (fail-safe defaults), Phase-4 fast-follow, not in this release.

Behavior changes to feel & tune

The daily limits are now real walls: phrase-flip/hover/juice/hanzipan 20/day, pronunciation-coach 15, tutomaton 20, soft nag every 5. These are the knobs — try them and we dial.

Recommend: build on Android + iPad/iOS, run the device checklist, then TestFlight. I'm standing by to fix anything testing surfaces.

[skyl]

Blockers addressed (commits up to 390d531c)

1. Red build / i18n — fixed. The 23 t() keys missing from en/common.json (code.*, subscription trial/intro, paywall.dismiss, onboarding.engage.explore) are now in en, and dailyLock.* + streakBadge.label + all the above are translated across all 53 non-English locales. npm run check:i18n passes (717 keys × 54 locales in sync); CI is green.

2. Apple offer-code redemption now attributes. The app subscribes to the iOS plugin's purchaseUpdated (Transaction.updates) and POSTs the pending resolutionToken to /verify-purchase after the redeem sheet, so PURCHASE#/ATTRIBUTION/LEDGER rows are written (mirrors the Android path; idempotent). App-side only — the plugin already emitted the event. Needs an iOS build to exercise.

3. /entitlement-token works for normal verified subs. attributePurchase now persists expiresAt on the PURCHASE# row, and a new recordEntitlementPurchase() writes the entitlement row for any verified active sub (no code required), so readLatestEntitlement finds it. Regression test added (fails without the fix).

4. Ledger payout pct no longer null. The resolution token now carries revenueSharePct (registry-derived at mint), and the masking test was rewritten to mint a real token instead of hand-injecting the field. New end-to-end test asserts a non-null pct from /code/resolve → attributePurchase. 34/34 lambda tests.

Blockers 3 & 4 are in codes.js / verify_purchase.js → need a Lambda redeploy to take effect live (spark/infra owns terraform/lambda). Blocker 2 needs an iOS build.

Also added — backwards compatibility (raised separately)

Packs ship OTA to pre-0.18.1 apps. The gate-v2 daily wall now hard-blocks only when the host advertises __CORPAN_HOST_CAPS.dailyLock (set by ≥0.18.1); in an older host the same pack degrades to the dismissible soft corpan:request-unlock nag every host already renders — never a frozen, unexplained wall, and no pack is version-gated. +3 tests.

Ready for re-review.