@www.hyperlinks.space/program-kit 1.2.3

package/docs/tma_logo_bar_jump_investigation.md

@@ -0,0 +1,69 @@
+# TMA logo bar jump on input focus – fix
+
+## Problem
+
+When the user focuses the AI & Search input in the Telegram Mini App, the keyboard opens and the logo bar jumps (shifts down then up). The whole column (logo bar + main + bottom bar) was also scrollable.
+
+**Cause:** Viewport height shrinks when the keyboard opens; if root/body height follows that, the layout reflows and the host may scroll the window → logo bar moves. Reacting on every browser resize (e.g. Visual Viewport) caused intermediate reflows before the final state.
+
+## What we tried (dismissed or replaced)
+
+| Approach | Outcome |
+|----------|--------|
+| **Position fixed for logo bar** | Reverted. Did not fix the shift inside TMA. |
+| **Root height from `viewport.stableHeight()`** (pin layout to stable height so it doesn’t change on keyboard) | Not used. We chose “single update when TMA reports” instead. |
+| **Visual Viewport API** (`window.visualViewport` resize + `body.style.height` + `--vh` + `scrollTo(0,0)` on every resize) | Replaced. Caused intermediate reflows; keyboard open triggered multiple resize events before the final size. |
+| **Scroll lock only** (prevent window scroll) | Necessary but not sufficient on its own; layout still shifted. |
+
+## Solution
+
+Use **only the TMA viewport API**. When the keyboard opens, change nothing until TMA sends **viewport_changed**; then apply the new height and scroll reset in one turn.
+
+### 1. TMA viewport (Telegram.tsx)
+
+- After `viewport.mount()`:
+  - **`viewport.bindCssVars()`** – SDK sets/updates `--tg-viewport-height`. Layout height is driven by this.
+  - **`on("viewport_changed", handler)`** – Run **`window.scrollTo(0, 0)` only when `payload.is_state_stable`** (or `payload.isStateStable`). Do not reset scroll during drag or animation.
+- **Window scroll lock** – `window.addEventListener("scroll", …)` → if `scrollY > 0` then `scrollTo(0, 0)`.
+- **viewport-fit=cover** on the viewport meta (iOS).
+
+### 2. CSS (global.css)
+
+- **html**: `height: 100%`, `overflow: hidden`, `overscroll-behavior: none`.
+- **body**, **#root** / **[data-expo-root]**: `height: var(--tg-viewport-height, 100%)`, `min-height: var(--tg-viewport-height, 100%)`, `overflow: hidden` (body also `overscroll-behavior: none`).
+
+### 3. Layout
+
+- **Root View** (_layout.tsx): `overflow: "hidden"`, flex column.
+- **Logo bar** (GlobalLogoBar): `flexShrink: 0`.
+- **Main**: `flex: 1`, `minHeight: 0`.
+
+### 4. TMA (telegramWebApp.ts)
+
+- **readyAndExpand()**: `expand()`, `setHeaderColor("#000000")`, `setupSwipeBehavior({ allow_vertical_swipe: false })`, `disableVerticalSwipes?.()`.
+
+## viewport_changed payload
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `height` | number | Viewport height. |
+| `width` | number (optional) | Viewport width. |
+| `is_expanded` | boolean | Viewport expanded. |
+| `is_state_stable` | boolean | State stable (no change in the next moment). |
+
+Only call `scrollTo(0, 0)` when **is_state_stable** is true. Support both `is_state_stable` and `isStateStable` (bridge payload shape).
+
+## Summary: keep vs dismiss
+
+**Keep in the stack:**
+
+- TMA-only viewport logic: `viewport.bindCssVars()`, `on("viewport_changed", …)` with **is_state_stable** check before `scrollTo(0, 0)`, window scroll lock, viewport-fit=cover.
+- CSS: `--tg-viewport-height` for body and #root, overflow/overscroll locked on html/body and root.
+- Root `overflow: "hidden"` and logo bar `flexShrink: 0`.
+- readyAndExpand (expand, setHeaderColor, setupSwipeBehavior, disableVerticalSwipes).
+
+**Dismiss as try-outs:**
+
+- Any use of **Visual Viewport API** for TMA (resize/scroll listeners, `body.style.height`, `--vh`) — replaced by TMA viewport + bindCssVars + viewport_changed.
+- **Position fixed** for the logo bar — reverted.
+- **stableHeight**-based root height — not used; we use bindCssVars (current height) and rely on **is_state_stable** to avoid resetting scroll until the viewport is stable.

package/docs/update.md

@@ -0,0 +1,205 @@
+# Instant App Updates Plan
+
+This plan defines how to deliver near-instant updates for the app with minimal user friction, while keeping binary releases for native-level changes.
+
+## 1) Update Strategy (Two Lanes)
+
+- **Lane A: OTA updates (default, fast path)**
+  - Use Expo EAS Update to deliver JavaScript/TypeScript and asset changes.
+  - No reinstall required.
+  - Target latency: minutes or less after publish.
+- **Lane B: Binary releases (slow path)**
+  - Use installer/store release only when native/runtime changes are required.
+  - Triggered through `app/releases/**` and GitHub Release workflow.
+
+Decision rule:
+
+- JS/UI/business logic/assets changes -> OTA
+- Native dependency/plugin/permission/runtime changes -> binary release
+
+## 2) Current Project Baseline
+
+Already configured:
+
+- `app/app.json` has `updates.url`.
+- `app/app.json` has `runtimeVersion.policy = appVersion`.
+- `app/eas.json` has channels:
+  - preview profile -> `main`
+  - production profile -> `production`
+
+Implication:
+
+- Binaries built on a channel only receive updates from that same channel and compatible runtime version.
+
+## 3) Target Architecture for "Instant" Updates
+
+1. Developer merges code to branch.
+2. CI publishes OTA update to EAS (`main` or `production` branch/channel).
+3. App receives update check trigger (foreground/resume and optional push signal).
+4. App fetches update, then applies at safe point (next app restart or immediate reload based on policy).
+
+For binary-only updates:
+
+1. `app/releases/builder/build_MMDDYYYY_HHMM/` (or Forge under `app/releases/forge/...`) changes.
+2. GitHub workflow dedupes and creates Release if new.
+3. Workflow calls `POST /api/releases` webhook.
+4. Backend notifies clients that binary update is available.
+
+## 4) Server and CI Setup
+
+### 4.1 GitHub Secrets
+
+Add repository secrets:
+
+- `EXPO_TOKEN` (required for EAS CLI in CI)
+- `RELEASE_WEBHOOK_URL` (for binary-release notification)
+- `RELEASE_WEBHOOK_TOKEN` (for endpoint auth)
+
+### 4.2 OTA Workflow (GitHub Actions)
+
+Create workflow `.github/workflows/eas-update.yml`:
+
+- Trigger:
+  - `push` to selected branches (`main`, optionally `release/*`)
+  - Optional `workflow_dispatch`
+- Path filters to avoid unnecessary publishes (example):
+  - include app source and config paths
+  - exclude `app/releases/**`
+- Steps:
+  1. checkout
+  2. setup node
+  3. install deps (`npm ci` in `app/`)
+  4. publish OTA:
+     - branch `main` for preview/internal
+     - branch `production` for production
+  5. output EAS update group id and URL
+
+Recommended publish command:
+
+- `npx eas update --branch <branch> --non-interactive --message "<commit message>"`
+
+### 4.3 Binary Workflow (Already Planned)
+
+Keep `app/releases/**` workflow with dedupe:
+
+- If release exists, skip.
+- If new, create GitHub Release and upload assets.
+- Call `POST /api/releases`.
+
+## 5) App Runtime Behavior
+
+Implement client update behavior with `expo-updates`:
+
+1. On app start and on foreground:
+   - call `checkForUpdateAsync()`
+2. If update exists:
+   - call `fetchUpdateAsync()`
+3. Apply policy:
+   - silent + apply on next launch (default safe)
+   - or prompt user and reload now (`reloadAsync()`)
+
+Suggested policy:
+
+- **Critical fixes:** prompt and reload now
+- **Normal updates:** fetch silently and apply next launch
+
+Minimum checks:
+
+- On cold start
+- On foreground if last check older than threshold (for example 10 minutes)
+
+## 6) Push-Accelerated Detection (Optional but Preferred)
+
+OTA itself is already fast, but to reduce time further:
+
+- Add backend push trigger when CI publishes OTA.
+- App receives push and immediately runs update check.
+
+Channels you can use:
+
+- Expo Push Notifications
+- Firebase Cloud Messaging
+- WebSocket/SSE (if app has persistent session)
+
+Fallback remains foreground polling.
+
+## 7) Versioning and Compatibility Rules
+
+With `runtimeVersion.policy = appVersion`:
+
+- OTA is only delivered to binaries with matching `expo.version`.
+- When native changes occur:
+  - bump app version
+  - ship new binary
+  - publish OTA for that new runtime afterward
+
+Team rule:
+
+- Do not bump app version for pure JS hotfixes unless intentionally creating a new runtime.
+
+## 8) Security and Reliability
+
+- Protect `/api/releases` using token and optional HMAC.
+- Make webhook handler idempotent by `release_id`.
+- Retry webhook delivery in workflow with backoff.
+- Log update lifecycle:
+  - CI publish success/failure
+  - release webhook accepted/rejected
+  - app check/fetch/apply events (client telemetry)
+
+## 9) Rollout Plan
+
+Phase 1 - Staging:
+
+1. Implement OTA workflow for `main` channel only.
+2. Add app-side check/fetch on startup + foreground.
+3. Test with internal build on `main`.
+
+Phase 2 - Production:
+
+1. Add production publish workflow/manual gate.
+2. Add push-accelerated trigger.
+3. Monitor crash-free sessions and update adoption rate.
+
+Phase 3 - Hardening:
+
+1. Add kill switch/rollback procedure.
+2. Add release dashboard with latest OTA and binary status.
+
+## 10) Operational Playbook
+
+### Publish OTA update
+
+From `app/`:
+
+- `npx eas update --branch main --message "fix: ..."`
+- for production:
+  - `npx eas update --branch production --message "fix: ..."`
+
+### Publish binary update
+
+1. Create `app/releases/builder/build_MMDDYYYY_HHMM/` with installer at root and supporting files under `dev/`.
+2. Push changes.
+3. Workflow creates (or skips duplicate) GitHub Release and calls `/api/releases`.
+
+### Rollback OTA
+
+- Republish a known-good commit to the same branch/channel with a new OTA message.
+- If needed, temporarily disable update checks via remote config flag.
+
+## 11) Acceptance Criteria
+
+- OTA updates reach active users without reinstall for JS/UI changes.
+- Median time from CI publish to client fetch is within target SLA.
+- Binary updates only occur for native/runtime changes.
+- Duplicate `release_id` never creates duplicate GitHub Release.
+- `/api/releases` accepts only authenticated requests.
+- App always has fallback update detection even if push signal fails.
+
+## 12) Next Implementation Tasks
+
+1. Create `app/api/releases.ts` endpoint.
+2. Add `.github/workflows/eas-update.yml`.
+3. Add client update service wrapper (`check/fetch/apply` policy).
+4. Add docs section in `build_and_install.md` linking OTA vs binary rules.
+5. Add monitoring events for update checks and apply outcomes.

package/docs/wallets_hosting_architecture.md

@@ -0,0 +1,257 @@
+# HyperlinksSpace — Wallet Architecture Doc
+
+> High-level system design, UI flow principles, and implementation thoughts.  
+> Target: non-custodial TON wallet built into the HyperlinksSpace app (Flutter/TMA/Web).
+
+---
+
+## 1. Guiding Principles
+
+- **Non-custodial by default.** The mnemonic (seed phrase) never touches the server. Key generation and signing happen on-device.
+- **Telegram-first identity.** Inside Telegram, the user's Telegram account is the identity anchor. Outside Telegram (Windows desktop, Web), Telegram Login is used as the identity bridge.
+- **Small, working steps.** Each wallet feature ships as an isolated, backward-compatible unit that can be deployed without touching existing bot or app flows.
+- **Stable coin built-in.** The wallet is designed from day one to display and eventually allocate DLLR (or another locked stable) alongside the TON balance.
+
+---
+
+## 2. Wallet Types and Entry Points
+
+The app supports two wallet modes:
+
+| Mode | Description | Who uses it |
+|---|---|---|
+| **Unhosted (non-custodial)** | Created inside the app, keys live on device | New users with no existing wallet |
+| **TON Connect** | Connects an existing external wallet (Tonkeeper, MyTonWallet, etc.) | Power users with existing wallets |
+
+TON Connect is treated as an **additional/advanced feature**, not the default. The primary flow is always the unhosted wallet.
+
+---
+
+## 3. Wallet State Machine
+
+Every wallet instance moves through these states:
+
+```
+[ No Wallet ]
+     │
+     ├──── "Create wallet" ──────► [ Generating ]
+     │                                   │
+     └──── "Restore wallet" ────────────►│
+                                         ▼
+                                   [ Created ]
+                                   (address shown instantly, QR + copy)
+                                         │
+                                         ▼
+                                   [ Deploying ]
+                                   (SMC deploy call in progress)
+                                         │
+                               ┌─────────┴─────────┐
+                               ▼                   ▼
+                          [ Ready ]           [ Deploy Failed ]
+                     (fully operational)      (retry available)
+```
+
+**State storage key:** `awallet_v1` (encrypted blob in SecureStorage)  
+**Metadata stored separately (plaintext):**
+```
+wallet_address
+created_at
+last_seen_at
+deploy_status   ← "pending" | "deployed" | "failed"
+```
+
+---
+
+## 4. First Launch — Unhosted Wallet
+
+**Goal:** User has no wallet. They open the app for the first time (any platform).
+
+### UI Flow
+
+1. **Wallet tab / panel opens** → app checks `awallet_v1` in local SecureStorage.
+2. Nothing found → show two CTAs:
+   - **"Create new wallet"** (primary, prominent)
+   - **"Restore wallet"** (secondary, text link — visible only if device has an encrypted blob from a previous session or the user chooses to enter a mnemonic)
+3. User taps **"Create new wallet"**:
+   - Spinner shown: _"Creating wallet…"_
+   - App generates a BIP39 mnemonic + TON keypair **entirely in-memory** (no server call at this step).
+   - Address is computed and displayed **instantly**.
+   - Encrypted blob is written to SecureStorage.
+4. App shows **"Your wallet is ready"** screen:
+   - Address (truncated + copy button)
+   - QR code
+   - DLLR status: `Allocated / Locked / Available` (placeholders until deploy completes)
+   - `"Deploying…"` status badge
+5. SMC deploy call fires in the background (POST `/wallet/deploy`). When complete, status badge updates to ✅ `"Active"`.
+6. A **"Back up your seed phrase"** nudge is shown — non-blocking, dismissible, but persistent until the user acknowledges.
+
+### Key decisions
+- Address generation is instant and shown before deploy. This is intentional UX — users can copy the address to receive funds immediately, even before the contract is deployed.
+- Mnemonic is shown **once**, at creation time. After acknowledgement it is never shown again (only recoverable via "Export seed phrase" with auth).
+
+---
+
+## 5. Second Launch — Loading Existing Wallet
+
+**Goal:** User returns to the app on the same device. Wallet was created previously.
+
+### UI Flow
+
+1. App reads `awallet_v1` from SecureStorage on startup.
+2. Encrypted blob found → decrypt using device key (Secure Enclave / Android Keystore).
+3. Wallet panel loads directly to **Ready state** — no mnemonic prompt needed.
+4. App polls `/wallet/status?address=...` to refresh balances and deploy status.
+5. If `deploy_status === "pending"` (e.g., deploy was interrupted), app auto-retries the deploy silently.
+
+### Key decisions
+- The device key (used to decrypt the blob) **never leaves the device**. It is stored in the OS-level secure keystore.
+- No mnemonic entry is needed on the same device — the encrypted blob handles re-authentication transparently.
+
+---
+
+## 6. New Device / Re-connect Scenario (Mnemonic Required)
+
+**Goal:** User opens the app on a new phone, new PC, or after clearing app data.
+
+### UI Flow
+
+1. App finds no `awallet_v1` in SecureStorage (it's a fresh install).
+2. Wallet panel shows:
+   - **"Create new wallet"** (primary)
+   - **"Restore wallet"** (secondary, prominent here)
+3. User taps **"Restore wallet"** → input field: _"Enter your 24-word seed phrase"_
+4. Words entered → app validates mnemonic → re-derives keypair → re-encrypts blob into the new device's SecureStorage.
+5. App calls `/wallet/restore` to confirm address matches expectation.
+6. Wallet loads at **Ready state** (deploy was already done on the original device).
+
+### Key decisions
+- The mnemonic is the **single recovery factor**. There is no server-side recovery.
+- Mnemonic input should use a native secure text field (no clipboard suggestions, no autocorrect logging).
+- CloudStorage (Telegram's `telegram.cloudStorage` API) can optionally store the **ciphertext** (not the key), so restore can be assisted without the user typing all 24 words. The device key is still required to decrypt it — CloudStorage alone is not sufficient to reconstruct the wallet.
+
+---
+
+## 7. Telegram Wallet — Inside Telegram (TMA)
+
+**Goal:** User accesses the wallet via the Telegram Mini App (TMA).
+
+### How identity and storage work inside TMA
+
+- **Identity:** `initData.user.id` (Telegram user ID) is the identity anchor. No separate login needed.
+- **Storage:**
+  - `telegram.cloudStorage` is used for the encrypted wallet blob — it is synced across Telegram sessions automatically.
+  - The device key (to decrypt the blob) is stored in the browser's IndexedDB / WebCrypto key store scoped to the TMA origin.
+- **First launch in TMA:** Same as Section 4, but blob goes to `cloudStorage` instead of native SecureStorage.
+- **Re-open in TMA on same device:** Blob in `cloudStorage` + device key in IndexedDB → loads wallet silently.
+- **TMA on a new device:** CloudStorage has the ciphertext, but the device key is absent → user is prompted to enter mnemonic once. New device key is generated and stored. From then on, that device works silently.
+
+### Key decisions
+- `telegram.cloudStorage` is **not end-to-end encrypted by Telegram** — it is accessible to the bot's server-side in theory. This is why we store only the **ciphertext** there, not the plaintext key or mnemonic.
+- The split: _ciphertext in CloudStorage, key in device_ ensures neither half alone can reconstruct the wallet.
+
+---
+
+## 8. Outside Telegram — Web / Windows Setup
+
+**Goal:** User uses the app via browser or Windows desktop (Electron/Tauri wrapper), outside of Telegram context.
+
+### How identity works outside TMA
+
+Since there is no `initData` from Telegram, identity is established via **Telegram Login Widget** (OAuth-style flow):
+
+1. User is shown a "Log in with Telegram" button.
+2. Telegram sends a signed hash to the app confirming the user's Telegram ID and username.
+3. App uses the Telegram ID as the identity anchor — same as inside TMA.
+
+### Storage outside Telegram
+
+- **Web browser:** Encrypted blob is stored in `localStorage` (or IndexedDB for larger payloads). Device key in WebCrypto non-extractable key store.
+- **Windows desktop:** Encrypted blob stored in the OS credential manager or app's local data directory. Device key in Windows DPAPI or Keychain equivalent.
+
+### First launch on Windows
+
+1. App opens → Telegram Login flow → identity confirmed.
+2. App checks local storage for `awallet_v1`.
+3. **No wallet found:** Same "Create / Restore" UI as Section 4.
+4. **Wallet found (transferred or restored):** Loads to Ready state.
+
+### Re-launch on Windows
+
+Same device → blob in local storage + device key still present → silent load, no mnemonic needed.
+
+### Key decisions
+- Windows is primarily a **reading/management surface** — send, receive, view balances. Heavy transaction flows remain on mobile/TMA first.
+- The GitHub auto-updater (workflow-based releases) is already in place for the Windows build. Wallet state must survive app updates — storage paths must not change across versions, or migration logic must be included.
+
+---
+
+## 9. API Contract (Wallet Endpoints)
+
+```
+POST /wallet/create
+  Body: { address, encrypted_blob, public_key }
+  Response: { ok: true }
+
+POST /wallet/deploy
+  Body: { address }
+  Response: { status: "pending" | "deployed" | "failed" }
+
+GET  /wallet/status?address=...
+  Response: { deployed: bool, dllr_status: {...}, balances: { ton, dllr } }
+
+POST /wallet/restore
+  Body: { encrypted_blob }
+  Response: { address }
+```
+
+The backend is **optional** for the read path — balances can be fetched directly from TON APIs (toncenter/tonapi) on the client side. The backend is primarily needed for:
+- SMC deploy coordination
+- DLLR allocation logic
+- Caching and rate-limit protection for API calls
+
+---
+
+## 10. WalletService Abstraction (Flutter)
+
+The Flutter app uses a `WalletService` interface so the UI never depends directly on whether we're in mock, front-only (direct TON API), or backend-connected mode:
+
+```dart
+abstract class WalletService {
+  Future<WalletState> loadFromStorage();
+  Stream<WalletStatus> watchStatus(String address);
+  Future<WalletInfo> createWallet();
+  Future<WalletInfo> restoreWallet(String mnemonic);
+}
+```
+
+Swap between implementations via a flag (`kUseMockWalletState` for dev, env-driven for prod). No UI refactor needed when switching providers.
+
+---
+
+## 11. Security Summary
+
+| Concern | Approach |
+|---|---|
+| Mnemonic exposure | Shown once at creation, never stored in plaintext |
+| Key storage | OS Secure Enclave / Android Keystore / WebCrypto non-extractable |
+| Server-side secrets | None — server never sees mnemonic or private key |
+| Cross-device restore | Mnemonic re-entry required OR ciphertext from CloudStorage + device key |
+| Telegram identity outside TMA | Telegram Login Widget (signed hash verification) |
+| Duplicate deploy | State machine prevents re-deploy if `deploy_status === "deployed"` |
+| App update survivability | Storage keys versioned (`awallet_v1`), migration path required for `v2` |
+
+---
+
+## 12. Phase Roadmap
+
+| Phase | Scope |
+|---|---|
+| **Phase 1** | Unhosted wallet: create, display address, deploy SMC, show TON balance |
+| **Phase 2** | DLLR integration: allocated/locked/available display, stable coin status |
+| **Phase 3** | TON Connect (connect existing wallets as secondary option) |
+| **Phase 4** | Send/receive flows, transaction history |
+| **Phase 5** | Cross-device CloudStorage assist, backup/export UX hardening |
+
+---
+
+*Last updated: April 2026. Maintained in repo at `app/docs/wallet_architecture.md`.*

package/eas.json

@@ -0,0 +1,47 @@
+{
+  "cli": {
+    "version": ">= 18.0.5",
+    "appVersionSource": "remote"
+  },
+  "build": {
+    "development": {
+      "developmentClient": true,
+      "distribution": "internal",
+      "android": {
+        "image": "latest"
+      },
+      "ios": {
+        "image": "latest"
+      }
+    },
+    "development-simulator": {
+      "extends": "development",
+      "ios": {
+        "simulator": true
+      }
+    },
+    "preview": {
+      "distribution": "internal",
+      "channel": "main",
+      "android": {
+        "image": "latest"
+      },
+      "ios": {
+        "image": "latest"
+      }
+    },
+    "production": {
+      "channel": "production",
+      "autoIncrement": true,
+      "android": {
+        "image": "latest"
+      },
+      "ios": {
+        "image": "latest"
+      }
+    }
+  },
+  "submit": {
+    "production": {}
+  }
+}

package/eslint.config.js

@@ -0,0 +1,10 @@
+// https://docs.expo.dev/guides/using-eslint/
+const { defineConfig } = require('eslint/config');
+const expoConfig = require('eslint-config-expo/flat');
+
+module.exports = defineConfig([
+  expoConfig,
+  {
+    ignores: ['dist/*'],
+  },
+]);