98 lines
3.3 KiB
Markdown
98 lines
3.3 KiB
Markdown
# Pascal Editor — Setup
|
|
|
|
## Prerequisites
|
|
|
|
- [Bun](https://bun.sh/) 1.3+ (recommended), or Node.js 22+
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
bun install
|
|
bun dev
|
|
```
|
|
|
|
The editor will be running at **http://localhost:3000**.
|
|
|
|
## Environment Variables (optional)
|
|
|
|
Copy `.env.example` to `.env` if you need:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
| Variable | Required | Description |
|
|
|----------|----------|-------------|
|
|
| `NEXT_PUBLIC_GOOGLE_MAPS_API_KEY` | No | Enables address search in the editor |
|
|
| `PORT` | No | Dev server port (default: 3000) |
|
|
|
|
## AI Design Agent
|
|
|
|
Saved scenes expose an `AI Designer` sidebar. Configure an OpenAI-compatible
|
|
model endpoint before using it:
|
|
|
|
```env
|
|
PASCAL_AGENT_API_KEY=your_api_key
|
|
PASCAL_AGENT_BASE_URL=https://api.openai.com/v1
|
|
PASCAL_AGENT_MODEL=gpt-4.1-mini
|
|
PASCAL_DATA_DIR=/absolute/path/to/pascal-data
|
|
PASCAL_AGENT_PROXY_SECRET=replace_with_a_long_random_value
|
|
```
|
|
|
|
The editor and Agent MCP processes must use the same `PASCAL_DATA_DIR` or
|
|
`PASCAL_DB_PATH`. Each chat request launches an isolated `pascal-mcp` stdio
|
|
process, binds it to the current scene, and closes it when streaming finishes.
|
|
This prevents concurrent users from sharing the MCP bridge's in-memory scene.
|
|
|
|
The default safety limits are 18 tool steps, 90 seconds per tool, and 5 minutes
|
|
per turn. Override them with `PASCAL_AGENT_MAX_STEPS`,
|
|
`PASCAL_AGENT_STEP_TIMEOUT_MS`, and `PASCAL_AGENT_TOTAL_TIMEOUT_MS`.
|
|
|
|
When the application runs under Node rather than Bun, make Bun available on
|
|
`PATH` or set `PASCAL_MCP_COMMAND` to its absolute path. Set
|
|
`PASCAL_MCP_ENTRY` when the built MCP executable is outside the monorepo.
|
|
|
|
Production requests must pass through a trusted reverse proxy that authenticates
|
|
the user, strips any incoming `X-Pascal-Agent-Proxy-Secret` header, and injects
|
|
the configured value before forwarding to Pascal. Bind the Pascal service to a
|
|
private interface so users cannot bypass the proxy.
|
|
|
|
For a same-domain hosted deployment, set
|
|
`NEXT_PUBLIC_PASCAL_BASE_PATH=/pascal-service` before building and
|
|
`PASCAL_REQUIRE_HOST_USER=true` at build and runtime. The reverse proxy must
|
|
also strip and inject `X-Pascal-User-Id`. New scenes persist that value as
|
|
`ownerId`; list, read, mutation, event-stream, and Agent routes reject scenes
|
|
owned by another user.
|
|
|
|
The standalone app scripts force Next.js to run under Bun because scene
|
|
persistence uses built-in SQLite. Starting the app with Node 20 or earlier will
|
|
fail when a scene is first loaded or saved.
|
|
|
|
The core editor works without environment variables; the AI agent remains disabled until configured.
|
|
|
|
## Monorepo Structure
|
|
|
|
```
|
|
├── apps/
|
|
│ └── editor/ # Next.js editor application
|
|
├── packages/
|
|
│ ├── core/ # @pascal-app/core — Scene schema, state, systems
|
|
│ ├── viewer/ # @pascal-app/viewer — 3D rendering
|
|
│ └── ui/ # Shared UI components
|
|
└── tooling/ # Build & release tooling
|
|
```
|
|
|
|
## Scripts
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `bun dev` | Start the development server |
|
|
| `bun build` | Build all packages |
|
|
| `bun check` | Lint and format check (Biome) |
|
|
| `bun check:fix` | Auto-fix lint and format issues |
|
|
| `bun check-types` | TypeScript type checking |
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on submitting PRs and reporting issues.
|