@revenexx/studio-commerce-devkit 0.1.1

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2026 revenexx GmbH. All rights reserved.
+
+This software is proprietary and confidential. It is part of revenexx Studio and
+may be used only under the terms of the revenexx Studio license.
+
+Full license terms: https://studio.revenexx.design/license

package/README.md

@@ -0,0 +1,104 @@
+# Commerce Studio — standalone dev host (app building)
+
+Run the **Commerce Studio UI on its own** to build apps: point it at your
+`../apps/` and it renders each app's `cockpit.json` **with realistic mock
+data** — no platform, no backend, no auth. Edit the manifest, reload, iterate.
+
+## What this is
+
+A thin Nuxt host around the publishable
+[`@revenexx/studio-commerce`](../../packages/studio-commerce) module — the same
+manifest-driven AppRenderer the cockpit runs. The renderer is unchanged; all the
+"local" magic is two **Nitro shims** in this host that speak the cockpit's exact
+wire contracts:
+
+```
+ browser ──https──► commerce-studio.rvnxx.test  (this Nuxt host)
+   useInstalledApps  →  GET /api/v1/tenants/:slug/apps   ─┐
+   usePostgrest      →  /pg/{vendor}__{app}__{entity}    ─┤ served locally
+                                                          ▼
+   server/utils/commerce.ts:  reads ../apps/<app>/{manifest,cockpit,schema}.json
+                              + an in-memory store seeded with fake rows
+```
+
+- **Console shim** (`server/routes/api/v1/tenants/[slug]/apps.get.ts`) assembles
+  `InstalledAppRecord[]` from disk **per request** — so editing a `cockpit.json`
+  and reloading reflects immediately.
+- **PostgREST shim** (`server/routes/pg/[entity].ts`) serves list/get/create/
+  update/delete over an in-memory store built generically from each
+  `schema.json`, seeded with plausible fake rows (column types, `CHECK` enums,
+  FK `references`), with a `Content-Range` total.
+- Media picker + Baseline-IO are **stubbed** (standalone has no Storage/IO
+  service); everything else renders and round-trips against the mock.
+
+## Quick start
+
+```bash
+cd revenexx-cockpit
+export GITHUB_TOKEN=ghp_xxx        # read:packages (for @revenexx/studio*)
+docker compose -f apps/commerce-studio-dev/docker-compose.dev.yml up
+```
+
+Open **https://commerce-studio.rvnxx.test** → redirects to `/commerce`. The
+sidebar lists every app under `../apps/`; open one (e.g. **inventories** or
+**products**) and its list/detail/form/widget views render from `cockpit.json`
+with mock rows. Create/edit persist in-memory for the session.
+
+**Host mode (no Docker):**
+```bash
+export APPS_DIR=/absolute/path/to/playground/apps   # optional; default is ../../../apps
+pnpm --filter commerce-studio-dev dev               # http://localhost:3000
+```
+
+## The app-building loop
+
+1. Edit your app under `../apps/<app>/`:
+   - `cockpit.json` — navigation / list / detail / form / widget views (the UI).
+   - `schema.json` — entities + columns (drives the mock data + Data Model page).
+2. Reload the studio → the manifest is re-read and re-rendered. No rebuild.
+3. Iterate. When happy, the same `cockpit.json` renders identically in the real
+   cockpit (this host runs the exact same module).
+
+## Config (`nuxt.config.ts` runtimeConfig.public)
+
+| Key | Default | Purpose |
+|---|---|---|
+| `consoleApi` | `''` (same-origin) | `useInstalledApps` → the Console shim |
+| `postgrestApi` | `/pg` | `usePostgrest` → the PostgREST shim |
+| `devToken` / `devTenant` | `dev` | Standalone platform-provider (any non-empty token unlocks the shims) |
+| `APPS_DIR` (env) | `../../../apps` (host) / `/apps` (compose) | Where apps are read from |
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Empty sidebar / no apps | `APPS_DIR` wrong, or apps have no `cockpit.json`. Container mounts `../../../apps` → `/apps`. |
+| List views empty | The entity has no `schema.json` columns, or a `CHECK`/reference the generator couldn't seed — check `server/utils/commerce.ts`. |
+| A media field is inert | By design (standalone stub) — the real Storage picker is cockpit-only. |
+| Import/Export missing on a view | By design — Baseline-IO is stubbed standalone (`useCommerceIo` returns null). |
+
+## Use it from your own app repo (published: `@revenexx/studio-commerce-devkit`)
+
+Once the studio packages are published to GitHub Packages, an app author works
+entirely inside their app repo — no cockpit checkout:
+
+```bash
+cd apps/products                              # your app repo (has cockpit.json)
+pnpm add -D @revenexx/studio-commerce-devkit
+pnpm commerce-studio                          # → http://localhost:3030 → /commerce
+```
+
+The `commerce-studio` bin boots this preview app (from `node_modules`) with
+`APPS_DIR` = your cwd, so it renders **your** app from `cockpit.json` with mock
+data. Preview the whole set instead: `APPS_DIR=/path/to/apps pnpm commerce-studio`.
+Requires the `@revenexx` registry in `.npmrc` (+ a `read:packages` token), same
+as any `@revenexx/*` install. Build output goes to `.commerce-studio/` in your
+app (gitignore it).
+
+## Notes
+
+- Mock data is in-memory and regenerated on server restart; it's for *seeing the
+  UI*, not persistence. A real local Postgres/PostgREST (from `schema.json` DDL)
+  is a deferred option if you need real constraints/RLS.
+- This same package doubles as the in-workspace dev host (the `docker compose`
+  above) and the published `@revenexx/studio-commerce-devkit` app-dev tool.

package/app/app.vue

@@ -0,0 +1,5 @@
+<template>
+  <NuxtLayout>
+    <NuxtPage />
+  </NuxtLayout>
+</template>

package/app/layouts/default.vue

@@ -0,0 +1,18 @@
+<script setup lang="ts">
+/**
+ * Minimal standalone shell — no cockpit IconRail/TopBar. Gives the commerce
+ * pages' `<CommerceLayout>` (its own sidebar shelf) a full-viewport height
+ * context. A thin top strip stands in for the cockpit chrome.
+ */
+</script>
+
+<template>
+  <div class="flex h-screen w-screen flex-col overflow-hidden bg-background text-foreground">
+    <header class="flex h-9 shrink-0 items-center gap-2 px-3 text-mono text-muted-foreground">
+      Commerce Studio · standalone app-building
+    </header>
+    <div class="min-h-0 flex-1">
+      <slot />
+    </div>
+  </div>
+</template>

package/app/pages/index.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+// The Commerce Studio lives at /commerce (registered by the module). An index
+// page also enables Nuxt's router so the module's extendPages routes mount.
+onMounted(() => {
+  navigateTo('/commerce')
+})
+</script>
+
+<template>
+  <div class="grid h-full place-items-center text-muted-foreground">
+    Loading Commerce Studio…
+  </div>
+</template>

package/bin/preview.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * `commerce-studio` — boot the Commerce Studio preview against your app.
+ *
+ * Run from an app repo (where `cockpit.json` lives) after adding
+ * `@revenexx/studio-commerce-devkit` as a devDependency:
+ *
+ *   pnpm add -D @revenexx/studio-commerce-devkit
+ *   pnpm commerce-studio            # → http://localhost:3030 → /commerce
+ *
+ * It runs this package's Nuxt app (from node_modules) with APPS_DIR pointed at
+ * your current directory, so the studio renders your app from disk with mock
+ * data — no platform, no backend. Preview several apps by pointing APPS_DIR at
+ * the apps root: `APPS_DIR=/path/to/apps pnpm commerce-studio`.
+ */
+import { spawnSync } from 'node:child_process'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const pkgDir = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const cwd = process.cwd()
+
+const env = {
+  ...process.env,
+  // Your app repo (or the apps root) — the studio reads manifests from here.
+  APPS_DIR: process.env.APPS_DIR || cwd,
+  // Keep Nuxt's build output out of node_modules, in your project.
+  NUXT_STUDIO_BUILDDIR: process.env.NUXT_STUDIO_BUILDDIR || resolve(cwd, '.commerce-studio'),
+}
+const port = process.env.PORT || '3030'
+
+const res = spawnSync('npx', ['nuxi', 'dev', pkgDir, '--port', port], { stdio: 'inherit', env })
+process.exit(res.status ?? 1)

package/nuxt.config.ts

@@ -0,0 +1,105 @@
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { addTemplate } from '@nuxt/kit'
+import tailwindcss from '@tailwindcss/vite'
+
+/**
+ * Standalone dev host for the Commerce Studio (app building).
+ *
+ * Extends `@revenexx/studio-shared` (shell primitives + standalone platform
+ * provider) and loads `@revenexx/studio-commerce` — the same AppRenderer the
+ * cockpit runs. It renders any app under `APPS_DIR` from that app's
+ * `cockpit.json`, with data served by two local Nitro shims:
+ *   - `GET /api/v1/tenants/:slug/apps` → InstalledAppRecord[] assembled from
+ *     each `APPS_DIR/<app>/{manifest,cockpit,schema}.json`
+ *   - `/pg/{entity}` → PostgREST-compatible mock store seeded from schema.json
+ * No platform, no CORS (same-origin), no auth (dev token). Edit a cockpit.json
+ * and reload — the manifest is read per request.
+ *
+ * Everything resolves by PACKAGE NAME (not monorepo-relative paths), so this
+ * works both in-repo and when installed from npm as
+ * `@revenexx/studio-commerce-devkit`.
+ */
+// Locate a package's install directory on the filesystem (walk up node_modules
+// from this config). Avoids `require.resolve`, whose exports/conditions the
+// studio packages don't expose for CJS or for `./package.json`. Works in the
+// monorepo and when installed from npm (pnpm symlinks are followed).
+const configDir = dirname(fileURLToPath(import.meta.url))
+function pkgDir(name: string): string {
+  let base = configDir
+  for (;;) {
+    const candidate = join(base, 'node_modules', name)
+    if (existsSync(join(candidate, 'package.json'))) return candidate
+    const parent = dirname(base)
+    if (parent === base) throw new Error(`Cannot locate ${name} in any node_modules`)
+    base = parent
+  }
+}
+
+// Absolute source dirs the Tailwind JIT must scan (design system + shell
+// primitives + the studio-commerce module runtime), resolved from wherever the
+// packages are installed — no fragile relative `@source` paths.
+const studioTailwindSources = [
+  join(pkgDir('@revenexx/studio'), 'dist'),
+  join(pkgDir('@revenexx/studio-shared'), 'components'),
+  join(pkgDir('@revenexx/studio-commerce'), 'dist', 'runtime'),
+]
+
+export default defineNuxtConfig({
+  ssr: false,
+  // When run via the `commerce-studio` bin from an app repo, keep Nuxt's build
+  // output in the app's cwd instead of node_modules.
+  ...(process.env.NUXT_STUDIO_BUILDDIR ? { buildDir: process.env.NUXT_STUDIO_BUILDDIR } : {}),
+  extends: ['@revenexx/studio-shared'],
+  modules: [
+    '@solar-icons/nuxt',
+    '@revenexx/studio-commerce',
+    // Generate the Tailwind entry with absolute @source paths (see above) and
+    // register it as the app's stylesheet.
+    (_options, nuxt) => {
+      const tpl = addTemplate({
+        filename: 'studio-tailwind.css',
+        write: true,
+        getContents: () => [
+          '@import "tailwindcss";',
+          '@import "tw-animate-css";',
+          '@import "@revenexx/studio/tokens";',
+          '@import "@revenexx/studio/fonts";',
+          ...studioTailwindSources.map(s => `@source "${s}";`),
+          '@custom-variant dark (&:is(.dark *));',
+          '@theme inline { --font-sans: "Flink Neue Condensed", ui-sans-serif, system-ui, sans-serif; }',
+          '@layer base { * { @apply border-border outline-ring/50; } body { @apply bg-background text-foreground; } }',
+          '@utility text-mono { font-family: "Flink Neue Condensed", system-ui, sans-serif; font-weight: 500; letter-spacing: 0.08em; text-transform: uppercase; font-size: 0.6875rem; line-height: 1.15; }',
+        ].join('\n'),
+      })
+      nuxt.options.css.push(tpl.dst)
+    },
+  ],
+  vite: {
+    plugins: [tailwindcss()],
+    server: {
+      allowedHosts: ['commerce-studio.rvnxx.test', 'localhost'],
+    },
+  },
+  solarIcons: {
+    namePrefix: 'Solar',
+    autoImport: true,
+    provider: true,
+    color: 'currentColor',
+    size: 18,
+    weight: 'BoldDuotone',
+  },
+  runtimeConfig: {
+    public: {
+      // Same-origin local shims (served by this host's server/routes):
+      consoleApi: '',
+      postgrestApi: '/pg',
+      // Standalone platform provider (any non-empty token unlocks the shims):
+      devToken: 'dev',
+      devTenant: 'dev',
+    },
+  },
+  devtools: { enabled: true },
+  compatibilityDate: '2025-01-01',
+})

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@revenexx/studio-commerce-devkit",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Preview any revenexx app locally in the Commerce Studio: renders the app's cockpit.json with mock data, no platform. Add as a devDependency and run `commerce-studio` from your app repo.",
+  "bin": {
+    "commerce-studio": "./bin/preview.mjs"
+  },
+  "files": [
+    "nuxt.config.ts",
+    "app",
+    "server",
+    "bin",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "@revenexx/studio": "^0.1.2",
+    "@solar-icons/nuxt": "^1.2.0",
+    "@tailwindcss/vite": "^4.1.18",
+    "nuxt": "^4.2.2",
+    "tailwindcss": "^4.1.18",
+    "tw-animate-css": "^1.4.0",
+    "vue": "^3.5.26",
+    "vue-router": "^4.6.4",
+    "@revenexx/studio-commerce": "0.1.1",
+    "@revenexx/studio-shared": "0.1.1"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "scripts": {
+    "dev": "nuxt dev",
+    "build": "nuxt build"
+  }
+}

package/server/routes/api/v1/tenants/[slug]/apps.get.ts

@@ -0,0 +1,7 @@
+// Console shim: the cockpit's `useInstalledApps` calls
+// `GET {consoleApi}/api/v1/tenants/{slug}/apps`. We assemble the same
+// InstalledAppRecord[] from the apps on disk, per request (edit a manifest +
+// reload → reflected).
+export default defineEventHandler(() => {
+  return { data: loadApps() }
+})

package/server/routes/pg/[entity].ts

@@ -0,0 +1,58 @@
+import { randomUUID } from 'node:crypto'
+
+/**
+ * PostgREST shim over the in-memory mock store. The cockpit's `usePostgrest`
+ * hits `{postgrestApi}/{qualified_entity}?…`; here `postgrestApi=/pg`, so this
+ * catch-all serves list/get/create/update/delete with a Content-Range total —
+ * the same wire contract Baseline's PostgREST provides. No auth is enforced.
+ */
+export default defineEventHandler(async (event) => {
+  const entity = getRouterParam(event, 'entity') || ''
+  const query = getQuery(event) as Record<string, any>
+  const method = event.method
+
+  const def = pgResolve(entity)
+  if (!def) {
+    setResponseStatus(event, 404)
+    return { message: `Unknown entity ${entity}` }
+  }
+
+  // id filter (`?id=eq.<id>`) drives get/update/delete.
+  const idFilter = typeof query[def.pk] === 'string' && query[def.pk].startsWith('eq.')
+    ? String(query[def.pk]).slice(3)
+    : null
+
+  if (method === 'GET') {
+    const { rows, total } = pgQuery(entity, query)
+    const offset = query.offset ? Number(query.offset) : 0
+    setResponseHeader(event, 'Content-Range', rows.length ? `${offset}-${offset + rows.length - 1}/${total}` : `*/${total}`)
+    return rows
+  }
+
+  if (method === 'POST') {
+    const body = (await readBody(event)) as Record<string, any>
+    const row = { ...body }
+    if (!row[def.pk]) row[def.pk] = randomUUID()
+    def.rows.unshift(row)
+    setResponseStatus(event, 201)
+    return [row]
+  }
+
+  if (method === 'PATCH') {
+    const body = (await readBody(event)) as Record<string, any>
+    const idx = def.rows.findIndex(r => String(r[def.pk]) === idFilter)
+    if (idx < 0) { setResponseStatus(event, 404); return [] }
+    def.rows[idx] = { ...def.rows[idx], ...body }
+    return [def.rows[idx]]
+  }
+
+  if (method === 'DELETE') {
+    const idx = def.rows.findIndex(r => String(r[def.pk]) === idFilter)
+    if (idx >= 0) def.rows.splice(idx, 1)
+    setResponseStatus(event, 204)
+    return null
+  }
+
+  setResponseStatus(event, 405)
+  return { message: 'Method not allowed' }
+})

package/server/utils/commerce.ts

@@ -0,0 +1,244 @@
+/**
+ * App-building dev backend — reads apps from disk and serves a mock data plane
+ * that speaks the same shapes the cockpit's Console + PostgREST clients expect.
+ *
+ * - `loadApps()` assembles `InstalledAppRecord[]` from each app's manifest,
+ *   cockpit and schema JSON under APPS_DIR (per call → edit + reload reflects).
+ * - `getStore()` builds an in-memory store keyed by the qualified entity name
+ *   `{vendor}__{app}__{entity}`, seeded with plausible fake rows derived from
+ *   each `schema.json`. It's PostgREST-compatible: list/get/create/update/delete
+ *   + select/order/limit/offset/filter translation + a Content-Range total.
+ */
+import { readdirSync, readFileSync, statSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+export function appsDir(): string {
+  // Container: set APPS_DIR=/apps (mounted). Host `pnpm dev`: cwd is this
+  // package dir, so the sibling apps repo is three levels up
+  // (commerce-studio-dev → apps → revenexx-cockpit → playground/apps).
+  return process.env.APPS_DIR || join(process.cwd(), '..', '..', '..', 'apps')
+}
+
+interface RawApp {
+  folder: string
+  manifest: Record<string, any>
+  cockpit: Record<string, any>
+  schema: { entities?: Record<string, any> }
+}
+
+function readJson(path: string): Record<string, any> | null {
+  try {
+    return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null
+  }
+  catch {
+    return null
+  }
+}
+
+function readOneApp(base: string, folder: string): RawApp | null {
+  const cockpit = readJson(join(base, 'cockpit.json'))
+  if (!cockpit) return null // not a renderable app
+  return {
+    folder,
+    manifest: readJson(join(base, 'manifest.json')) ?? {},
+    cockpit,
+    schema: (readJson(join(base, 'schema.json')) as any) ?? { entities: {} },
+  }
+}
+
+/**
+ * Apps on disk with a cockpit.json. `APPS_DIR` may point at either the apps
+ * ROOT (multi-app: iterate subdirs) or a SINGLE app dir (has cockpit.json
+ * directly — the `pnpm add -D @revenexx/studio-commerce-devkit` case, run
+ * from inside your app repo).
+ */
+export function readApps(): RawApp[] {
+  const dir = appsDir()
+  // Single-app: APPS_DIR is itself an app.
+  const self = readOneApp(dir, dir.split('/').filter(Boolean).pop() || 'app')
+  if (self) return [self]
+  // Multi-app: iterate subdirs.
+  const out: RawApp[] = []
+  for (const folder of readdirSync(dir)) {
+    const base = join(dir, folder)
+    if (folder.startsWith('.') || !statSync(base).isDirectory()) continue
+    const app = readOneApp(base, folder)
+    if (app) out.push(app)
+  }
+  return out
+}
+
+/** Assemble the InstalledAppRecord[] the cockpit's useInstalledApps expects. */
+export function loadApps(): unknown[] {
+  const now = new Date().toISOString()
+  return readApps().map((a) => {
+    const vendor = a.manifest.vendor ?? 'revenexx'
+    return {
+      tenant_slug: 'dev',
+      app: {
+        owner_tenant_slug: vendor,
+        name: a.manifest.name ?? a.folder,
+        title: a.manifest.title ?? a.folder,
+        vendor,
+        icon: a.manifest.icon ?? null,
+        kind: 'app',
+        app_type: a.manifest.type ?? 'public',
+        latest_version: a.manifest.version ?? null,
+        cockpit: a.cockpit,
+        settings_schema: null,
+        data_schema: { tables: a.schema.entities ?? {} },
+        analytics: null,
+        permissions: a.manifest.permissions ?? [],
+      },
+      installed_at: now,
+      uninstalled_at: null,
+      state: 'installed',
+      provisioning_error: null,
+      is_active: true,
+    }
+  })
+}
+
+// ── Mock data store ─────────────────────────────────────────────────────────
+
+interface EntityDef {
+  qualified: string
+  pk: string
+  columns: Record<string, any>
+  refs: { col: string, entity: string }[] // qualified ref entity
+  rows: Record<string, any>[]
+}
+
+function qualify(vendor: string, app: string, entity: string): string {
+  return `${vendor.replace(/-/g, '_')}__${app.replace(/-/g, '_')}__${entity}`
+}
+
+function enumFromCheck(check?: string): string[] | null {
+  if (!check) return null
+  const m = check.match(/in\s*\(([^)]*)\)/i)
+  if (!m) return null
+  return m[1]!.split(',').map(s => s.trim().replace(/^'|'$/g, '')).filter(Boolean)
+}
+
+function fakeValue(colName: string, col: any, i: number): unknown {
+  const type = String(col.type || 'text').toLowerCase()
+  const options = enumFromCheck(col.check)
+  if (options?.length) return options[i % options.length]
+  if (col.pk || type.includes('uuid')) return randomUUID()
+  if (/(bool)/.test(type)) return i % 2 === 0
+  if (/(int|numeric|decimal|real|double|serial)/.test(type)) return Math.round(Math.random() * 1000) / (type.includes('numeric') ? 100 : 1)
+  if (/(timestamp|date|time)/.test(type)) return new Date(Date.now() - i * 86400000).toISOString()
+  if (/(json|jsonb)/.test(type)) return {}
+  // text-ish: use a readable value based on the column name
+  if (colName === 'name' || colName === 'title' || colName === 'label') return `${colName} ${i + 1}`
+  if (colName === 'code' || colName === 'sku' || colName === 'slug') return `${colName}-${i + 1}`
+  if (colName.endsWith('status') || colName === 'state') return ['active', 'draft', 'archived'][i % 3]
+  return `${colName} ${i + 1}`
+}
+
+let _store: Map<string, EntityDef> | null = null
+
+/** Build (once) the qualified-entity store with fake rows, in FK-safe order. */
+export function getStore(rowsPerEntity = 8): Map<string, EntityDef> {
+  if (_store) return _store
+  const store = new Map<string, EntityDef>()
+
+  // 1. Register every entity across all apps under its qualified name.
+  for (const a of readApps()) {
+    const vendor = a.manifest.vendor ?? 'revenexx'
+    const app = a.manifest.name ?? a.folder
+    for (const [entity, def] of Object.entries(a.schema.entities ?? {})) {
+      const columns = (def as any).columns ?? {}
+      const pk = Object.keys(columns).find(c => columns[c]?.pk) ?? 'id'
+      const refs = Object.entries(columns)
+        .filter(([, c]: any) => c?.references?.entity)
+        .map(([col, c]: any) => ({ col, entity: qualify(vendor, app, c.references.entity) }))
+      store.set(qualify(vendor, app, entity), { qualified: qualify(vendor, app, entity), pk, columns, refs, rows: [] })
+    }
+  }
+
+  // 2. Seed rows FK-safe: an entity is ready once its referenced entities are seeded.
+  const pending = new Set(store.keys())
+  let guard = 0
+  while (pending.size && guard++ < 20) {
+    for (const key of [...pending]) {
+      const def = store.get(key)!
+      const deps = def.refs.filter(r => store.has(r.entity) && r.entity !== key)
+      if (deps.some(r => pending.has(r.entity))) continue // wait for parents
+      for (let i = 0; i < rowsPerEntity; i++) {
+        const row: Record<string, any> = {}
+        for (const [colName, col] of Object.entries(def.columns)) {
+          const ref = def.refs.find(r => r.col === colName)
+          if (ref && store.get(ref.entity)?.rows.length) {
+            const parents = store.get(ref.entity)!.rows
+            row[colName] = parents[i % parents.length]![store.get(ref.entity)!.pk]
+          }
+          else {
+            row[colName] = fakeValue(colName, col, i)
+          }
+        }
+        def.rows.push(row)
+      }
+      pending.delete(key)
+    }
+  }
+  _store = store
+  return store
+}
+
+// ── PostgREST querystring → in-memory query ──────────────────────────────────
+
+export interface PgResult { rows: Record<string, any>[], total: number }
+
+export function pgQuery(entity: string, query: Record<string, any>): PgResult {
+  const store = getStore()
+  // ListView appends `_scoped` for market-scoped views; fall back to the base.
+  const def = store.get(entity) ?? store.get(entity.replace(/_scoped$/, ''))
+  if (!def) return { rows: [], total: 0 }
+  let rows = [...def.rows]
+
+  for (const [key, raw] of Object.entries(query)) {
+    if (['select', 'order', 'limit', 'offset'].includes(key)) continue
+    const val = String(raw)
+    const [op, ...rest] = val.split('.')
+    const arg = rest.join('.')
+    rows = rows.filter((r) => {
+      const cell = r[key]
+      switch (op) {
+        case 'eq': return String(cell) === arg
+        case 'neq': return String(cell) !== arg
+        case 'ilike': return String(cell ?? '').toLowerCase().includes(arg.replace(/\*/g, '').toLowerCase())
+        case 'like': return String(cell ?? '').includes(arg.replace(/\*/g, ''))
+        case 'in': return arg.replace(/^\(|\)$/g, '').split(',').includes(String(cell))
+        case 'gt': return Number(cell) > Number(arg)
+        case 'gte': return Number(cell) >= Number(arg)
+        case 'lt': return Number(cell) < Number(arg)
+        case 'lte': return Number(cell) <= Number(arg)
+        case 'is': return arg === 'null' ? cell == null : cell === (arg === 'true')
+        default: return true
+      }
+    })
+  }
+
+  if (query.order) {
+    const [col, dir] = String(query.order).split('.')
+    rows.sort((a, b) => (a[col!] > b[col!] ? 1 : a[col!] < b[col!] ? -1 : 0) * (dir === 'desc' ? -1 : 1))
+  }
+
+  const total = rows.length
+  const offset = query.offset ? Number(query.offset) : 0
+  const limit = query.limit ? Number(query.limit) : undefined
+  rows = rows.slice(offset, limit != null ? offset + limit : undefined)
+
+  if (query.select && query.select !== '*') {
+    const cols = String(query.select).split(',').map(s => s.trim())
+    rows = rows.map(r => Object.fromEntries(cols.map(c => [c, r[c]])))
+  }
+  return { rows, total }
+}
+
+export function pgResolve(entity: string): EntityDef | undefined {
+  const store = getStore()
+  return store.get(entity) ?? store.get(entity.replace(/_scoped$/, ''))
+}