@frontera-sdk/cli 1.43.10 → 1.44.0

package/src/templates/next-app-files.ts

@@ -0,0 +1,1052 @@
+/**
+ * The Next.js App scaffold: configuration, and a WORKING reference feature.
+ *
+ * The scaffold used to be four files — a layout, a providers tree, a page that
+ * rendered one paragraph, and a stack of prose skills describing patterns that
+ * appeared nowhere in the tree. Prose alone loses: an agent asked to "add a
+ * page listing shipments" copies the nearest file it can see, and the nearest
+ * file was a single-component page with inline query branching. So it produced
+ * single-component pages with inline query branching, no matter what the skill
+ * said.
+ *
+ * What ships here instead is one complete vertical slice — route adapter →
+ * shell → feature folder → sub-components → hooks → data layer → pure helpers
+ * → tests — small enough to read in a sitting and structured exactly the way
+ * every later feature must be. The skills name this slice by path, so "follow
+ * the pattern" is a file to copy rather than a paragraph to interpret.
+ *
+ * Everything here type-checks and builds with nothing installed but the public
+ * packages in `package.json`; no registry component is required for the first
+ * build to be green.
+ */
+
+interface ScaffoldInput {
+  /** Project name — the package name, the display name and the page title. */
+  name: string
+  /** Design tokens + Tailwind entry, vendored from the platform stylesheet. */
+  themeCss: string
+}
+
+export function nextAppFiles({ name, themeCss }: ScaffoldInput): Record<string, string> {
+  return {
+    ...projectFiles(name),
+    ...sourceFiles(name, themeCss),
+    ...docFiles(name),
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * Project configuration
+ * ------------------------------------------------------------------ */
+
+function projectFiles(name: string): Record<string, string> {
+  return {
+    'package.json': `${JSON.stringify(
+      {
+        name,
+        version: '0.1.0',
+        private: true,
+        packageManager: 'bun@1.3.14',
+        scripts: {
+          dev: 'next dev',
+          build: 'next build',
+          typecheck: 'tsc --noEmit',
+          test: 'bun test src',
+          // One command an agent can run before claiming done, in the order
+          // that fails fastest. `next build` does not type-check the whole
+          // project and `tsc` never sees the static-export constraints, so
+          // neither alone is a gate.
+          check: 'bun run typecheck && bun run test && bun run build',
+          'blueprint:types': 'frontera blueprint generate-types',
+          'blueprint:types:check': 'frontera blueprint generate-types --check',
+          deploy: 'bun run check && frontera app deploy',
+        },
+        dependencies: {
+          '@frontera-sdk/blueprint': '^1.43.10',
+          '@frontera-sdk/core': '^1.43.10',
+          '@tanstack/react-query': '^5.90.21',
+          // Everything from here to `tailwind-merge` is what a shadcn
+          // component imports. Every item in that registry declares NO
+          // dependencies of its own, so `shadcn add button` writes a file
+          // importing `class-variance-authority` and installs nothing —
+          // declaring them here is the difference between an added component
+          // compiling and a project that cannot resolve `cva`.
+          'class-variance-authority': '^0.7.1',
+          clsx: '^2.1.1',
+          'lucide-react': '^1.31.0',
+          next: '16.3.0',
+          'radix-ui': '^1.6.7',
+          react: '19.2.7',
+          'react-dom': '19.2.7',
+          'tailwind-merge': '^3.3.1',
+        },
+        devDependencies: {
+          '@tailwindcss/postcss': '^4.1.0',
+          // The Tailwind v4 replacement for `tailwindcss-animate`. shadcn
+          // overlays (dialog, select, popover, sheet) style their transitions
+          // with `animate-in` / `fade-in-0` / `zoom-in-95`, and an unknown
+          // utility in Tailwind is not an error — it silently produces no CSS,
+          // so the overlay simply appears without motion and nothing says why.
+          'tw-animate-css': '^1.4.0',
+          // For `bun:test` in `src/**/__tests__`. Without it `tsc` cannot
+          // resolve the module and `bun run typecheck` fails on the tests
+          // this scaffold ships.
+          '@types/bun': '^1.3.0',
+          '@types/node': '^22',
+          '@types/react': '^19',
+          '@types/react-dom': '^19',
+          tailwindcss: '^4.1.0',
+          typescript: '^5.9.3',
+        },
+      },
+      null,
+      2,
+    )}\n`,
+
+    // Frontera hosting configuration is deliberately separate from npm's
+    // package manifest. package.json stays standard package metadata; this
+    // file describes how the already-built artifact is served.
+    'frontera.config.json': `${JSON.stringify(
+      {
+        displayName: name,
+        outputDirectory: 'out',
+        routing: 'filesystem',
+        connectDomains: [],
+        resourceDomains: [],
+      },
+      null,
+      2,
+    )}\n`,
+
+    'next.config.ts': `import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  output: 'export',
+  trailingSlash: true,
+  images: { unoptimized: true },
+  // Current Frontera SDK packages publish TypeScript source. This is Next's
+  // supported boundary for compiling those dependencies inside the App build.
+  transpilePackages: ['@frontera-sdk/core', '@frontera-sdk/blueprint'],
+}
+
+export default nextConfig
+`,
+
+    'tsconfig.json': `${JSON.stringify(
+      {
+        compilerOptions: {
+          target: 'ES2017',
+          lib: ['dom', 'dom.iterable', 'esnext'],
+          allowJs: false,
+          skipLibCheck: true,
+          strict: true,
+          noEmit: true,
+          esModuleInterop: true,
+          module: 'esnext',
+          moduleResolution: 'bundler',
+          resolveJsonModule: true,
+          isolatedModules: true,
+          jsx: 'react-jsx',
+          incremental: true,
+          plugins: [{ name: 'next' }],
+          paths: { '@/*': ['./src/*'] },
+        },
+        // `.next/dev/types` is not decoration: `next build` rewrites this file
+        // to add it on the first run, so omitting it means the very first
+        // build leaves the working tree dirty and a deploy records it as such.
+        include: [
+          'next-env.d.ts',
+          '**/*.ts',
+          '**/*.tsx',
+          '.next/types/**/*.ts',
+          '.next/dev/types/**/*.ts',
+        ],
+        exclude: ['node_modules', 'out'],
+      },
+      null,
+      2,
+    )}\n`,
+
+    'next-env.d.ts': `/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+`,
+
+    // Configures the shadcn CLI so `bunx shadcn@latest add <name>` writes into
+    // this project unmodified: Tailwind v4 (no config file), our stylesheet,
+    // our `@/` aliases, our `cn`.
+    //
+    // `cssVariables: true` with a stylesheet that already defines every
+    // variable upstream references is why `add` leaves `globals.css` alone.
+    // `shadcn init` is the command that would NOT: it rewrites the stylesheet
+    // with the vanilla palette and drops the platform surface scale.
+    'components.json': `${JSON.stringify(
+      {
+        $schema: 'https://ui.shadcn.com/schema.json',
+        style: 'new-york',
+        // These components render in the browser under a static export, and
+        // the SDK session is a client boundary — so they carry 'use client'.
+        rsc: false,
+        tsx: true,
+        tailwind: {
+          config: '',
+          css: 'src/app/globals.css',
+          baseColor: 'neutral',
+          cssVariables: true,
+          prefix: '',
+        },
+        aliases: {
+          components: '@/components',
+          ui: '@/components/ui',
+          utils: '@/lib/utils',
+          lib: '@/lib',
+          hooks: '@/hooks',
+        },
+        iconLibrary: 'lucide',
+      },
+      null,
+      2,
+    )}\n`,
+
+    'postcss.config.mjs': `export default { plugins: { '@tailwindcss/postcss': {} } }
+`,
+
+    '.gitignore': `node_modules/
+.next/
+out/
+.frontera/
+.env
+.env.*
+.env.local
+!.env.example
+*.log
+`,
+
+    // Present so the answer to "where do I put the API key" is a file that
+    // says: nowhere. A static App has no secret storage — every value here
+    // ends up readable in the browser bundle.
+    '.env.example': `# Build-time, PUBLIC values only. Everything in a NEXT_PUBLIC_ variable is
+# readable by anyone who opens the App.
+#
+# Do NOT put a Frontera workspace key, an App token, or any customer
+# credential here. Local development gets real Blueprint access from
+# \`frontera app dev\`, which owns NEXT_PUBLIC_FRONTERA_DEV_SESSION_ENDPOINT and
+# keeps the stored CLI key out of the browser.
+
+# NEXT_PUBLIC_SUPPORT_URL=https://example.com/support
+`,
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * Application source — the reference vertical slice
+ * ------------------------------------------------------------------ */
+
+function sourceFiles(name: string, themeCss: string): Record<string, string> {
+  return {
+    // The platform stylesheet, plus the animation utilities shadcn overlays
+    // expect. The import goes directly after Tailwind's because CSS `@import`
+    // rules must precede every other rule in the file.
+    'src/app/globals.css': themeCss.includes('tw-animate-css')
+      ? themeCss
+      : themeCss.replace('@import "tailwindcss";', '@import "tailwindcss";\n@import "tw-animate-css";'),
+
+    'src/app/layout.tsx': `import type { Metadata } from 'next'
+import type { ReactNode } from 'react'
+
+import './globals.css'
+import { Providers } from './providers'
+
+export const metadata: Metadata = { title: ${JSON.stringify(name)} }
+
+/**
+ * Server root layout. Owns metadata and the document, nothing else.
+ *
+ * Never mark this file 'use client' — the client boundary belongs in
+ * providers.tsx so the document stays static-exportable.
+ */
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body className="min-h-dvh bg-background text-foreground antialiased">
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+`,
+
+    'src/app/providers.tsx': `'use client'
+
+import type { ReactNode } from 'react'
+import { blueprintProvider } from '@frontera-sdk/blueprint/provider'
+import { FronteraAppProvider } from '@frontera-sdk/core/react'
+
+/**
+ * The one client boundary at the app root.
+ *
+ * FronteraAppProvider picks the session transport (embedded / standalone /
+ * local), completes the handshake, builds the credentialed client and only
+ * then renders children. Domain providers are contributed as a list, so a
+ * second data domain is one array entry, never a second bridge.
+ *
+ * Mount this ONCE. A per-route provider stack forks the session and the query
+ * cache, which shows up as a second handshake and rows that refuse to update.
+ */
+const devSessionEndpoint = process.env.NEXT_PUBLIC_FRONTERA_DEV_SESSION_ENDPOINT
+if (devSessionEndpoint) {
+  const runtime = globalThis as typeof globalThis & {
+    __FRONTERA_CONFIG__?: Record<string, unknown>
+  }
+  runtime.__FRONTERA_CONFIG__ = { ...runtime.__FRONTERA_CONFIG__, devSessionEndpoint }
+}
+
+export function Providers({ children }: { children: ReactNode }) {
+  return <FronteraAppProvider providers={[blueprintProvider]}>{children}</FronteraAppProvider>
+}
+`,
+
+    // Thin route adapter: reads configuration, renders ONE feature component.
+    // No JSX for the feature, no hooks, no data access.
+    'src/app/page.tsx': `import { STARTER_OBJECT_TYPE, STARTER_SEARCH_PROPERTY } from '@/lib/blueprint/starter'
+import { AppShell } from '@/ui/app-shell/app-shell'
+import { ObjectExplorer } from '@/ui/object-explorer/object-explorer'
+
+export default function HomePage() {
+  return (
+    <AppShell>
+      <ObjectExplorer
+        objectType={STARTER_OBJECT_TYPE}
+        searchProperty={STARTER_SEARCH_PROPERTY}
+      />
+    </AppShell>
+  )
+}
+`,
+
+    'src/lib/utils.ts': `import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+`,
+
+    // One place for user-visible text. Not internationalisation — the point is
+    // that wording is reviewable in one file instead of hidden in twenty JSX
+    // branches, and that an empty state and its error twin cannot drift.
+    'src/lib/copy.ts': `export const copy = {
+  app: {
+    title: ${JSON.stringify(name)},
+    embedded: 'Embedded',
+    standalone: 'Standalone',
+    local: 'Local development',
+  },
+  explorer: {
+    searchLabel: 'Search',
+    searchPlaceholder: 'Filter by the configured property…',
+    loading: 'Loading records…',
+    empty: 'No records match this view.',
+    emptyHint: 'Clear the search, or widen the filter.',
+    errorTitle: 'Could not load records',
+    retry: 'Try again',
+    unconfiguredTitle: 'Point this App at an object type',
+    unconfiguredBody:
+      'Run \`frontera blueprint list\` to see what this workspace exposes, then set STARTER_OBJECT_TYPE in src/lib/blueprint/starter.ts.',
+    previous: 'Previous',
+    next: 'Next',
+    range: (from: number, to: number, total: number | null) =>
+      total === null ? \`\${from}–\${to}\` : \`\${from}–\${to} of \${total}\`,
+  },
+} as const
+`,
+
+    'src/lib/blueprint/starter.ts': `/**
+ * The object type the starter page reads.
+ *
+ * \`frontera blueprint list\` shows what this workspace exposes; put an API name
+ * here — \`Shipment\`, \`LoanApplication\`, whatever the deployment models — and
+ * \`frontera blueprint get <apiName>\` lists its properties.
+ *
+ * Annotated \`: string\` on purpose. Without it TypeScript infers the literal
+ * type \`''\`, and the empty-check in the explorer becomes a "no overlap" error
+ * the moment you fill this in — a type error caused by doing exactly what the
+ * comment says.
+ *
+ * This starter reads any object type by name, which is what makes it useful
+ * before you know the data. Real features do the opposite: run
+ * \`bun run blueprint:types\` and pass a LITERAL api name to \`useObjects\`, so
+ * rows, filters and sorts are all typed. See the frontera-blueprint-data skill.
+ */
+export const STARTER_OBJECT_TYPE: string = ''
+
+/** A string property to search with \`contains\`. Undefined disables search. */
+export const STARTER_SEARCH_PROPERTY: string | undefined = undefined
+`,
+
+    // ---- data layer -------------------------------------------------
+    'src/lib/blueprint/objects/objects-hooks.ts': `'use client'
+
+import { keepPreviousData } from '@tanstack/react-query'
+import { useAggregate, useObjectQuery } from '@frontera-sdk/blueprint/hooks'
+import { objectsOf } from '@frontera-sdk/blueprint/types'
+import type { AggregateResponse, WhereNode } from '@frontera-sdk/blueprint/types'
+
+/**
+ * The data layer for the object explorer.
+ *
+ * Everything that talks to Blueprint lives in \`src/lib/blueprint/<domain>/\`,
+ * one folder per domain, and components receive rows as props. That separation
+ * is what keeps a filter change from turning into a fetch inside a table cell.
+ *
+ * This starter domain is deliberately generic — it takes the object type as an
+ * argument so it works before you know the data model. A real domain is named
+ * after its object type (\`src/lib/blueprint/shipment/shipment-hooks.ts\`), uses
+ * a literal api name, and gets full row/filter/sort inference from
+ * \`bun run blueprint:types\`.
+ */
+
+export const PAGE_SIZE = 25
+
+export interface ObjectPageParams {
+  objectType: string
+  /** Opaque cursor returned by the previous page. Omit for the first page. */
+  pageToken?: string
+  pageSize?: number
+  search?: string
+  searchProperty?: string
+}
+
+/**
+ * The server-side filter.
+ *
+ * Filtering the returned rows in the component instead narrows only the page
+ * you happened to fetch: a filter matching 8,961 records renders 5 of them and
+ * the footer claims "Page 1 of 1".
+ */
+export function objectWhere(params: ObjectPageParams): WhereNode | undefined {
+  const search = params.search?.trim()
+  if (!search || !params.searchProperty) return undefined
+  return { property: params.searchProperty, op: 'contains', value: search }
+}
+
+/** One page of rows. Disabled until an object type is configured. */
+export function useObjectPage(params: ObjectPageParams) {
+  const pageSize = params.pageSize ?? PAGE_SIZE
+  return useObjectQuery(
+    {
+      objectSet: objectsOf(params.objectType, objectWhere(params)),
+      pageToken: params.pageToken,
+      pageSize,
+    },
+    {
+      enabled: params.objectType.length > 0,
+      // Keep the previous page on screen while the next one loads, so paging
+      // dims instead of collapsing to a skeleton and losing scroll position.
+      placeholderData: keepPreviousData,
+    },
+  )
+}
+
+/**
+ * The total, as its own aggregate over the SAME object set.
+ *
+ * \`rows.length\` is the size of one page — never the count. The two queries
+ * must share \`objectWhere\`, or the number under the table describes a
+ * different filter than the table.
+ */
+export function useObjectTotal(params: ObjectPageParams) {
+  return useAggregate(
+    {
+      objectSet: objectsOf(params.objectType, objectWhere(params)),
+      aggregations: [{ alias: 'total', fn: 'count' }],
+      // Required by the service. An empty array means "grand total".
+      groupBy: [],
+    },
+    { enabled: params.objectType.length > 0, placeholderData: keepPreviousData },
+  )
+}
+
+/** Read the count out of an aggregate response, or null when it is absent. */
+export function totalFrom(response: AggregateResponse | undefined): number | null {
+  const value = response?.rows[0]?.total
+  if (value === null || value === undefined) return null
+  const total = Number(value)
+  return Number.isFinite(total) ? total : null
+}
+
+`,
+
+    'src/lib/blueprint/objects/__tests__/objects-hooks.test.ts': `import { describe, expect, test } from 'bun:test'
+
+import { objectWhere, totalFrom } from '../objects-hooks'
+
+/**
+ * The parts of the data layer worth testing in a static App are the pure ones:
+ * filter construction and aggregate parsing. Hooks need a running
+ * session and are covered by \`frontera app dev\` against real data.
+ */
+describe('objectWhere', () => {
+  const base = { objectType: 'Shipment' }
+
+  test('is undefined without a search property, so the query stays unfiltered', () => {
+    expect(objectWhere({ ...base, search: 'jakarta' })).toBeUndefined()
+  })
+
+  test('ignores whitespace-only input rather than filtering on an empty string', () => {
+    expect(objectWhere({ ...base, search: '   ', searchProperty: 'city' })).toBeUndefined()
+  })
+
+  test('builds a server-side contains filter', () => {
+    expect(objectWhere({ ...base, search: ' jakarta ', searchProperty: 'city' })).toEqual({
+      property: 'city',
+      op: 'contains',
+      value: 'jakarta',
+    })
+  })
+})
+
+describe('totalFrom', () => {
+  test('reads the aliased count', () => {
+    expect(totalFrom({ rows: [{ total: 8961 }] })).toBe(8961)
+  })
+
+  test('distinguishes "no answer yet" from zero', () => {
+    expect(totalFrom(undefined)).toBeNull()
+    expect(totalFrom({ rows: [] })).toBeNull()
+    expect(totalFrom({ rows: [{ total: 0 }] })).toBe(0)
+  })
+})
+`,
+
+    // ---- shell ------------------------------------------------------
+    'src/ui/app-shell/app-shell.tsx': `'use client'
+
+import type { ReactNode } from 'react'
+import { useFronteraApp } from '@frontera-sdk/core/react'
+
+import { copy } from '@/lib/copy'
+
+/**
+ * The frame every page renders into.
+ *
+ * An App is shown in two containers — inside the platform in a constrained
+ * frame, and standalone at full viewport — so the shell adapts rather than
+ * assuming it owns the screen. It carries the customer's page identity, not
+ * Frontera branding: the platform chrome already says where you are.
+ */
+export function AppShell({ children }: { children: ReactNode }) {
+  const { mode, init } = useFronteraApp()
+  const label =
+    mode === 'embedded' ? copy.app.embedded : mode === 'local' ? copy.app.local : copy.app.standalone
+
+  return (
+    <div className="flex min-h-dvh flex-col bg-background">
+      <header className="flex flex-wrap items-center justify-between gap-2 border-b border-border px-4 py-3 sm:px-6">
+        <h1 className="text-base font-semibold text-foreground sm:text-lg">{copy.app.title}</h1>
+        <p className="text-xs text-muted-foreground">
+          {label} · {init.version}
+        </p>
+      </header>
+      {/* The App owns its own scrolling: embedded, the platform will not
+          scroll for it. */}
+      <main className="mx-auto w-full max-w-6xl flex-1 overflow-y-auto p-4 sm:p-6">{children}</main>
+    </div>
+  )
+}
+`,
+
+    // ---- feature: object explorer -----------------------------------
+    'src/ui/object-explorer/types.ts': `/** A Blueprint property, as the query response describes it. */
+export interface ObjectColumn {
+  apiName: string
+  displayName?: string
+  dataType?: string
+}
+
+export type ObjectRow = Record<string, unknown>
+`,
+
+    'src/ui/object-explorer/utils.ts': `/**
+ * Render one cell value.
+ *
+ * Blueprint returns JSON, so a cell can be null, a number, a boolean or a
+ * nested object. Formatting here keeps every table component free of
+ * defensive \`String(value ?? '')\` sprinkles that quietly print "null".
+ */
+export function formatCell(value: unknown): string {
+  if (value === null || value === undefined) return '—'
+  if (typeof value === 'boolean') return value ? 'Yes' : 'No'
+  if (typeof value === 'number') return Number.isFinite(value) ? value.toLocaleString() : '—'
+  if (typeof value === 'string') return value
+  return JSON.stringify(value)
+}
+`,
+
+    'src/ui/object-explorer/hooks/use-debounced-value.ts': `'use client'
+
+import { useEffect, useState } from 'react'
+
+/**
+ * Trailing debounce for text input.
+ *
+ * A query key that changes on every keystroke issues one request per
+ * character; each one is a real Blueprint scan.
+ */
+export function useDebouncedValue<T>(value: T, delayMs = 300): T {
+  const [debounced, setDebounced] = useState(value)
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delayMs)
+    return () => clearTimeout(timer)
+  }, [value, delayMs])
+
+  return debounced
+}
+`,
+
+    'src/ui/object-explorer/object-explorer.tsx': `'use client'
+
+import { useState } from 'react'
+
+import {
+  PAGE_SIZE,
+  totalFrom,
+  useObjectPage,
+  useObjectTotal,
+} from '@/lib/blueprint/objects/objects-hooks'
+import { copy } from '@/lib/copy'
+
+import { EmptyPanel } from './components/empty-panel'
+import { ObjectPager } from './components/object-pager'
+import { ObjectSearch } from './components/object-search'
+import { ObjectTable } from './components/object-table'
+import { ObjectTableSkeleton } from './components/object-table-skeleton'
+import { QueryError } from './components/query-error'
+import { useDebouncedValue } from './hooks/use-debounced-value'
+
+/**
+ * The feature entry point. Owns view state, calls the data layer, and renders
+ * query states in one deliberate order — configuration, error, first load,
+ * empty, content. Sub-components below it receive data as props and fetch
+ * nothing.
+ *
+ * Copy this folder shape for the next feature: entry file at the root,
+ * sub-components in \`components/\`, hooks in \`hooks/\`, shared helpers in
+ * \`utils.ts\`, shared types in \`types.ts\`.
+ */
+export function ObjectExplorer({
+  objectType,
+  searchProperty,
+}: {
+  objectType: string
+  searchProperty?: string
+}) {
+  const [search, setSearch] = useState('')
+  const [pageIndex, setPageIndex] = useState(0)
+  const [pageTokens, setPageTokens] = useState<Array<string | undefined>>([undefined])
+  const debouncedSearch = useDebouncedValue(search)
+
+  const params = {
+    objectType,
+    pageToken: pageTokens[pageIndex],
+    search: debouncedSearch,
+    searchProperty,
+  }
+  const rows = useObjectPage(params)
+  const total = useObjectTotal(params)
+
+  // A cursor belongs to one exact query shape. Changing the filter starts a
+  // new scan rather than sending a token minted for the previous search.
+  const handleSearch = (value: string) => {
+    setSearch(value)
+    setPageIndex(0)
+    setPageTokens([undefined])
+  }
+
+  const handlePrevious = () => setPageIndex((current) => Math.max(0, current - 1))
+  const handleNext = () => {
+    const nextPageToken = rows.data?.nextPageToken
+    if (!nextPageToken) return
+    setPageTokens((current) => [...current.slice(0, pageIndex + 1), nextPageToken])
+    setPageIndex((current) => current + 1)
+  }
+
+  if (objectType.length === 0) {
+    return (
+      <EmptyPanel title={copy.explorer.unconfiguredTitle} body={copy.explorer.unconfiguredBody} />
+    )
+  }
+
+  const records = rows.data?.rows ?? []
+  const columns = rows.data?.properties ?? []
+  const totalCount = totalFrom(total.data)
+
+  return (
+    <section className="flex flex-col gap-4">
+      <ObjectSearch
+        value={search}
+        onChange={handleSearch}
+        disabled={searchProperty === undefined}
+      />
+
+      {rows.isError ? (
+        <QueryError message={rows.error.message} onRetry={() => void rows.refetch()} />
+      ) : rows.isLoading ? (
+        <ObjectTableSkeleton />
+      ) : records.length === 0 ? (
+        <EmptyPanel title={copy.explorer.empty} body={copy.explorer.emptyHint} />
+      ) : (
+        <>
+          <ObjectTable columns={columns} rows={records} isRefreshing={rows.isFetching} />
+          <ObjectPager
+            page={pageIndex + 1}
+            pageSize={PAGE_SIZE}
+            rowsOnPage={records.length}
+            total={totalCount}
+            hasPrevious={pageIndex > 0}
+            hasNext={rows.data?.hasMore ?? false}
+            onPrevious={handlePrevious}
+            onNext={handleNext}
+          />
+        </>
+      )}
+    </section>
+  )
+}
+`,
+
+    'src/ui/object-explorer/components/object-table.tsx': `'use client'
+
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@/components/ui/table'
+import { cn } from '@/lib/utils'
+
+import type { ObjectColumn, ObjectRow } from '../types'
+import { formatCell } from '../utils'
+
+/**
+ * Presentational table. Receives rows, renders rows.
+ *
+ * The markup is the shadcn \`table\` primitive — do not hand-roll a \`<table>\`
+ * next to it. Wrapped in its own horizontal scroller so a wide object type
+ * stays readable on a phone without the page itself scrolling sideways.
+ */
+export function ObjectTable({
+  columns,
+  rows,
+  isRefreshing = false,
+}: {
+  columns: ObjectColumn[]
+  rows: ObjectRow[]
+  isRefreshing?: boolean
+}) {
+  return (
+    <div
+      // A background refetch dims the stale rows instead of replacing them
+      // with a skeleton, so the table does not flash on every page change.
+      aria-busy={isRefreshing}
+      className={cn(
+        'overflow-x-auto rounded-lg border transition-opacity',
+        isRefreshing && 'opacity-60',
+      )}
+    >
+      <Table>
+        <TableHeader>
+          <TableRow>
+            {columns.map((column) => (
+              <TableHead key={column.apiName}>{column.displayName ?? column.apiName}</TableHead>
+            ))}
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {rows.map((row, index) => (
+            <TableRow key={index}>
+              {columns.map((column) => (
+                <TableCell key={column.apiName}>{formatCell(row[column.apiName])}</TableCell>
+              ))}
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  )
+}
+`,
+
+    'src/ui/object-explorer/components/object-table-skeleton.tsx': `import { Skeleton } from '@/components/ui/skeleton'
+
+/**
+ * Shaped like the table it replaces — same border, same row rhythm — so the
+ * layout does not jump when data arrives. A centred spinner communicates
+ * nothing about what is loading and shifts everything below it.
+ */
+export function ObjectTableSkeleton({ rows = 8, columns = 4 }: { rows?: number; columns?: number }) {
+  return (
+    <div className="overflow-hidden rounded-lg border">
+      {Array.from({ length: rows }).map((_, rowIndex) => (
+        <div key={rowIndex} className="flex gap-3 border-b px-3 py-2.5 last:border-0">
+          {Array.from({ length: columns }).map((__, cellIndex) => (
+            <Skeleton key={cellIndex} className="h-3.5 flex-1" />
+          ))}
+        </div>
+      ))}
+    </div>
+  )
+}
+`,
+
+    'src/ui/object-explorer/components/object-search.tsx': `'use client'
+
+import { Input } from '@/components/ui/input'
+import { copy } from '@/lib/copy'
+
+/** Controlled search input. The debounce belongs to the caller, not the field. */
+export function ObjectSearch({
+  value,
+  onChange,
+  disabled = false,
+}: {
+  value: string
+  onChange: (value: string) => void
+  disabled?: boolean
+}) {
+  return (
+    <div className="flex flex-col gap-1.5">
+      <label htmlFor="object-search" className="text-xs font-medium text-muted-foreground">
+        {copy.explorer.searchLabel}
+      </label>
+      <Input
+        id="object-search"
+        type="search"
+        value={value}
+        disabled={disabled}
+        placeholder={copy.explorer.searchPlaceholder}
+        onChange={(event) => onChange(event.target.value)}
+        // h-11 keeps the target at 44px for touch; the primitive is denser by
+        // default, and a filter is a primary control on a phone.
+        className="h-11 sm:h-9 sm:max-w-sm"
+      />
+    </div>
+  )
+}
+`,
+
+    'src/ui/object-explorer/components/object-pager.tsx': `'use client'
+
+import { Button } from '@/components/ui/button'
+import { copy } from '@/lib/copy'
+
+/**
+ * Cursor-backed server-side pager. The numeric page is presentation only;
+ * Blueprint navigation uses opaque page tokens retained by the parent.
+ */
+export function ObjectPager({
+  page,
+  pageSize,
+  rowsOnPage,
+  total,
+  hasPrevious,
+  hasNext,
+  onPrevious,
+  onNext,
+}: {
+  page: number
+  pageSize: number
+  rowsOnPage: number
+  total: number | null
+  hasPrevious: boolean
+  hasNext: boolean
+  onPrevious: () => void
+  onNext: () => void
+}) {
+  const from = (page - 1) * pageSize + 1
+  const to = from + Math.max(rowsOnPage, 1) - 1
+
+  return (
+    <div className="flex flex-wrap items-center justify-between gap-2">
+      <p className="text-xs text-muted-foreground">{copy.explorer.range(from, to, total)}</p>
+      <div className="flex items-center gap-2">
+        {/* h-11 on touch: the primitive's default height sits below the 44px
+            target a thumb needs, and paging is a primary control. */}
+        <Button variant="outline" className="h-11 sm:h-9" disabled={!hasPrevious} onClick={onPrevious}>
+          {copy.explorer.previous}
+        </Button>
+        <Button variant="outline" className="h-11 sm:h-9" disabled={!hasNext} onClick={onNext}>
+          {copy.explorer.next}
+        </Button>
+      </div>
+    </div>
+  )
+}
+`,
+
+    'src/ui/object-explorer/components/empty-panel.tsx': `/** Success with nothing in it, and configuration gaps. Never used for errors. */
+export function EmptyPanel({ title, body }: { title: string; body?: string }) {
+  return (
+    <div className="rounded-lg border border-dashed border-border bg-card p-8 text-center">
+      <p className="text-sm font-medium text-foreground">{title}</p>
+      {body ? <p className="mt-1 text-sm text-muted-foreground">{body}</p> : null}
+    </div>
+  )
+}
+`,
+
+    'src/ui/object-explorer/components/query-error.tsx': `'use client'
+
+import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert'
+import { Button } from '@/components/ui/button'
+import { copy } from '@/lib/copy'
+
+/**
+ * Recoverable failure, kept distinct from an empty result.
+ *
+ * Rendering a failed read as "no records" tells the customer their data is
+ * gone when the truth is that the request did not succeed. The primitive
+ * carries \`role="alert"\`, so a screen reader is told without being polled.
+ */
+export function QueryError({ message, onRetry }: { message: string; onRetry?: () => void }) {
+  return (
+    <Alert variant="destructive">
+      <AlertTitle>{copy.explorer.errorTitle}</AlertTitle>
+      <AlertDescription>
+        <p>{message}</p>
+        {onRetry ? (
+          <Button variant="outline" className="mt-2 h-11 sm:h-9" onClick={onRetry}>
+            {copy.explorer.retry}
+          </Button>
+        ) : null}
+      </AlertDescription>
+    </Alert>
+  )
+}
+`,
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * Human and agent entry points
+ * ------------------------------------------------------------------ */
+
+function docFiles(name: string): Record<string, string> {
+  return {
+    'AGENTS.md': `# ${name}
+
+A Frontera App: an ordinary Next.js App Router project whose deployable result
+is static files, reading platform data through Blueprint.
+
+## Read this first
+
+Load \`.agents/skills/using-frontera-app-patterns/SKILL.md\`. It is the
+dispatcher — it routes you to the one skill that governs the files you are
+about to change. The patterns there are the ones this project already follows;
+match them rather than inventing a second style.
+
+For the CLI itself — logging in, discovering data, deploying — load
+\`.agents/skills/using-frontera-cli/SKILL.md\` if it is present. It is written
+by \`frontera app init\` and covers the commands rather than the code.
+
+## The shape of the project
+
+| Path | What it is |
+|---|---|
+| \`src/app/\` | route adapters only — layout, providers, thin pages |
+| \`src/ui/<feature>/\` | feature folders; one component per file |
+| \`src/components/ui/\` | shadcn primitives — copied source, yours to edit |
+| \`src/lib/blueprint/<domain>/\` | the data layer: Blueprint reads live here |
+| \`src/lib/copy.ts\` | user-visible strings |
+| \`src/generated/\` | \`bun run blueprint:types\` output — never edited by hand |
+
+\`src/ui/object-explorer/\` is the reference feature. It is a complete slice —
+route adapter, feature entry, sub-components, hooks, data layer, tests — and
+copying its shape is the fastest way to be right.
+
+## Non-negotiables
+
+1. Bun runs everything: \`bun install\`, \`bun run <script>\`, \`bun test\`.
+2. Components never fetch. Hooks in \`src/lib/blueprint/\` fetch; components take props.
+3. Filter, sort, cursor-page and aggregate on the server. Narrowing a fetched page misreports every total.
+4. No secrets in the browser. Not in source, not in \`NEXT_PUBLIC_*\`, not in \`.env\`.
+5. Colors come from tokens in \`src/app/globals.css\`. No hex literals in components.
+6. Every route must exist as a static file after \`bun run build\`. No server runtime exists.
+
+## Verify before claiming done
+
+\`\`\`bash
+bun run check
+\`\`\`
+
+That is \`typecheck\`, then \`bun test\`, then \`build\` — the build is the only
+thing that proves the static export still works. For anything touching data,
+also run it against real data with \`frontera app dev\`.
+`,
+
+    'CLAUDE.md': `./AGENTS.md
+`,
+
+    'README.md': `# ${name}
+
+A Frontera App — a Next.js App Router project that builds to static files and
+reads platform data through Blueprint.
+
+## Getting started
+
+\`\`\`bash
+bun install
+\`\`\`
+
+\`\`\`bash
+frontera app dev
+\`\`\`
+
+\`frontera app dev\` starts Next and a local session broker, so the App runs
+with real, short-lived Blueprint access. \`bun run dev\` alone starts Next
+without a session — useful for pure layout work, not for data.
+
+## Point it at your data
+
+\`\`\`bash
+frontera blueprint list
+\`\`\`
+
+Set \`STARTER_OBJECT_TYPE\` in \`src/lib/blueprint/starter.ts\` to one of the api
+names it prints. Then generate typed contracts for real features:
+
+\`\`\`bash
+bun run blueprint:types
+\`\`\`
+
+Commit \`src/generated/frontera-blueprint.ts\`. It is a projection of the
+Blueprint this workspace is granted; regenerate it after a publication or a
+grant change.
+
+## Ship it
+
+\`\`\`bash
+bun run check
+\`\`\`
+
+\`\`\`bash
+frontera app deploy --no-promote
+\`\`\`
+
+Deploying without promoting publishes an immutable version and returns a
+preview URL. Promote it once it looks right:
+
+\`\`\`bash
+frontera app promote <version>
+\`\`\`
+
+## Layout
+
+\`\`\`text
+src/app/                    route adapters: layout, providers, pages
+src/ui/<feature>/           feature folders — one component per file
+src/lib/blueprint/<domain>/ Blueprint reads (hooks + pure helpers)
+src/lib/copy.ts             user-visible strings
+src/components/ui/          shadcn primitives (bunx shadcn@latest add <name>)
+\`\`\`
+
+Agent instructions and the full pattern set live in \`AGENTS.md\` and
+\`.agents/skills/\`.
+`,
+  }
+}