Create a service storefront

Hono, Express, Next.js, and TanStack UI projects render a public service storefront. It is a minimal, read-only directory of invoke and stream endpoints with payment method and price. It is not an operations dashboard, marketplace listing, wallet custodian, API console, or substitute for a protocol-aware buyer.

Generate the Next workspace surface

Build the repository packages, then run the local CLI so the generated project uses the same Next contracts as these docs:

bun run build:packages
bun packages/cli/dist/index.js my-service --adapter=tanstack-ui
# or
bun packages/cli/dist/index.js my-service --adapter=next --ui-preset=folio

The public npm CLI is the Stable channel. Do not use an unpinned public CLI to reproduce this Next page; see Release channels.

Public data flow

canonical entrypoint registry
  → Agent Card + health handlers
    → buildServicePageModel(card, { health, baseUrl })
      → shared ServicePageModel
        → Hono/Express HTML endpoint table
        → Next/TanStack React endpoint table

buildServicePageModel() from @lucid-agents/http accepts only public Agent Card and health data. The model preserves the full public contract, while the page deliberately displays only:

• agent name, version, description, and status;
• each invoke and stream HTTP path;
• each operation's payment method and network; and
• each operation's price, including free operations.

Schemas, examples, trust metadata, capabilities, and the complete Agent Card remain available from the public discovery and entrypoint APIs. The page does not repeat those documents as raw JSON.

Storefront code must not inspect private runtime config, payment trackers, wallet connectors, secrets, internal task records, or adapter-local registries. That boundary keeps the UI truthful across frameworks.

Choose and customize a design

The wizard offers three distinct presets:

The generated service-ui.config.ts is the only visual configuration surface:

import { defineServiceUi } from '@lucid-agents/http/service-ui';

export default defineServiceUi({
  preset: 'folio',
  tokens: {
    colors: { accent: '#2B302C' },
    fonts: {
      display: ['Instrument Sans', 'Avenir Next', 'sans-serif'],
      stylesheetUrl: 'https://fonts.example.com/service.css',
    },
  },
});

The API intentionally excludes arbitrary layout and CSS overrides. Unknown keys, unsafe URLs/font names, invalid hex colors, and inaccessible primary color combinations fail validation. This keeps custom brands on the same semantic markup, responsive rules, and public information contract.

The service name remains the primary page identity. Lucid appears only as a small Resolved Core mark with "Powered by Lucid Agents" in the footer.

Configure the public origin

The model prefers the first Agent Card supportedInterfaces URL unless the caller supplies baseUrl. Configure one canonical external origin and base path after reverse-proxy rewriting. An internal host such as http://agent.local must never leak into production cards or copyable URLs.

Test these through the public proxy:

curl -fsS https://service.example/.well-known/agent-card.json
curl -fsS https://service.example/health

Every displayed operation URL should resolve, carry exactly one configured base-path prefix, and return the same schema/price advertised by the card.

Protected operations

The directory can state that an operation uses x402 or MPP and show the advertised network and price. Payment and authorization happen through a protocol-aware client outside the public page. The page must not:

• expose a server wallet key or facilitator credential to the browser;
• imply that an unauthenticated fetch() can complete a protected operation;
• treat “wallet connected” as payment approval;
• promise usage metering when the operation has a fixed price; or
• display a registration as proof that an output will be correct.

Because the directory has no input or credential controls, it does not retain buyer data or task access tokens.

Verify the page

1. Add one free and one priced capability, including a streaming operation.
2. Load the endpoint directory on desktop and mobile.
3. Confirm every operation has one row with the correct path, payment method, and price. Confirm there are no invoke controls, schemas, or raw JSON dumps.
4. Change a capability price and verify the table updates from the card without a second hard-coded catalog.
5. Break health deliberately and confirm the status becomes degraded/offline without hiding the endpoint rows.
6. Run the generated matrix for all three presets and verify the three Cloudflare previews when repository credentials are configured.

Production boundary

Reconciliation, payment analytics, alerts, task administration, tenant data, and refunds belong in authenticated operational tooling. Do not add them to the public storefront merely because they are convenient to render.

Continue with Publish a catalog, deployment runbooks, and the security threat model.