ugly-app 0.1.604 → 0.1.605

package/dist/cli/version.d.ts

@@ -1,2 +1,2 @@
-export declare const CLI_VERSION = "0.1.604";
+export declare const CLI_VERSION = "0.1.605";
 //# sourceMappingURL=version.d.ts.map

package/dist/cli/version.js

@@ -1,3 +1,3 @@
 // Auto-generated by prebuild — do not edit manually
-export const CLI_VERSION = "0.1.604";
+export const CLI_VERSION = "0.1.605";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "ugly-app",
-  "version": "0.1.604",
+  "version": "0.1.605",
   "type": "module",
+  "comment:files": "Allowlist what ships to npm. dist = runtime; src = sourcemap targets (dist/*.js.map reference ../../src/); templates = CLI scaffold. Everything else at repo root (.pgdata local Postgres, coverage, assets/icons sources, test/, test-results/) is excluded by omission. The !negations strip the scaffold's installed deps + cruft (templates/node_modules is 200MB+ and must never ship). package.json/README/LICENSE ship automatically.",
+  "files": [
+    "dist",
+    "src",
+    "templates",
+    "!templates/node_modules",
+    "!templates/node_modules/**",
+    "!templates/package-lock.json",
+    "!**/.DS_Store",
+    "!**/*.log"
+  ],
   "main": "./dist/server/index.js",
   "exports": {
     ".": "./dist/server/index.js",

package/src/cli/version.ts

@@ -1,2 +1,2 @@
 // Auto-generated by prebuild — do not edit manually
-export const CLI_VERSION = "0.1.604";
+export const CLI_VERSION = "0.1.605";

package/templates/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "css.validate": false,
+  "less.validate": false,
+  "scss.validate": false
+}

package/templates/docs/architecture.md

@@ -0,0 +1,25 @@
+# Architecture
+
+ugly-app provides a typed full-stack framework:
+
+- **Shared** (`shared/api.ts`, `shared/collections.ts`, `shared/dbIndexes.ts`) — single source of truth for types and config, used by both client and server
+- **Server** (`server/index.ts`) — Express + WebSocket, all handlers get `ctx.userId: string`
+- **Client** (`client/main.tsx`) — React SPA, `createSocket()` for typed server calls, `AppProvider` for global state
+
+## Data flow
+```
+Client → socket.call('fn', input)
+  → WebSocket message to server
+  → Router dispatches to registerFunction handler
+  → Handler uses ctx.db / ctx.storage / ctx.textGen / ctx.imageGen / ctx.log
+  → Returns typed result
+  → Client receives typed output
+```
+
+## Live updates
+```
+Server writes to MongoDB
+  → MongoDB Change Stream fires on all server instances
+  → Server fans out to subscribed WebSocket clients
+  → Client trackDoc/trackDocs callbacks receive updated data
+```

package/templates/docs/auth.md

@@ -0,0 +1,40 @@
+# Authentication
+
+ugly-app handles auth via HttpOnly cookie + server-side JWT injection. No localStorage needed.
+
+## How it works
+
+1. User logs in via ugly.bot OAuth popup → `POST /auth/verify` → server sets `auth_token` HttpOnly cookie
+2. On every page load, the server reads the cookie, issues a **fresh 30-day token**, and injects it into the HTML:
+   ```html
+   <script>window.__AUTH_TOKEN__ = "eyJ..."</script>
+   ```
+3. Client reads `window.__AUTH_TOKEN__` synchronously — no extra HTTP round-trip
+4. Token is passed to `socket.connect(token)` for WebSocket authentication
+
+## Endpoints (provided by ugly-app)
+
+- `POST /auth/verify` — exchanges OAuth code for JWT, sets `auth_token` cookie
+- `GET /auth/token` — validates cookie, returns `{ token }`, refreshes cookie (useful for SPAs making background requests)
+- `POST /auth/logout` — clears the `auth_token` cookie
+- `GET /auth/url` — returns the OAuth popup URL for a given origin
+
+## Client pattern
+
+```tsx
+// Read token injected by server (set once, valid for whole session)
+const token = (window as any).__AUTH_TOKEN__
+
+// Logout
+await fetch('/auth/logout', { method: 'POST' })
+window.location.reload()
+```
+
+## Server handlers
+
+All handlers receive `ctx.userId: string` (guaranteed authenticated).
+Lazy `ctx.user: Promise<User | null>` for full user object when needed.
+
+## Token expiry
+
+Default: 30 days. Refreshed on every page load. Override via `JWT_EXPIRY_SECONDS` env var.

package/templates/docs/collections.md

@@ -0,0 +1,30 @@
+# Collections
+
+Collections are defined in `shared/collections.ts` and passed to `createApp()`.
+
+## Flags
+
+- `trackable: true` — clients can `trackDoc` / `trackDocs` on this collection
+- `public: true` — unauthenticated users can read (future: not yet enforced)
+- `cache: false` — disable client-side caching (reserved for future use)
+- `parent: 'collectionName'` — denotes a sub-collection relationship
+
+## Indexes
+
+Indexes are defined directly on the collection definition in `shared/collections.ts`:
+
+```ts
+export const collections = defineCollections({
+  post: {
+    type: {} as Post,
+    meta: { cache: true, trackable: true, public: false, cascadeFrom: null },
+    indexes: [
+      { fields: { authorId: 1, created: -1 } },  // regular index
+    ],
+  },
+});
+```
+
+After adding or modifying indexes:
+1. Run `npm run db:schema-gen` to generate a migration file
+2. Run `npm run db:migrate` to apply the migration

package/templates/docs/db-queries.md

@@ -0,0 +1,41 @@
+# DB Queries
+
+All DB operations are available on `ctx.db` in server handlers.
+
+## Read
+
+```ts
+const doc = await ctx.db.getDoc(collections.post, id)           // returns T | null
+const posts = await ctx.db.getDocs(collections.post, { authorId: ctx.userId })  // equality filter
+```
+
+## Write
+
+```ts
+await ctx.db.setDoc(collections.post, { ...dbDefaults(), id: nanoid(), title, authorId: ctx.userId })
+await ctx.db.setDocFields(collections.post, id, { title: newTitle })  // partial update
+await ctx.db.deleteDoc(collections.post, id)
+```
+
+## dbDefaults()
+
+Always spread `dbDefaults()` when creating new docs:
+```ts
+import { dbDefaults } from 'ugly-app/shared'
+{ ...dbDefaults(), id: nanoid(), ...yourFields }
+```
+
+Adds: `created: new Date()`, `updated: new Date()`.
+
+## Live updates (client)
+
+```ts
+// Single doc
+const unsub = socket.trackDoc<Post>('post', postId, (post) => setPost(post))
+
+// Collection with filter
+const unsub = socket.trackDocs<Post>('post', { authorId: userId }, (posts) => setPosts(posts))
+
+// Cleanup
+return () => unsub()
+```

package/templates/tests/e2e/app.spec.ts

@@ -0,0 +1,51 @@
+import { expect, test } from '@playwright/test';
+
+test.describe('App startup', () => {
+  test('home page loads and shows welcome text', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.getByText('Welcome')).toBeVisible();
+  });
+
+  test('home page shows login button when unauthenticated', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.getByText('Login')).toBeVisible();
+  });
+
+  test('navigating to a non-existent route returns 404', async ({ page }) => {
+    const response = await page.goto('/this-route-does-not-exist');
+    // Framework serves 404 for unmatched routes (see App.ts page route handler).
+    // Client-side routing only applies to paths registered in shared/pages.ts.
+    expect(response?.status()).toBe(404);
+  });
+});
+
+test.describe('Auth flow', () => {
+  test('auth-demo page shows login prompt when unauthenticated', async ({ page }) => {
+    await page.goto('/auth-demo');
+    await expect(page.getByText('You are not logged in.')).toBeVisible();
+    await expect(page.getByText('Login with ugly.bot')).toBeVisible();
+  });
+
+  test('login button opens OAuth popup', async ({ page, context }) => {
+    await page.goto('/auth-demo');
+
+    // Listen for a new page (popup) when clicking login
+    const popupPromise = context.waitForEvent('page');
+    await page.getByText('Login with ugly.bot').click();
+    const popup = await popupPromise;
+
+    // The popup should navigate to the ugly.bot login page. AuthDemoPage opens
+    // /oauth which redirects to /loginOAuth on ugly.bot.
+    expect(popup.url()).toContain('ugly.bot/');
+    expect(popup.url().toLowerCase()).toContain('oauth');
+    await popup.close();
+  });
+
+  test('auth/verify endpoint rejects invalid code', async ({ request }) => {
+    const response = await request.post('/auth/verify', {
+      data: { code: 'invalid-code-12345' },
+    });
+    // Should not return 200 for an invalid OAuth code
+    expect(response.status()).not.toBe(200);
+  });
+});

package/templates/tests/e2e/inspect.spec.ts

@@ -0,0 +1,81 @@
+import { expect, test } from '@playwright/test';
+import {
+  expectClean,
+  inspectWindow,
+  setDevice,
+  simulateKeyboard,
+  waitForApp,
+} from 'ugly-app/playwright';
+
+test.describe('inspect helper', () => {
+  test('clean fixture page produces empty arrays', async ({ page }) => {
+    await page.goto('/test/inspect-fixture');
+    await waitForApp(page);
+    const r = await inspectWindow(page, async () => {
+      await page.waitForTimeout(200);
+    });
+    expect(r.cls.spikes).toEqual([]);
+    expect(r.overlaps).toEqual([]);
+    expect(r.safeAreaViolations).toEqual([]);
+    await expectClean(page);
+  });
+
+  test('captures intentional CLS', async ({ page }) => {
+    await page.goto('/test/inspect-fixture?simulate=cls');
+    await waitForApp(page);
+    const r = await inspectWindow(page, async () => {
+      await page.waitForTimeout(1000);
+    });
+    expect(r.cls.spikes.length).toBeGreaterThan(0);
+    expect(r.cls.total).toBeGreaterThan(0);
+  });
+
+  test('captures overlapping interactive controls', async ({ page }) => {
+    await page.goto('/test/inspect-fixture?simulate=overlap');
+    await waitForApp(page);
+    const r = await inspectWindow(page, async () => {});
+    expect(r.overlaps.length).toBeGreaterThan(0);
+    const selectors = r.overlaps[0];
+    expect(selectors.a.selector).toMatch(/overlap-[ab]/);
+    expect(selectors.b.selector).toMatch(/overlap-[ab]/);
+  });
+
+  test('captures safe-area violations on iOS', async ({ page }) => {
+    // Seed iOS safe-area insets into localStorage before navigation so
+    // the inspect module's readSafeAreaInsets picks them up.
+    await page.addInitScript(() => {
+      localStorage.setItem(
+        '__safeAreaInsets',
+        JSON.stringify({ top: 59, right: 0, bottom: 34, left: 0 }),
+      );
+    });
+    await page.goto('/test/inspect-fixture?simulate=safearea');
+    await setDevice(page, 'ios');
+    const r = await inspectWindow(page, async () => {});
+    expect(r.safeAreaViolations.length).toBeGreaterThan(0);
+    expect(r.safeAreaViolations[0].side).toBe('b');
+  });
+
+  test('captures keyboard covering input', async ({ page }) => {
+    await page.goto('/test/inspect-fixture?simulate=keyboard');
+    await setDevice(page, 'ios');
+    const r = await inspectWindow(page, async () => {
+      await page.locator('[data-id=fixture-input]').focus();
+      await simulateKeyboard(page, 320);
+      await page.waitForTimeout(400);
+    });
+    expect(r.keyboard.coveredInputs.length).toBeGreaterThan(0);
+    expect(r.keyboard.coveredInputs[0].selector).toContain('fixture-input');
+  });
+
+  test('SPA navigation lands in route.transitions', async ({ page }) => {
+    await page.goto('/test/inspect-fixture');
+    await waitForApp(page);
+    const r = await inspectWindow(page, async () => {
+      await page.locator('[data-id=nav-to-other]').click();
+      await page.waitForTimeout(600);
+    });
+    expect(r.route.transitions.length).toBeGreaterThanOrEqual(1);
+    expect(r.route.transitions[0].to).toContain('inspect-fixture-other');
+  });
+});

package/templates/tests/e2e/scroll.spec.ts

@@ -0,0 +1,365 @@
+import { expect, test, Page } from '@playwright/test';
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Find the scrollable div (overflow-y: auto) inside a [data-id] container and return its metrics. */
+async function getScrollMetrics(page: Page, dataId: string) {
+  return page.evaluate((id) => {
+    const container = document.querySelector(`[data-id="${id}"]`);
+    if (!container) throw new Error(`Container [data-id="${id}"] not found`);
+    const divs = container.querySelectorAll('div');
+    for (const div of divs) {
+      const style = getComputedStyle(div);
+      if (
+        (style.overflowY === 'auto' || style.overflowY === 'scroll') &&
+        div.scrollHeight > 0
+      ) {
+        return {
+          scrollTop: div.scrollTop,
+          scrollHeight: div.scrollHeight,
+          clientHeight: div.clientHeight,
+          scrollWidth: div.scrollWidth,
+          clientWidth: div.clientWidth,
+        };
+      }
+    }
+    throw new Error(`No scrollable div found in [data-id="${id}"]`);
+  }, dataId);
+}
+
+/** Hover a container and scroll via mouse wheel. */
+async function wheelScroll(page: Page, dataId: string, deltaY: number) {
+  const container = page.locator(`[data-id="${dataId}"]`);
+  await container.scrollIntoViewIfNeeded();
+  await container.hover();
+  await page.mouse.wheel(0, deltaY);
+  await page.waitForTimeout(300);
+}
+
+/** Programmatically set scrollTop on the scrollable element inside a container. */
+async function setScrollTop(page: Page, dataId: string, value: number) {
+  await page.evaluate(
+    ({ id, val }) => {
+      const container = document.querySelector(`[data-id="${id}"]`);
+      if (!container) return;
+      const divs = container.querySelectorAll('div');
+      for (const div of divs) {
+        const style = getComputedStyle(div);
+        if (
+          (style.overflowY === 'auto' || style.overflowY === 'scroll') &&
+          div.scrollHeight > 0
+        ) {
+          div.scrollTop = val;
+          return;
+        }
+      }
+    },
+    { id: dataId, val: value },
+  );
+  await page.waitForTimeout(100);
+}
+
+/** Check whether the last item is scrolled into view within its scroll container. */
+async function isLastItemVisible(page: Page, dataId: string, itemText: string) {
+  return page.evaluate(
+    ({ id, text }) => {
+      const container = document.querySelector(`[data-id="${id}"]`);
+      if (!container) return false;
+      // Find all text elements containing the target text
+      const walker = document.createTreeWalker(
+        container,
+        NodeFilter.SHOW_TEXT,
+        { acceptNode: (node) => node.textContent === text ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP },
+      );
+      const textNode = walker.nextNode();
+      if (!textNode?.parentElement) return false;
+      const itemEl = textNode.parentElement;
+      // Find the scroll container
+      const divs = container.querySelectorAll('div');
+      let scrollEl: HTMLDivElement | null = null;
+      for (const div of divs) {
+        const style = getComputedStyle(div);
+        if (
+          (style.overflowY === 'auto' || style.overflowY === 'scroll') &&
+          div.scrollHeight > 0
+        ) {
+          scrollEl = div;
+          break;
+        }
+      }
+      if (!scrollEl) return false;
+      const scrollRect = scrollEl.getBoundingClientRect();
+      const itemRect = itemEl.getBoundingClientRect();
+      // Item bottom should be within the scroll container's visible area
+      return itemRect.bottom <= scrollRect.bottom + 2 && itemRect.top >= scrollRect.top - 2;
+    },
+    { id: dataId, text: itemText },
+  );
+}
+
+// ─── Setup ────────────────────────────────────────────────────────────────────
+
+test.beforeEach(async ({ page }) => {
+  await page.goto('/test/scroll');
+  await expect(page.locator('[data-id="scrollview-large"]')).toBeVisible();
+});
+
+// ─── ScrollView ───────────────────────────────────────────────────────────────
+
+test.describe('ScrollView', () => {
+  test('large list: first items are visible', async ({ page }) => {
+    const container = page.locator('[data-id="scrollview-large"]');
+    await expect(container.getByText('Item 1', { exact: true })).toBeVisible();
+    await expect(container.getByText('Item 2', { exact: true })).toBeVisible();
+  });
+
+  test('large list: content overflows container', async ({ page }) => {
+    const metrics = await getScrollMetrics(page, 'scrollview-large');
+    expect(metrics.scrollHeight).toBeGreaterThan(metrics.clientHeight);
+  });
+
+  test('large list: mouse wheel scrolling changes scrollTop', async ({
+    page,
+  }) => {
+    const before = await getScrollMetrics(page, 'scrollview-large');
+    expect(before.scrollTop).toBe(0);
+
+    await wheelScroll(page, 'scrollview-large', 300);
+
+    const after = await getScrollMetrics(page, 'scrollview-large');
+    expect(after.scrollTop).toBeGreaterThan(0);
+  });
+
+  test('large list: scrolling to bottom reveals last item', async ({
+    page,
+  }) => {
+    const visible = await isLastItemVisible(page, 'scrollview-large', 'Item 100');
+    expect(visible).toBe(false);
+
+    await setScrollTop(page, 'scrollview-large', 99999);
+
+    const visibleAfter = await isLastItemVisible(page, 'scrollview-large', 'Item 100');
+    expect(visibleAfter).toBe(true);
+  });
+
+  test('short list: all items visible without scrolling', async ({ page }) => {
+    const container = page.locator('[data-id="scrollview-short"]');
+    await expect(container.getByText('Item 1', { exact: true })).toBeVisible();
+    await expect(container.getByText('Item 2', { exact: true })).toBeVisible();
+    await expect(container.getByText('Item 3', { exact: true })).toBeVisible();
+  });
+
+  test('short list: content does not overflow', async ({ page }) => {
+    const metrics = await getScrollMetrics(page, 'scrollview-short');
+    expect(metrics.scrollHeight).toBeLessThanOrEqual(
+      metrics.clientHeight + 1,
+    );
+  });
+
+  test('scrollbar is hidden (no scrollbar gutter)', async ({ page }) => {
+    const metrics = await getScrollMetrics(page, 'scrollview-large');
+    expect(metrics.scrollWidth).toBeLessThanOrEqual(metrics.clientWidth + 1);
+  });
+});
+
+// ─── SimpleScrollView ─────────────────────────────────────────────────────────
+
+test.describe('SimpleScrollView', () => {
+  test('large list: first items are visible', async ({ page }) => {
+    const container = page.locator('[data-id="simple-large"]');
+    await container.scrollIntoViewIfNeeded();
+    await expect(container.getByText('Item 1', { exact: true })).toBeVisible();
+    await expect(container.getByText('Item 2', { exact: true })).toBeVisible();
+  });
+
+  test('large list: content overflows container', async ({ page }) => {
+    const metrics = await getScrollMetrics(page, 'simple-large');
+    expect(metrics.scrollHeight).toBeGreaterThan(metrics.clientHeight);
+  });
+
+  test('large list: mouse wheel scrolling changes scrollTop', async ({
+    page,
+  }) => {
+    const before = await getScrollMetrics(page, 'simple-large');
+    expect(before.scrollTop).toBe(0);
+
+    await wheelScroll(page, 'simple-large', 300);
+
+    const after = await getScrollMetrics(page, 'simple-large');
+    expect(after.scrollTop).toBeGreaterThan(0);
+  });
+
+  test('large list: scrolling to bottom reveals last item', async ({
+    page,
+  }) => {
+    const visible = await isLastItemVisible(page, 'simple-large', 'Item 100');
+    expect(visible).toBe(false);
+
+    await setScrollTop(page, 'simple-large', 99999);
+
+    const visibleAfter = await isLastItemVisible(page, 'simple-large', 'Item 100');
+    expect(visibleAfter).toBe(true);
+  });
+
+  test('short list: all items visible without scrolling', async ({ page }) => {
+    const container = page.locator('[data-id="simple-short"]');
+    await container.scrollIntoViewIfNeeded();
+    await expect(container.getByText('Item 1', { exact: true })).toBeVisible();
+    await expect(container.getByText('Item 2', { exact: true })).toBeVisible();
+    await expect(container.getByText('Item 3', { exact: true })).toBeVisible();
+  });
+
+  test('short list: content does not overflow', async ({ page }) => {
+    const metrics = await getScrollMetrics(page, 'simple-short');
+    expect(metrics.scrollHeight).toBeLessThanOrEqual(
+      metrics.clientHeight + 1,
+    );
+  });
+
+  test('scrollbar is hidden (no scrollbar gutter)', async ({ page }) => {
+    const metrics = await getScrollMetrics(page, 'simple-large');
+    expect(metrics.scrollWidth).toBeLessThanOrEqual(metrics.clientWidth + 1);
+  });
+
+  test('touch events are wired up', async ({ page }) => {
+    // Dispatch synthetic touch events to verify the component's listeners fire.
+    // Note: synthetic touch events don't cause actual browser scrolling,
+    // but they verify the event listeners (touchmove, touchend) are attached.
+    const fired = await page.evaluate((id) => {
+      const container = document.querySelector(`[data-id="${id}"]`);
+      if (!container) return { touchmove: false, touchend: false };
+      const divs = container.querySelectorAll('div');
+      let scrollEl: Element | null = null;
+      for (const div of divs) {
+        if (
+          getComputedStyle(div).overflowY === 'auto' ||
+          getComputedStyle(div).overflowY === 'scroll'
+        ) {
+          scrollEl = div;
+          break;
+        }
+      }
+      if (!scrollEl) return { touchmove: false, touchend: false };
+
+      const results = { touchmove: false, touchend: false };
+
+      scrollEl.addEventListener(
+        'touchmove',
+        () => {
+          results.touchmove = true;
+        },
+        { once: true },
+      );
+      scrollEl.addEventListener(
+        'touchend',
+        () => {
+          results.touchend = true;
+        },
+        { once: true },
+      );
+
+      const touch = new Touch({
+        identifier: 1,
+        target: scrollEl,
+        clientX: 200,
+        clientY: 300,
+      });
+
+      scrollEl.dispatchEvent(
+        new TouchEvent('touchstart', {
+          touches: [touch],
+          changedTouches: [touch],
+          bubbles: true,
+        }),
+      );
+
+      const moveTouch = new Touch({
+        identifier: 1,
+        target: scrollEl,
+        clientX: 200,
+        clientY: 100,
+      });
+
+      scrollEl.dispatchEvent(
+        new TouchEvent('touchmove', {
+          touches: [moveTouch],
+          changedTouches: [moveTouch],
+          bubbles: true,
+        }),
+      );
+
+      scrollEl.dispatchEvent(
+        new TouchEvent('touchend', {
+          touches: [],
+          changedTouches: [moveTouch],
+          bubbles: true,
+        }),
+      );
+
+      return results;
+    }, 'simple-large');
+
+    expect(fired.touchmove).toBe(true);
+    expect(fired.touchend).toBe(true);
+  });
+});
+
+// ─── FlatList ─────────────────────────────────────────────────────────────────
+
+test.describe('FlatList', () => {
+  test('large list: first items are visible', async ({ page }) => {
+    const container = page.locator('[data-id="flatlist-large"]');
+    await container.scrollIntoViewIfNeeded();
+    await expect(container.getByText('Item 1', { exact: true })).toBeVisible();
+    await expect(container.getByText('Item 2', { exact: true })).toBeVisible();
+  });
+
+  test('large list: content overflows container', async ({ page }) => {
+    const metrics = await getScrollMetrics(page, 'flatlist-large');
+    expect(metrics.scrollHeight).toBeGreaterThan(metrics.clientHeight);
+  });
+
+  test('large list: mouse wheel scrolling changes scrollTop', async ({
+    page,
+  }) => {
+    const before = await getScrollMetrics(page, 'flatlist-large');
+    expect(before.scrollTop).toBe(0);
+
+    await wheelScroll(page, 'flatlist-large', 300);
+
+    const after = await getScrollMetrics(page, 'flatlist-large');
+    expect(after.scrollTop).toBeGreaterThan(0);
+  });
+
+  test('large list: scrolling to bottom reveals last item', async ({
+    page,
+  }) => {
+    const visible = await isLastItemVisible(page, 'flatlist-large', 'Item 100');
+    expect(visible).toBe(false);
+
+    await setScrollTop(page, 'flatlist-large', 99999);
+
+    const visibleAfter = await isLastItemVisible(page, 'flatlist-large', 'Item 100');
+    expect(visibleAfter).toBe(true);
+  });
+
+  test('short list: all items visible without scrolling', async ({ page }) => {
+    const container = page.locator('[data-id="flatlist-short"]');
+    await container.scrollIntoViewIfNeeded();
+    await expect(container.getByText('Item 1', { exact: true })).toBeVisible();
+    await expect(container.getByText('Item 2', { exact: true })).toBeVisible();
+    await expect(container.getByText('Item 3', { exact: true })).toBeVisible();
+  });
+
+  test('short list: content does not overflow', async ({ page }) => {
+    const metrics = await getScrollMetrics(page, 'flatlist-short');
+    expect(metrics.scrollHeight).toBeLessThanOrEqual(
+      metrics.clientHeight + 1,
+    );
+  });
+
+  test('scrollbar is hidden (no scrollbar gutter)', async ({ page }) => {
+    const metrics = await getScrollMetrics(page, 'flatlist-large');
+    expect(metrics.scrollWidth).toBeLessThanOrEqual(metrics.clientWidth + 1);
+  });
+});