@www.hyperlinks.space/program-kit 1.2.3

package/bot/webhook.ts

@@ -0,0 +1,262 @@
+/**
+ * Telegram webhook handler for /api/bot (serverless).
+ *
+ * Flow:
+ * - User sends a message in Telegram → Telegram POSTs that update here.
+ * - We return 200 OK immediately so Telegram does not retry or hide the user's message.
+ * - We process the update in the background (waitUntil).
+ *
+ * Per-chat serialization: we process one update per chat at a time. When a new update arrives
+ * for a chat, we wait for the previous handler for that chat to finish, then run the new one.
+ * So Reply A is always sent before we start processing Prompt B — no reorder flash.
+ */
+
+import { waitUntil } from '@vercel/functions';
+import { createBot } from './grammy.js';
+
+interface TelegramUpdate {
+  update_id: number;
+  message?: { chat?: { id?: number }; [key: string]: unknown };
+  edited_message?: { chat?: { id?: number }; [key: string]: unknown };
+  channel_post?: { chat?: { id?: number }; [key: string]: unknown };
+  callback_query?: { message?: { chat?: { id?: number } }; [key: string]: unknown };
+  [key: string]: unknown;
+}
+
+/** Extract chat id from update so we can serialize processing per chat and avoid reply order flash. */
+function getChatIdFromUpdate(update: TelegramUpdate): number | undefined {
+  const msg = update.message ?? update.edited_message ?? update.channel_post;
+  if (msg && typeof msg === 'object' && msg.chat && typeof (msg.chat as { id?: number }).id === 'number') {
+    return (msg.chat as { id: number }).id;
+  }
+  const cq = update.callback_query;
+  if (cq && typeof cq === 'object' && cq.message && typeof (cq.message as { chat?: { id?: number } }).chat?.id === 'number') {
+    return (cq.message as { chat: { id: number } }).chat.id;
+  }
+  return undefined;
+}
+
+/** Per-chat tail promise: next update for this chat waits for the previous handler to finish. */
+const chatQueue = new Map<number, Promise<void>>();
+
+const BOT_TOKEN = process.env.BOT_TOKEN || process.env.TELEGRAM_BOT_TOKEN;
+/** Single bot instance for all webhook requests; created once at module load. */
+const bot = BOT_TOKEN ? createBot(BOT_TOKEN) : null;
+/** Lazy init: run bot.init() once on first use; later requests reuse the same promise. */
+let botInitPromise: Promise<void> | null = null;
+function ensureBotInit(): Promise<void> {
+  if (!bot) return Promise.resolve();
+  if (!botInitPromise) botInitPromise = bot.init();
+  return botInitPromise;
+}
+
+// Vercel production alias (VERCEL_PROJECT_PRODUCTION_URL) or deployment URL (VERCEL_URL).
+const BASE_URL =
+  process.env.VERCEL_PROJECT_PRODUCTION_URL
+    ? `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`
+    : process.env.VERCEL_URL
+      ? `https://${process.env.VERCEL_URL}`
+      : '';
+
+function jsonResponse(data: object, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: {
+      'Content-Type': 'application/json',
+      'Access-Control-Allow-Origin': '*',
+    },
+  });
+}
+
+async function setWebhook(): Promise<{ ok?: boolean } | null> {
+  if (!BOT_TOKEN || !BASE_URL) return null;
+  const url = `${BASE_URL}/api/bot`;
+  const res = await fetch(`https://api.telegram.org/bot${BOT_TOKEN}/setWebhook`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ url }),
+  });
+  const data = (await res.json()) as { ok?: boolean; description?: string };
+  return data;
+}
+
+async function getWebhookInfo(): Promise<{ url?: string }> {
+  if (!BOT_TOKEN) return {};
+  try {
+    const res = await fetch(`https://api.telegram.org/bot${BOT_TOKEN}/getWebhookInfo`);
+    const data = (await res.json()) as { ok?: boolean; result?: { url?: string } };
+    return data?.result ?? {};
+  } catch {
+    return {};
+  }
+}
+
+export async function handleRequest(request: Request): Promise<Response> {
+  const method = request.method;
+  console.log('[webhook]', method, new Date().toISOString());
+
+  if (method === 'OPTIONS') return jsonResponse({}, 200);
+
+  if (method === 'GET') {
+    const expectedUrl = BASE_URL ? `${BASE_URL}/api/bot` : '';
+    const current = await getWebhookInfo();
+    if (BASE_URL && BOT_TOKEN) {
+      const result = await setWebhook();
+      return jsonResponse({
+        ok: true,
+        webhook_set: result?.ok === true,
+        url: expectedUrl,
+        telegram_has: current.url || '(none)',
+      });
+    }
+    return jsonResponse({
+      ok: true,
+      service: 'telegram-bot',
+      bot: !!BOT_TOKEN,
+      vercel_url_set: !!BASE_URL,
+      expected_url: expectedUrl || '(set VERCEL_URL / VERCEL_PROJECT_PRODUCTION_URL)',
+      telegram_has: current.url || '(none)',
+    });
+  }
+
+  if (method !== 'POST') {
+    return jsonResponse({ ok: false, error: 'method_not_allowed' }, 405);
+  }
+  if (!BOT_TOKEN || !bot) {
+    return jsonResponse({ ok: false, error: 'BOT_TOKEN not set' }, 500);
+  }
+
+  // Read body before returning 200. Once we return, the request may be closed and body
+  // unavailable, so reading it inside waitUntil can fail and the message is lost.
+  let update: TelegramUpdate;
+  try {
+    const body =
+      typeof request.json === 'function'
+        ? await request.json()
+        : (request as unknown as { body?: unknown }).body;
+    update =
+      typeof body === 'string'
+        ? (JSON.parse(body) as TelegramUpdate)
+        : (body as TelegramUpdate);
+  } catch {
+    console.error('[webhook] invalid_body');
+    return jsonResponse({ ok: false, error: 'invalid_body' }, 400);
+  }
+  if (!update || typeof update !== 'object') {
+    console.error('[webhook] invalid update');
+    return jsonResponse({ ok: false, error: 'invalid_update' }, 400);
+  }
+
+  // Return 200 OK immediately so Telegram applies the message to the chat. Process update
+  // in waitUntil so we don't block the response on AI/DB.
+  // Serialize per chat so Reply A is always sent before we start processing Prompt B.
+  const updateId = update.update_id;
+  const chatId = getChatIdFromUpdate(update);
+  const prev = chatId !== undefined ? chatQueue.get(chatId) : undefined;
+  const work = (prev ?? Promise.resolve())
+    .then(() => ensureBotInit())
+    .then(() => bot!.handleUpdate(update as Parameters<typeof bot.handleUpdate>[0]))
+    .then(() => {
+      console.log('[webhook] handled update', updateId);
+    })
+    .catch((err) => {
+      console.error('[bot]', err);
+    });
+  const tail = work.then(() => {}, () => {});
+  if (chatId !== undefined) {
+    chatQueue.set(chatId, tail);
+  }
+  waitUntil(work);
+  return jsonResponse({ ok: true });
+}
+
+/** Legacy (req, res) handler; also used when Vercel passes (request, context). */
+export interface NodeRes {
+  setHeader(name: string, value: string): void;
+  status(code: number): { json(data: unknown): void; end(): void };
+  end(): void;
+}
+
+export interface NodeReq {
+  method: string;
+  body?: unknown;
+}
+
+async function legacyHandler(req: NodeReq, res: NodeRes): Promise<void> {
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+  if (req.method === 'OPTIONS') {
+    res.status(200).end();
+    return;
+  }
+  if (req.method === 'GET') {
+    const expectedUrl = BASE_URL ? `${BASE_URL}/api/bot` : '';
+    const current = await getWebhookInfo();
+    if (BASE_URL && BOT_TOKEN) {
+      const result = await setWebhook();
+      res.status(200).json({
+        ok: true,
+        webhook_set: result?.ok === true,
+        url: expectedUrl,
+        telegram_has: current.url || '(none)',
+      });
+    } else {
+      res.status(200).json({
+        ok: true,
+        service: 'telegram-bot',
+        bot: !!BOT_TOKEN,
+        vercel_url_set: !!BASE_URL,
+        expected_url: expectedUrl || '(set VERCEL_URL / VERCEL_PROJECT_PRODUCTION_URL)',
+        telegram_has: current.url || '(none)',
+      });
+    }
+    return;
+  }
+  if (req.method !== 'POST') {
+    res.status(405).json({ ok: false, error: 'method_not_allowed' });
+    return;
+  }
+  if (!BOT_TOKEN || !bot) {
+    res.status(500).json({ ok: false, error: 'BOT_TOKEN not set' });
+    return;
+  }
+  let update: TelegramUpdate = req.body as TelegramUpdate;
+  if (typeof update === 'string') {
+    try {
+      update = JSON.parse(update) as TelegramUpdate;
+    } catch {
+      res.status(400).json({ ok: false, error: 'invalid_body' });
+      return;
+    }
+  }
+  if (!update || typeof update !== 'object') {
+    res.status(400).json({ ok: false, error: 'invalid_body' });
+    return;
+  }
+  try {
+    await ensureBotInit();
+    const chatIdLegacy = getChatIdFromUpdate(update);
+    const prevLegacy = chatIdLegacy !== undefined ? chatQueue.get(chatIdLegacy) : undefined;
+    await (prevLegacy ?? Promise.resolve());
+    await bot.handleUpdate(update as Parameters<typeof bot.handleUpdate>[0]);
+    if (chatIdLegacy !== undefined) {
+      chatQueue.set(chatIdLegacy, Promise.resolve());
+    }
+  } catch (err) {
+    console.error('[bot]', err);
+    res.status(500).json({ ok: false, error: 'handler_error' });
+    return;
+  }
+  res.status(200).json({ ok: true });
+}
+
+export default async function handler(
+  request: Request | NodeReq,
+  context?: NodeRes,
+): Promise<Response | void> {
+  if (request && typeof (request as Request).json === 'function') {
+    return handleRequest(request as Request);
+  }
+  return legacyHandler(request as NodeReq, context!);
+}

package/database/messages.ts

@@ -0,0 +1,128 @@
+/**
+ * Message helpers for the AI messages table (bot + TMA).
+ * Shared by API routes and bot. Import from ../database/messages.js.
+ */
+import { sql } from './start.js';
+
+export type MessageType = 'bot' | 'app';
+export type MessageRole = 'user' | 'assistant' | 'system';
+
+export interface Message {
+  id: number;
+  created_at: Date;
+  user_telegram: string;
+  thread_id: number;
+  type: MessageType;
+  role: MessageRole;
+  content: string | null;
+  telegram_update_id: number | null;
+}
+
+export interface InsertMessageOpts {
+  user_telegram: string;
+  thread_id: number;
+  type: MessageType;
+  role: MessageRole;
+  content: string | null;
+  telegram_update_id?: number | null;
+}
+
+/**
+ * Insert a message. For bot user messages with telegram_update_id, the unique
+ * constraint may conflict (duplicate webhook or another instance). Returns the
+ * new row id, or null if insert was skipped due to unique violation.
+ */
+export async function insertMessage(
+  opts: InsertMessageOpts,
+): Promise<{ id: number } | null> {
+  const {
+    user_telegram,
+    thread_id,
+    type,
+    role,
+    content,
+    telegram_update_id = null,
+  } = opts;
+
+  try {
+    const rows = await sql`
+      INSERT INTO messages (user_telegram, thread_id, type, role, content, telegram_update_id)
+      VALUES (${user_telegram}, ${thread_id}, ${type}, ${role}, ${content}, ${telegram_update_id})
+      RETURNING id;
+    `;
+    const row = rows[0] as { id: string } | undefined;
+    if (!row) return null;
+    return { id: Number(row.id) };
+  } catch (err: unknown) {
+    const code = err && typeof err === 'object' && 'code' in err ? (err as { code: string }).code : '';
+    if (code === '23505') return null; // unique_violation (bot dedupe)
+    throw err;
+  }
+}
+
+/**
+ * Messages for a thread, ordered by created_at ascending (oldest first, for AI history).
+ */
+export async function getThreadHistory(
+  opts: {
+    user_telegram: string;
+    thread_id: number;
+    type: MessageType;
+    limit?: number;
+  },
+): Promise<Message[]> {
+  const { user_telegram, thread_id, type, limit = 100 } = opts;
+  const rows = await sql`
+    SELECT id, created_at, user_telegram, thread_id, type, role, content, telegram_update_id
+    FROM messages
+    WHERE user_telegram = ${user_telegram} AND thread_id = ${thread_id} AND type = ${type}
+    ORDER BY created_at ASC
+    LIMIT ${limit};
+  `;
+  return (rows as RawMessageRow[]).map(rowToMessage);
+}
+
+/**
+ * Max telegram_update_id for user messages in the thread (bot only). Used to check
+ * "is the latest user message still the one I inserted?" before sending a reply.
+ * Returns null if no user messages with telegram_update_id in the thread.
+ */
+export async function getMaxTelegramUpdateIdForThread(
+  user_telegram: string,
+  thread_id: number,
+  type: MessageType,
+): Promise<number | null> {
+  const rows = await sql`
+    SELECT MAX(telegram_update_id) AS max_id
+    FROM messages
+    WHERE user_telegram = ${user_telegram} AND thread_id = ${thread_id} AND type = ${type}
+      AND role = 'user' AND telegram_update_id IS NOT NULL;
+  `;
+  const row = rows[0] as { max_id: string | null } | undefined;
+  if (!row || row.max_id == null) return null;
+  return Number(row.max_id);
+}
+
+interface RawMessageRow {
+  id: string;
+  created_at: Date;
+  user_telegram: string;
+  thread_id: string;
+  type: string;
+  role: string;
+  content: string | null;
+  telegram_update_id: string | null;
+}
+
+function rowToMessage(row: RawMessageRow): Message {
+  return {
+    id: Number(row.id),
+    created_at: row.created_at,
+    user_telegram: row.user_telegram,
+    thread_id: Number(row.thread_id),
+    type: row.type as MessageType,
+    role: row.role as MessageRole,
+    content: row.content,
+    telegram_update_id: row.telegram_update_id != null ? Number(row.telegram_update_id) : null,
+  };
+}

package/database/start.ts

@@ -0,0 +1,133 @@
+import dotenv from "dotenv";
+import path from "path";
+
+// Local-only: try to load .env / .env.local when running tools like db:migrate.
+// In Vercel Lambdas these files don't exist, so these calls are harmless no-ops.
+const cwd = process.cwd();
+dotenv.config({ path: path.join(cwd, ".env") });
+dotenv.config({ path: path.join(cwd, "app", ".env") });
+dotenv.config({ path: path.join(cwd, ".env.local") });
+dotenv.config({ path: path.join(cwd, "app", ".env.local") });
+import { neon } from "@neondatabase/serverless";
+
+const connectionString = process.env.DATABASE_URL;
+
+if (!connectionString) {
+  // Fail fast on the server side so misconfiguration is obvious in logs.
+  throw new Error(
+    "DATABASE_URL is not set. Configure it in ./app/.env for the current Neon branch.",
+  );
+}
+
+export const sql = neon(connectionString);
+
+async function runSchemaMigrations() {
+  // users table
+  await sql`
+    CREATE TABLE IF NOT EXISTS users (
+      telegram_username   TEXT PRIMARY KEY,
+      created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      last_login_at       TIMESTAMPTZ,
+      last_tma_seen_at    TIMESTAMPTZ,
+      locale              TEXT,
+      time_zone           TEXT,
+      number_of_wallets   INTEGER NOT NULL DEFAULT 0,
+      default_wallet      BIGINT
+    );
+  `;
+
+  // wallets table
+  await sql`
+    CREATE TABLE IF NOT EXISTS wallets (
+      id                    BIGSERIAL PRIMARY KEY,
+      telegram_username     TEXT NOT NULL REFERENCES users(telegram_username),
+      wallet_address        TEXT NOT NULL,
+      wallet_blockchain     TEXT NOT NULL,
+      wallet_net            TEXT NOT NULL,
+      type                  TEXT NOT NULL,
+      label                 TEXT,
+      is_default            BOOLEAN NOT NULL DEFAULT FALSE,
+      created_at            TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      updated_at            TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      last_used_at          TIMESTAMPTZ,
+      last_seen_balance_at  TIMESTAMPTZ,
+      source                TEXT,
+      notes                 TEXT,
+      UNIQUE (telegram_username, wallet_address, wallet_blockchain, wallet_net)
+    );
+  `;
+
+  // pending_transactions table
+  await sql`
+    CREATE TABLE IF NOT EXISTS pending_transactions (
+      id                TEXT PRIMARY KEY,
+      telegram_username TEXT NOT NULL REFERENCES users(telegram_username),
+      wallet_address    TEXT NOT NULL,
+      wallet_blockchain TEXT NOT NULL,
+      wallet_net        TEXT NOT NULL,
+      payload           JSONB NOT NULL,
+      status            TEXT NOT NULL CHECK (status IN ('pending', 'confirmed', 'rejected', 'failed')),
+      created_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      updated_at        TIMESTAMPTZ NOT NULL DEFAULT NOW()
+    );
+  `;
+
+  // Helpful indexes
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_wallets_user
+      ON wallets(telegram_username);
+  `;
+
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_pending_tx_user
+      ON pending_transactions(telegram_username);
+  `;
+
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_pending_tx_status
+      ON pending_transactions(status);
+  `;
+
+  // messages table (AI: bot + TMA)
+  await sql`
+    CREATE TABLE IF NOT EXISTS messages (
+      id                  BIGSERIAL PRIMARY KEY,
+      created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+      user_telegram       TEXT NOT NULL REFERENCES users(telegram_username),
+      thread_id           BIGINT NOT NULL,
+      type                TEXT NOT NULL CHECK (type IN ('bot', 'app')),
+      role                TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'system')),
+      content             TEXT,
+      telegram_update_id  BIGINT
+    );
+  `;
+
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_messages_thread
+      ON messages(user_telegram, thread_id, type, created_at);
+  `;
+
+  await sql`
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_messages_bot_update_id
+      ON messages(user_telegram, thread_id, type, telegram_update_id)
+      WHERE telegram_update_id IS NOT NULL;
+  `;
+}
+
+let schemaInitPromise: Promise<void> | null = null;
+
+export function ensureSchema(): Promise<void> {
+  if (!schemaInitPromise) {
+    schemaInitPromise = runSchemaMigrations().catch((err) => {
+      console.error("[db] schema init failed", err);
+      schemaInitPromise = null;
+      throw err;
+    });
+  }
+  return schemaInitPromise;
+}
+
+// Schema runs at deploy via `npm run db:migrate` in buildCommand. No schema work
+// in the request path — keeps /api/telegram and other routes fast (no 504).
+

package/database/users.ts

@@ -0,0 +1,46 @@
+/**
+ * User helpers for the users table. Shared by API routes and bot.
+ * Import from ../database/users.js (e.g. from api/, telegram/, bot/).
+ */
+import { sql } from './start.js';
+
+export function normalizeUsername(raw: unknown): string {
+  if (typeof raw !== 'string') return '';
+  let s = raw.trim();
+  if (s.startsWith('@')) s = s.slice(1);
+  return s.toLowerCase();
+}
+
+export async function upsertUserFromTma(opts: {
+  telegramUsername: string;
+  locale: string | null;
+}): Promise<void> {
+  const { telegramUsername, locale } = opts;
+  if (!telegramUsername) return;
+
+  await sql`
+    INSERT INTO users (telegram_username, locale, created_at, updated_at, last_tma_seen_at)
+    VALUES (${telegramUsername}, ${locale}, NOW(), NOW(), NOW())
+    ON CONFLICT (telegram_username) DO UPDATE
+      SET locale        = EXCLUDED.locale,
+          last_tma_seen_at = NOW(),
+          updated_at    = NOW();
+  `;
+}
+
+export async function upsertUserFromBot(opts: {
+  telegramUsername: string;
+  locale: string | null;
+}): Promise<void> {
+  const { telegramUsername, locale } = opts;
+  if (!telegramUsername) return;
+
+  await sql`
+    INSERT INTO users (telegram_username, locale, created_at, updated_at, last_login_at)
+    VALUES (${telegramUsername}, ${locale}, NOW(), NOW(), NOW())
+    ON CONFLICT (telegram_username) DO UPDATE
+      SET locale        = EXCLUDED.locale,
+          last_login_at = NOW(),
+          updated_at    = NOW();
+  `;
+}

package/docs/ai_and_search_bar_input.md

@@ -0,0 +1,94 @@
+## AI & Search bar input behaviour
+
+This document describes how the text in the global AI & Search bottom bar should behave as the user types, matching the Flutter implementation.
+
+---
+
+### 1. Reference states (pictures sequence)
+
+The reference images show a sequence of states for a long line of text; they illustrate how the bar grows and then turns into a scrolling window:
+
+1. **Full text, no bar**  
+   Long multi‑line text fills a tall content area. This is effectively the raw content without the constraints of the bottom bar.
+
+2. **Initial bar: single line + arrow**  
+   - Only a single line of text is visible.  
+   - The text baseline is horizontally aligned with the apply arrow icon on the right.  
+   - There is empty space above the line; bar height is at its minimum.
+
+3. **Unconstrained multi‑line text**  
+   - Text has grown to multiple lines in a taller, unbounded view (again, this is the raw content).  
+
+4. **Growing bar: multiple lines + arrow**  
+   - The bottom bar has increased in height to show multiple lines.  
+   - As lines are added, the **space above the text shrinks**, but the **last visible line remains on the same vertical level as the arrow**.  
+   - Visually, the bar grows upwards while the arrow + last line baseline stays fixed.
+
+5. **Very long text, no bar**  
+   - The entire long text block is visible in a tall area, showing how much total content exists.
+
+6. **Capped bar height: scrolling window**  
+   - The bottom bar height is now capped (e.g. at 180 px).  
+   - The visible area becomes a **fixed‑height window** into the text:
+     - Older lines at the top continue moving up and eventually disappear under the **top edge** of the bar as more text is entered.
+     - The **last visible line stays aligned with the arrow baseline** at the bottom of the bar. The typing position does not move vertically once the bar has reached its maximum height.
+
+---
+
+### 2. Detailed behaviour by line count
+
+#### 1–7 lines: growing bar
+
+- For each new line from 1 up to 7:
+  - The **bottom bar height increases** by exactly one line height (20 px).  
+  - The height formula is:
+    \[
+    \text{height} = 20\text{ (top padding)} + N \times 20\text{ (lines)} + 20\text{ (bottom padding)}, \quad 1 \le N \le 7.
+    \]
+  - The **last line is always on the same baseline as the arrow** on the right.
+  - Visually, the bar grows **upwards**; the arrow + last line stay fixed at the bottom.
+
+#### 8 lines: text reaches the top edge
+
+- When the **8th line** appears:
+  - The text block now reaches the **top edge of the bottom bar**.  
+  - The bar height is at its **maximum** (e.g. 180 px).  
+  - All 8 lines are still visible at once, from the top edge down to the arrow.
+
+#### 9 lines: full‑height text area, one line hidden
+
+- When the **9th line** appears:
+  - The **scrollable text area is exactly 180 px high**, the same as the bar.  
+  - The **last line remains aligned with the arrow** at the bottom.  
+  - The **topmost line (1st)** is now hidden just above the top edge of the bar.  
+  - If the user scrolls, they can reveal all 9 lines, because:
+    \[
+    9 \times 20\text{ px} = 180\text{ px},
+    \]
+    so all 9 lines can fit into the bar’s full height when scrolled to the appropriate position.
+
+#### 9+ lines: fixed bar, 9‑line scrolling window
+
+- For **any number of lines ≥ 9**:
+  - The bar height stays fixed at its maximum (e.g. 180 px).  
+  - The **scrollable area always occupies the full bar height** (180 px).  
+  - At any moment:
+    - Up to **9 lines are visible** in the window.  
+    - The **bottom (last visible) line stays aligned with the arrow** while typing.  
+    - Older lines scroll upwards and are hidden above the top edge; the user can scroll to reveal them.
+
+---
+
+### 3. Implementation‑oriented summary
+
+- **Line height & padding**
+  - Line height: 20 px.
+  - Top padding: 20 px.
+  - Bottom padding: 20 px.
+
+- **Bar growth vs. scroll mode**
+  - For 1–7 lines, bar height grows; arrow + last line baseline are fixed.  
+  - From the 8th line onward, the bar stays at max height; the input switches to a scrollable window that:
+    - Always keeps the caret / last line baseline aligned with the arrow.
+    - Hides older lines under the top edge while allowing them to be revealed by scrolling.
+