LivePage

LivePage is a visual page builder. You compose a page from design components in an in-browser editor, connect components to data sources, and export the result as JSON, shortcode, or a standalone HTML file.

Status: early development (0.1.0). Formats and APIs can change without notice.

Features

• Visual editor. Add, replace, and configure design components such as headers, rows, columns, images, stats, callouts, charts, metric cards, and data tables. Includes undo/redo history and a command palette.
• Data sources. Bind components to REST APIs, GraphQL, JSON feeds, RSS feeds, CSV, generated data, or an authorized LinkedIn OIDC profile through placeholders.
• Templates. Start from bundled templates: SaaS landing page, agency homepage, personal portfolio, CV/resume, blog article, event page, link-in-bio, contact/about, and patient health dashboard.
• Page assistant (optional). Describe the page you want in plain language; a chat picks a template, drafts its text, and tunes its design settings. Off unless enabled with NEXT_PUBLIC_PROMPT_ASSIST_ENABLED=1. Once enabled, toggle it on in the Settings popover (toolbar) to show the chat bubble (bottom-right) without needing a URL parameter. Includes a command palette action ("Open AI Assistant"), first-visit tooltip, and in-app help; see Optional: page assistant.
• Import and export. Save and load pages as JSON or shortcode, or export a standalone HTML page.

Getting started

You need Node.js 18.18 or newer and npm.

npm install
npm run dev

Open http://localhost:3000 for the landing page, or go straight to the builder at http://localhost:3000/try.

Optional: page assistant

The feature is off by default. Set NEXT_PUBLIC_PROMPT_ASSIST_ENABLED=1 and rebuild (the value is inlined at build time) to turn it on. Once enabled, the chat bubble (bottom-right of /try) can be shown in two ways:

1. Per-visit URL parameter: Open the builder with ?prompt-assist=1 (e.g., /try?prompt-assist=1).
2. Persistent setting: Toggle "Enable AI Assistant" in the Settings popover (toolbar gear icon). This persists across visits in localStorage and does not require the URL parameter.

With the deployment flag off, the /api/prompt-assist routes answer 404. It uses TypeSafe's Jev and/or OpenAI. Copy .env.example to .env.local and set TYPESAFE_API_KEY and/or OPENAI_API_KEY; with neither, the chat lets you pick a template by hand and everything else works as before. Keys stay on the server, and the request text is sent to whichever provider you configure. How it works is described in .agents/docs/CONTEXT.md.

Discoverability features:

• Toolbar toggle: Enable/disable the AI Assistant from the Settings popover.
• Command palette: Press ⌘K and search "Open AI Assistant" to open the chat.
• First-visit tooltip: A helpful tooltip appears on first visit explaining the feature.
• In-app help: The Settings popover includes a description of the AI Assistant.

Optional: LinkedIn profile data source

The LinkedIn Profile source uses LinkedIn's official OpenID Connect authorization code flow. In your LinkedIn developer app, enable the Sign In with LinkedIn using OpenID Connect product and authorize the openid, profile, and email scopes. Register the exact value of LINKEDIN_REDIRECT_URI as an authorized redirect URL. For local development, use http://localhost:3000/api/linkedin-profile/callback; production must use the HTTPS callback URL for your deployment. The integration uses LinkedIn's OIDC discovery document and the userinfo endpoint.

Set LINKEDIN_CLIENT_ID, LINKEDIN_CLIENT_SECRET, LINKEDIN_REDIRECT_URI, and LINKEDIN_SESSION_ENCRYPTION_KEY in .env.local using the names in .env.example. Generate the encryption key with openssl rand -base64 32. The client secret stays on the server. The profile session is stored in an encrypted, HttpOnly, SameSite=Lax cookie; it is protected from client-side JS read access and expires after eight hours, but it is not cryptographically bound to one browser/device. It requires HTTPS in production and is removed on disconnect. LinkedIn data is loaded only through the same-origin profile endpoint and is not stored in source settings, app nodes, or exports.

Available profile values are limited to claims returned by the configured app's LinkedIn OIDC scopes: subject, name, given/family names, picture, locale, and the optional email and email-verification claim. LinkedIn does not expose headline, about/summary, positions, education, or skills through this normal self-serve OIDC profile. Those template fields remain empty; access to broader profile permissions requires LinkedIn approval. LivePage does not scrape LinkedIn. Standalone HTML files cannot use the LinkedIn session cookie.

Development

Command	What it does
npm run dev	Start the development server
npm run build	Create a production build
npm start	Serve the production build
npm run lint	Run ESLint through next lint
npm test	Run the whole Jest suite
npm run test:smoke	Smoke suites (Jest and Playwright): the fast critical-path gate CI runs first
npm run test:smoke:unit / npm run test:smoke:ui	Just the Jest or just the Playwright smoke suite
npm run test:unit	Unit tests
npm run test:component	Component and integration tests
npm run test:ui	Full Playwright browser suite (same as test:html-browser)
npm run check:test-categories	Fail if a Jest test lives outside a category folder
npm run test:watch	Run Jest in watch mode
npm run test:coverage	Run Jest with coverage
npm run build:html-runtime	Rebuild the browser runtime used by HTML exports
npm run test:html-browser	Run the standalone HTML artifact regression test in Chromium
npm run check:branch	Check that the current branch name follows gitflow
npm run lint:staged	Lint the staged JS/TS files (what the pre-commit hook runs)
npm run setup:hooks	Enable the git hooks (runs automatically on npm install / npm ci)
npm run check:hooks	Check that the git hooks are enabled and executable
npm run verify	Lint + full Jest suite (--runInBand) + branch-name check + git-hooks check (convenient pre-PR gate)

Test categories and the CI job order are described in .agents/docs/TESTING.md.

The dev, build, start, and test commands rebuild the HTML export runtime automatically, and npm install builds it once (the postinstall script). It is generated into client/features/serializers/html/generated/, which is git-ignored.

The standalone HTML browser tests run in headless Chromium against both the live /try?template=<id>&mode=preview page and the exact exported HTML for every bundled template at desktop and mobile viewport sizes. They fulfill pinned React imports from locally installed React packages and use the preview's local font assets, so the comparison does not depend on CDN availability. To install the browser locally, run npx playwright install chromium once after npm install; then run npm run test:html-browser.

The app is built with Next.js (App Router), React 19, TypeScript, Tailwind CSS, Radix UI, and Zod. Tests use Jest and Testing Library.

Git hooks

npm install and npm ci enable the hooks in scripts/git-hooks/ through the prepare script, so a fresh clone needs no manual step:

• pre-commit lints the staged JS/TS files with ESLint. Warnings fail too.
• commit-msg checks the branch name (skipped on a detached HEAD).
• pre-push checks the branch name and runs the smoke tests (npm run test:smoke), not the long suites. The UI smoke tests need Chromium once: npx playwright install chromium.

The dev, build, start, and test scripts also re-enable the hooks (setup:workspace), so an install that skipped prepare repairs itself on first use. npm run check:hooks reports why hooks would not run, and npm run setup:hooks repairs them. --no-verify skips local hooks; CI runs every check regardless.

Branch names

Pushes must use a gitflow branch name, or a dependabot/<dependency> branch for automated dependency updates. The check applies to people, agents, and other automation. Topic segments are lowercase kebab-case.

Branch type	Pattern	Example
main	main	main
develop	develop	develop
dependabot	dependabot/<dependency>	dependabot/dependencies/node/22
feature	feature/<topic>	feature/login-flow
release	release/<version>	release/1.4.0
hotfix	hotfix/<topic>	hotfix/crash-on-start
support	support/<version-line>	support/1.x
bugfix	bugfix/<topic>	bugfix/null-deref

A rejected name lists these patterns. CI runs node scripts/check-branch-name.mjs on every push and pull request. The local git hooks refuse non-compliant branches at push time. The server-side GitHub ruleset is the check that cannot be skipped; see .agents/docs/BRANCH-NAMES.md.

Project layout

Application code is organized by runtime: browser features and UI live in client/, backend features and integrations in server/, and runtime-neutral models and contracts in shared/. Each runtime groups domain code in its own features/ subfolder. The Next.js route tree stays in app/; page files import client features, while API route files are thin adapters to server features. UI primitives live in client/components/ui/. .agents/docs/CONTEXT.md has the module map and import-boundary rule.

HTML exports

An HTML export is a single file that opens directly in a modern browser, with no LivePage server needed. It bundles the same registered preview-component implementations and compiled Tailwind CSS generated from the builder's global stylesheet. Keep these limits in mind:

• The default file loads pinned React and ReactDOM builds from esm.sh, and Inter from Google Fonts, so the browser needs network access when it opens the file.
• Self-contained export (Download self-contained HTML, or the command palette action) is a single file that inlines the compiled CSS, embeds image, favicon, and Open Graph assets as base64 data URLs, and bundles React locally. It does not load esm.sh or Google Fonts. Assets that cannot be fetched at export time stay as URLs.
• The export runtime uses the registered preview data-source implementations. Network-backed sources must allow the exported page's origin through CORS.
• Image and other asset URLs stay as references in the default export. They are not embedded. Root-relative public image paths are made absolute against the builder's origin so they can load when the exported file is opened locally. Self-contained export embeds fetchable images instead.
• Template parity covers initial content and layout at desktop and mobile sizes; live data-source runtime states are not guaranteed to remain visually identical.

Bundled templates

Templates live in client/features/templates/definitions/. Each one is versioned (schema and version), keeps catalog metadata separate from its content.pages payload, and stores the page as the same AppNode tree the editor uses.

To add a template:

1. Create a definition in client/features/templates/definitions/ using only supported design-component tags.
2. Keep catalog metadata (name, description, category, tags, thumbnail) outside the page payload.
3. Validate it with pageTemplateDefinitionSchema and register it in client/features/templates/registry.ts.
4. If the template is meant for imported profile data, add dataMapping entries that point to the target component ids and fields.

The CV/resume templates include LinkedIn-shaped mapping notes in their dataMapping blocks.

Documentation

• Project context and architecture decisions
• Code conventions
• Glossary
• Branch names
• Testing: test categories, what belongs in smoke, CI order
• AGENTS.md and the agent workflow for coding agents

Contributing

See CONTRIBUTING.md for how to open a pull request and the branch naming (gitflow) conventions enforced in this repo.

Security and conduct

Report vulnerabilities privately as described in SECURITY.md. Participation in this project is governed by the Code of Conduct.

License

MIT