ugly-app 0.1.708 → 0.1.710

package/src/cli/buildWorkers.ts

@@ -222,18 +222,32 @@ function injectTitle(html: string, title: string | undefined): string {
   return html.replace(/<title>[^<]*<\/title>/, `<title>${escaped}</title>`);
 }
 
-function rewriteHtmlForBuildId(html: string, buildId: string): string {
+export function rewriteHtmlForBuildId(html: string, buildId: string): string {
   // Match `src="/path"` / `href="/path"` whose path starts with the
   // vite-emitted prefixes — `/assets/`, plus root-level static files
-  // emitted by vite to `dist/client/` (icon.png, favicon.ico, etc.).
+  // emitted by vite to `dist/client/` (fonts, maps, …).
   // Replacing only these patterns avoids accidentally clobbering
   // hrefs to `/api/...` or to external URLs.
   return html.replace(
     /(\s(?:src|href)=")\/([^"]+)"/g,
     (full, attr: string, restPath: string) => {
+      // App icons (favicon / apple-touch-icon / root images) are captured and
+      // PERSISTED by other surfaces — the mobile & desktop dock, PWA installs,
+      // the ugly.bot app-store listing. They must stay at a stable, long-lived
+      // URL, so leave them at the root path. wrapWithAssets serves root images
+      // from the current build (revalidated by etag), so the icon stays fresh
+      // without ever rotting. Moving them under the per-deploy `/{buildId}/`
+      // prefix is what made a pinned `/{oldBuildId}/icon.png` 404→SPA-HTML once
+      // the app redeployed.
+      if (restPath.match(/^[^/]+\.(?:png|ico|svg|jpg|jpeg|gif|webp)$/i)) {
+        return full;
+      }
+      // Vite chunks + non-captured root assets (fonts, source maps) are
+      // content-/build-addressed and never referenced externally, so pin them
+      // under the buildId for immutable hard-caching.
       if (
         restPath.startsWith('assets/') ||
-        restPath.match(/^[^/]+\.(?:png|ico|svg|jpg|jpeg|gif|webp|woff2?|ttf|map)$/i)
+        restPath.match(/^[^/]+\.(?:woff2?|ttf|map)$/i)
       ) {
         return `${attr}/${buildId}/${restPath}"`;
       }

package/src/cli/schemaGen.ts

@@ -4,6 +4,7 @@ import type { SchemaChange } from '../shared/SchemaDiff.js';
 import type { IndexDef } from '../shared/DB.js';
 import { disposeImportTs, importTs } from './uglyappConfig.js';
 import { checkSchemas, ensureSchemaSnapshotsTable } from '../server/SchemaCheck.js';
+import { fieldIndexStatements } from '../server/schemaIndexes.js';
 import { closePg, initPg } from '../server/NodePool.js';
 import { serializeSchema } from '../shared/SchemaSerializer.js';
 import type { z } from 'zod';
@@ -142,22 +143,12 @@ export function generateMigrationCodeForNewCollection(
   collection: string,
   indexes?: IndexDef[],
 ): string {
-  const indexStatements: string[] = [];
-  for (const idx of indexes ?? []) {
-    const fields = Object.keys(idx.fields);
-    if (idx.unique && fields.length === 1) {
-      const field = fields[0];
-      indexStatements.push(
-        `  await query(\`CREATE UNIQUE INDEX IF NOT EXISTS "idx_${collection}_${field}_unique" ON "${collection}" ((data->>'${field}'))\`);`,
-      );
-    }
-    if (idx.ttl !== undefined) {
-      const field = fields[0];
-      indexStatements.push(
-        `  await query(\`CREATE INDEX IF NOT EXISTS "idx_${collection}_${field}" ON "${collection}" ((data->>'${field}'))\`);`,
-      );
-    }
-  }
+  // Emit a `((data->>'field'))` statement for every declared single-field index
+  // — plain *and* unique. (The previous hand-rolled loop only handled unique/ttl
+  // indexes, so a plain `{ fields: { userId: 1 } }` produced no index at all.)
+  const indexStatements = fieldIndexStatements(collection, indexes).map(
+    (sql) => `  await query(\`${sql}\`);`,
+  );
 
   return `import type { query as pgQuery } from 'ugly-app/server';
 

package/src/cli/version.ts

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

package/src/native/conformance/harness.ts

@@ -346,6 +346,68 @@ const PROBES: Probe[] = [
       assert(typeof page.content === 'string', 'browse.extract gave no content');
     },
   },
+  {
+    id: 'browse.session.roundtrip',
+    category: 'stream',
+    async run(n) {
+      const s = (await n.invoke('browse.open', {
+        url: 'https://example.com/',
+        opts: { waitForSelector: 'h1' },
+      })) as { id: string; url: string; title: string };
+      assert(s && typeof s.id === 'string', 'browse.open gave no session id');
+      try {
+        const content = (await n.invoke('browse.content', { id: s.id, opts: { format: 'text' } })) as {
+          content: string;
+        };
+        assert(content.content.length > 0, 'browse.content empty');
+        const links = (await n.invoke('browse.links', { id: s.id })) as unknown[];
+        assert(Array.isArray(links), 'browse.links not an array');
+        const shot = (await n.invoke('browse.screenshot', { id: s.id })) as string;
+        assert(typeof shot === 'string' && shot.length > 100, 'browse.screenshot returned no image');
+        const info = (await n.invoke('browse.info', { id: s.id })) as { url: string };
+        assert(/example\.com/.test(info.url), `browse.info url was '${info.url}'`);
+      } finally {
+        await n.invoke('browse.close', { id: s.id }).catch(() => {});
+      }
+    },
+  },
+  {
+    id: 'browse.interact',
+    category: 'stream',
+    async run(n) {
+      const s = (await n.invoke('browse.open', { url: 'https://example.com/' })) as { id: string };
+      try {
+        // Inject a deterministic input + button so we don't depend on a third-party form.
+        await n.invoke('browse.eval', {
+          id: s.id,
+          expression: `(function(){
+            var i = document.createElement('input'); i.id = 'cf-in';
+            var b = document.createElement('button'); b.id = 'cf-btn';
+            b.onclick = function(){ window.__cf = 'clicked'; };
+            document.body.appendChild(i); document.body.appendChild(b);
+            return true;
+          })()`,
+        });
+        const found = (await n.invoke('browse.waitForSelector', {
+          id: s.id,
+          selector: '#cf-in',
+          timeoutMs: 2000,
+        })) as boolean;
+        assert(found === true, 'waitForSelector did not find injected input');
+        await n.invoke('browse.type', { id: s.id, selector: '#cf-in', text: 'hello' });
+        const typed = (await n.invoke('browse.eval', {
+          id: s.id,
+          expression: `document.querySelector('#cf-in').value`,
+        })) as string;
+        assert(typed === 'hello', `type did not set value, got '${typed}'`);
+        await n.invoke('browse.click', { id: s.id, selector: '#cf-btn' });
+        const clicked = (await n.invoke('browse.eval', { id: s.id, expression: `window.__cf || ''` })) as string;
+        assert(clicked === 'clicked', `click handler did not fire, got '${clicked}'`);
+      } finally {
+        await n.invoke('browse.close', { id: s.id }).catch(() => {});
+      }
+    },
+  },
 
   // ----- event-emitting -----
   {

package/src/native/contract-meta.browse.test.ts

@@ -0,0 +1,11 @@
+import { describe, it, expect } from 'vitest';
+import { fallbackFor } from './contract-meta.js';
+
+describe('browse namespace fallback profile', () => {
+  it('is native on ios, android, and desktop; throw on web', () => {
+    expect(fallbackFor('browse.extract', 'ios')).toBe('native');
+    expect(fallbackFor('browse.screenshot', 'android')).toBe('native');
+    expect(fallbackFor('browse.open', 'desktop')).toBe('native');
+    expect(fallbackFor('browse.open', 'web')).toBe('throw');
+  });
+});

package/src/native/contract-meta.ts

@@ -56,7 +56,7 @@ const NS_DEFAULT: Record<Namespace, [Fallback, Fallback, Fallback, Fallback]> =
   sandbox: ['throw', 'throw', 'native', 'throw'], // desktop-only (Ugly Studio daemon)
   permissions: ['native', 'native', 'native', 'native'],
   browser: ['throw', 'throw', 'native', 'throw'],
-  browse: ['throw', 'throw', 'native', 'throw'], // desktop-only (Ugly Browser)
+  browse: ['native', 'native', 'native', 'throw'], // headless webview on all shells; web has none
   mcp: ['throw', 'throw', 'native', 'throw'], // desktop-only (Studio MCP registry)
   terminal: ['throw', 'throw', 'native', 'throw'], // desktop-only (Studio PTY terminal)
   task: ['native', 'native', 'native', 'throw'], // desktop-cap; mobile/web tunnel via Ugly Proxy
@@ -143,6 +143,7 @@ const CHANNELS: Channel[] = [
   'task.stop',
   'proxy.signFingerprint',
   'proxy.verifyFingerprint',
+  'proxy.self',
   'proxy.pickHost',
   'proxy.setStatus',
   'uglybot.request',

package/src/native/contract.ts

@@ -421,6 +421,11 @@ export interface NativeContract {
     // never leaves OS secure storage — only domain-separated handshake tags are returned.
     'proxy.signFingerprint': { payload: { role: 'client' | 'host'; fingerprint: string }; result: { tag: string } };
     'proxy.verifyFingerprint': { payload: { role: 'client' | 'host'; fingerprint: string; tag: string }; result: { ok: boolean } };
+    // This device's own stable proxy identity (the deviceId/label it registers as
+    // a host under). Returns null off the native desktop shell (e.g. plain web),
+    // where there's no local filesystem to host. Used to stamp synced recent
+    // projects with the desktop that physically holds the files.
+    'proxy.self': { payload: void; result: { deviceId: string; deviceLabel: string } | null };
     // Host-picker UI — drawn by the native shell (Ugly Studio), driven by the app's
     // proxy bootstrap. pickHost shows the permission sheet; setStatus updates the drawer
     // badge + the paused/blurred disconnect overlay.

package/src/native/facades/browse.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { createBrowseFacade } from './browse.js';
+
+function mock() {
+  const calls: Array<{ channel: string; payload: unknown }> = [];
+  let ensureCount = 0;
+  const invoke = async (channel: string, payload: unknown): Promise<unknown> => {
+    calls.push({ channel, payload });
+    if (channel === 'browse.open' || channel === 'browse.navigate' || channel === 'browse.info')
+      return { id: 's1', url: 'u', title: 't' };
+    if (channel === 'browse.extract' || channel === 'browse.content')
+      return { url: 'u', title: 't', format: 'readability', content: '', length: 0 };
+    if (channel === 'browse.links') return [];
+    if (channel === 'browse.waitForSelector') return true;
+    if (channel === 'browse.screenshot') return 'data:image/png;base64,AAAA';
+    return undefined;
+  };
+  const ensure = async (): Promise<void> => {
+    ensureCount += 1;
+  };
+  return { calls, facade: createBrowseFacade(invoke, ensure), ensureCount: () => ensureCount };
+}
+
+describe('browse facade → channel mapping', () => {
+  it('maps every method to its channel + payload and gates each on ensure()', async () => {
+    const m = mock();
+    const { facade, calls } = m;
+    await facade.extract('https://x/', { format: 'html' });
+    await facade.open('https://x/', { waitMs: 10 });
+    await facade.navigate('s1', 'https://y/');
+    await facade.click('s1', '#a');
+    await facade.type('s1', '#a', 'hi', { clear: true, submit: true });
+    await facade.waitForSelector('s1', '#a', 500);
+    await facade.content('s1', { format: 'text' });
+    await facade.links('s1');
+    await facade.eval('s1', '1+1');
+    await facade.screenshot('s1');
+    await facade.info('s1');
+    await facade.close('s1');
+
+    expect(calls.map((c) => c.channel)).toEqual([
+      'browse.extract',
+      'browse.open',
+      'browse.navigate',
+      'browse.click',
+      'browse.type',
+      'browse.waitForSelector',
+      'browse.content',
+      'browse.links',
+      'browse.eval',
+      'browse.screenshot',
+      'browse.info',
+      'browse.close',
+    ]);
+    expect(calls[0].payload).toEqual({ url: 'https://x/', opts: { format: 'html' } });
+    expect(calls[2].payload).toEqual({ id: 's1', url: 'https://y/', opts: undefined });
+    expect(calls[3].payload).toEqual({ id: 's1', selector: '#a' });
+    expect(calls[4].payload).toEqual({ id: 's1', selector: '#a', text: 'hi', opts: { clear: true, submit: true } });
+    expect(calls[5].payload).toEqual({ id: 's1', selector: '#a', timeoutMs: 500 });
+    expect(calls[8].payload).toEqual({ id: 's1', expression: '1+1' });
+    // ensure() fires once per call (12 calls).
+    expect(m.ensureCount()).toBe(12);
+  });
+});

package/src/native/proxy.ts

@@ -79,6 +79,10 @@ export function enableUglyProxy(opts: {
   let connecting: Promise<boolean> | null = null;
   let lastLabel: string | undefined;
   let forceRepick = false;
+  // When set, the next connect targets this specific host (bypassing the picker).
+  // Driven by the 'proxy:connect' event — e.g. opening a recent project that's
+  // stamped with the desktop it lives on, so the phone reaches the right host.
+  let preferredHost: string | null = null;
 
   const setStatus = (state: string, hostLabel?: string): void => {
     void native.invoke('proxy.setStatus' as never, { state, hostLabel } as never).catch(() => {});
@@ -89,14 +93,16 @@ export function enableUglyProxy(opts: {
     if (connecting) return connecting;
     connecting = (async () => {
       try {
-        const existing = forceRepick ? null : client.hostDeviceId();
-        console.error('[uglyproxy] ensureConnected: start', { existing, forceRepick });
+        // A pinned host (preferredHost) wins over the cached one and the picker.
+        const existing = preferredHost ?? (forceRepick ? null : client.hostDeviceId());
+        console.error('[uglyproxy] ensureConnected: start', { existing, preferredHost, forceRepick });
         if (existing) {
-          // Silent reconnect to the previously chosen host.
+          // Direct (re)connect to the cached or pinned host — no picker.
           setStatus('reconnecting', lastLabel);
           await client.connect(existing);
           setStatus('connected', lastLabel);
-          console.error('[uglyproxy] ensureConnected: reconnected', { existing });
+          preferredHost = null;
+          console.error('[uglyproxy] ensureConnected: connected', { existing });
           return true;
         }
         forceRepick = false;
@@ -125,13 +131,26 @@ export function enableUglyProxy(opts: {
   }
 
   // The native drawer's "switch desktop" pill emits this — drop the current host and
-  // re-run the picker.
+  // re-run the picker. Clear any pin so the user's repick isn't overridden.
   native.subscribe('proxy:switch' as never, (() => {
     forceRepick = true;
+    preferredHost = null;
     client.close();
     void ensureConnected();
   }) as never);
 
+  // Pin to a specific host (e.g. opening a recent project stamped with its
+  // desktop). If we're connected elsewhere, drop it so the pinned target wins.
+  native.subscribe('proxy:connect' as never, ((data: unknown) => {
+    const d = data as { deviceId?: string; label?: string } | undefined;
+    if (!d?.deviceId) return;
+    preferredHost = d.deviceId;
+    if (d.label) lastLabel = d.label;
+    forceRepick = false;
+    if (client.isOpen() && client.hostDeviceId() !== d.deviceId) client.close();
+    void ensureConnected();
+  }) as never);
+
   // task.event:<id> subscriptions need a host-side fanout handshake (task.listen) — unlike
   // process/net streams, whose fanout is registered by the spawning invoke. Ref-count per
   // task id so N local subscribers share one host subscription (no duplicate event delivery).

package/src/server/PostgresSchema.ts

@@ -7,6 +7,8 @@
  */
 
 import { getPool } from './Pg.js';
+import { fieldIndexStatements } from './schemaIndexes.js';
+import type { IndexDef } from '../shared/DB.js';
 
 const VALID_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 
@@ -17,10 +19,14 @@ function assertSafeName(name: string): void {
 }
 
 /**
- * Create the collection table + its default JSONB GIN index if they
- * don't exist. Idempotent.
+ * Create the collection table, its default JSONB GIN index, and the btree
+ * expression indexes the collection declares (so `WHERE data->>'field' = $1`
+ * lookups stay index-served instead of seq-scanning). All idempotent.
  */
-export async function ensureTable(collection: string): Promise<void> {
+export async function ensureTable(
+  collection: string,
+  indexes?: IndexDef[],
+): Promise<void> {
   assertSafeName(collection);
   const pool = getPool();
   await pool.query(
@@ -36,6 +42,17 @@ export async function ensureTable(collection: string): Promise<void> {
     `CREATE INDEX IF NOT EXISTS "idx_${collection}_data"
      ON "${collection}" USING GIN (data)`,
   );
+  // Declared field indexes — isolate each so a single failure (e.g. a UNIQUE
+  // index over pre-existing duplicate data) never aborts the rest of the sync.
+  for (const sql of fieldIndexStatements(collection, indexes)) {
+    try {
+      await pool.query(sql);
+    } catch (err) {
+      console.warn(
+        `[PostgresSchema] field index skipped for "${collection}": ${(err as Error).message}`,
+      );
+    }
+  }
 }
 
 export async function tableExists(collection: string): Promise<boolean> {

package/src/server/SchemaCheck.ts

@@ -40,11 +40,15 @@ async function loadSnapshots(): Promise<Record<string, SchemaDescriptor>> {
   return snapshots;
 }
 
-async function upsertSnapshot(name: string, descriptor: SchemaDescriptor): Promise<void> {
+async function upsertSnapshot(
+  name: string,
+  descriptor: SchemaDescriptor,
+  indexes?: IndexDef[],
+): Promise<void> {
   // Invariant: a stored snapshot must imply the table exists. ensureTable is
   // idempotent (CREATE TABLE IF NOT EXISTS + CREATE INDEX IF NOT EXISTS) on
   // the data-proxy side, so this is safe to call on every snapshot write.
-  await ensureTable(name);
+  await ensureTable(name, indexes);
   await Postgres.query(
     `INSERT INTO _schema_snapshots (collection, schema_json, updated_at)
      VALUES ($1, $2, NOW())
@@ -60,11 +64,12 @@ export async function updateAllSnapshots(
     if (!def.schema) continue;
     // Getter-backed collections have no local table — skip schema snapshots.
     if (def.meta?.getter) continue;
+    const indexes = (def as { indexes?: IndexDef[] }).indexes;
     const descriptor = serializeSchema(
       def.schema as z.ZodObject<z.ZodRawShape>,
-      (def as { indexes?: IndexDef[] }).indexes,
+      indexes,
     );
-    await upsertSnapshot(name, descriptor);
+    await upsertSnapshot(name, descriptor, indexes);
   }
 }
 
@@ -175,8 +180,8 @@ export async function autoMigrateNewCollections(
   `);
 
   for (const name of newCollections) {
-    // 1. Create the table via data proxy
-    await ensureTable(name);
+    // 1. Create the table via data proxy (+ its declared field indexes)
+    await ensureTable(name, (defs[name] as { indexes?: IndexDef[] })?.indexes);
 
     // 2. Skip writing a new file if a schema migration for this collection already exists.
     // Auto-baseline can be triggered whenever the _schema_snapshots row is missing

package/src/server/adapter/workers/createWorkersApp.ts

@@ -65,7 +65,8 @@ import type {
   WorkerHandlers,
   WorkerRegistry,
 } from '../../../shared/Api.js';
-import type { CollectionDefRegistry } from '../../../shared/DB.js';
+import type { CollectionDefRegistry, IndexDef } from '../../../shared/DB.js';
+import { fieldIndexStatements } from '../../schemaIndexes.js';
 import { getUglyBotUrl } from '../../../shared/uglyBotUrl.js';
 import type { DbAdapter, PubSubMessage, ServerAdapter } from '../types.js';
 import type { QueueMessage, WorkersEnv } from './cf-types.js';
@@ -1600,6 +1601,17 @@ export function createWorkersApp<R extends AppRegistryBase>(
         await db.query(
           `CREATE INDEX IF NOT EXISTS "idx_${name}_data" ON "${name}" USING GIN (data)`,
         );
+        // Declared btree expression indexes (`((data->>'field'))`) — without
+        // these, `WHERE data->>'field' = $1` reads seq-scan and hang at scale.
+        // Isolate each so one bad index never fails the whole schema sync.
+        const indexes = (ctx.collections?.[name] as { indexes?: IndexDef[] } | undefined)?.indexes;
+        for (const sql of fieldIndexStatements(name, indexes)) {
+          try {
+            await db.query(sql);
+          } catch (err) {
+            console.warn(`[/_init] field index skipped for "${name}": ${(err as Error).message}`);
+          }
+        }
         created.push(name);
       }
       return c.json({ ok: true, ensured: created });

package/src/server/schemaIndexes.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import { fieldIndexStatements } from './schemaIndexes';
+
+describe('fieldIndexStatements', () => {
+  // Regression: the dock-app prod hang. A plain `{ fields: { userId: 1 } }` index
+  // declaration produced NO `((data->>'userId'))` btree index (schemaGen only
+  // handled unique/ttl), so `WHERE data->>'userId' = $1` seq-scanned and hung.
+  it('emits a btree expression index for a plain single-field index', () => {
+    const sql = fieldIndexStatements('dockApp', [{ fields: { userId: 1 } }]);
+    expect(sql).toEqual([
+      `CREATE INDEX IF NOT EXISTS "idx_dockApp_userId" ON "dockApp" ((data->>'userId'))`,
+    ]);
+  });
+
+  it('emits a UNIQUE index (with _unique suffix) for a unique index', () => {
+    const sql = fieldIndexStatements('emailAccount', [{ fields: { email: 1 }, unique: true }]);
+    expect(sql).toEqual([
+      `CREATE UNIQUE INDEX IF NOT EXISTS "idx_emailAccount_email_unique" ON "emailAccount" ((data->>'email'))`,
+    ]);
+  });
+
+  it('emits one statement per declared index', () => {
+    const sql = fieldIndexStatements('voice', [
+      { fields: { userId: 1 } },
+      { fields: { provider: 1 } },
+    ]);
+    expect(sql).toHaveLength(2);
+    expect(sql[1]).toContain(`((data->>'provider'))`);
+  });
+
+  it('skips composite (multi-field) indexes — single-field only', () => {
+    expect(fieldIndexStatements('x', [{ fields: { a: 1, b: 1 } }])).toEqual([]);
+  });
+
+  it('returns [] for no/empty indexes', () => {
+    expect(fieldIndexStatements('x')).toEqual([]);
+    expect(fieldIndexStatements('x', [])).toEqual([]);
+  });
+
+  it('refuses unsafe collection/field names (no SQL injection surface)', () => {
+    expect(fieldIndexStatements('bad-name', [{ fields: { userId: 1 } }])).toEqual([]);
+    expect(fieldIndexStatements('ok', [{ fields: { 'a; DROP TABLE x': 1 } }])).toEqual([]);
+  });
+});

package/src/server/schemaIndexes.ts

@@ -0,0 +1,44 @@
+/**
+ * Single source of truth for the btree expression indexes a collection declares
+ * via `indexes: [{ fields: { <field>: 1 } }]`.
+ *
+ * The default `idx_<c>_data` GIN index covers JSONB containment (`data @> …`),
+ * but it CANNOT serve the scalar lookups the query layer actually emits
+ * (`translateFilter` builds `WHERE data->>'field' = $1`). Without a matching
+ * `((data->>'field'))` btree index, every filtered read on the collection
+ * sequential-scans — invisible on a small table, a hang once it grows past the
+ * 30s statement_timeout.
+ *
+ * Pure string-builder (no pg/pool imports) so it's safe to share across the Node
+ * schema sync (`PostgresSchema.ensureTable`), the Workers `/_init` route, and the
+ * migration generator (`schemaGen`). Statements are idempotent (IF NOT EXISTS) so
+ * every call site can run them on every deploy.
+ */
+import type { IndexDef } from '../shared/DB.js';
+
+const VALID_NAME = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+
+/** Raw `CREATE [UNIQUE] INDEX` SQL for each declared single-field index. */
+export function fieldIndexStatements(
+  collection: string,
+  indexes?: IndexDef[],
+): string[] {
+  if (!VALID_NAME.test(collection)) return [];
+  const out: string[] = [];
+  for (const idx of indexes ?? []) {
+    const fields = Object.keys(idx.fields);
+    // Single-field expression indexes only — matches the query layer, which
+    // filters one JSONB field at a time. (Composite indexes aren't emitted.)
+    if (fields.length !== 1) continue;
+    const field = fields[0];
+    if (!VALID_NAME.test(field)) continue;
+    const unique = idx.unique ? 'UNIQUE ' : '';
+    const name = idx.unique
+      ? `idx_${collection}_${field}_unique`
+      : `idx_${collection}_${field}`;
+    out.push(
+      `CREATE ${unique}INDEX IF NOT EXISTS "${name}" ON "${collection}" ((data->>'${field}'))`,
+    );
+  }
+  return out;
+}