Pascal 3D Building Editor

The Pascal Editor architecture is organized into several specialized domains. When working with core packages like @pascal-app/core, @pascal-app/viewer, @pascal-app/editor, or @pascal-app/mcp, developers should follow the canonical rules defined in the architecture documentation.

Key architectural domains include:

• Rendering & Layers: Three.js layer constants and rendering separation.
• Systems & Renderers: Core/viewer systems and the node renderer pattern.
• Node Management: Node definitions (geometry/renderer/system composition), node schemas (Zod-based), and the Scene Registry.
• Interaction & Tools: The InteractionScope state machine, editor tools, and spatial queries (placement validation).
• Selection: Two-layer selection (viewer + editor) and selection groups.
• Content Authoring: Contracts for GLB catalog items and plugin authoring.

The IFC → Pascal Converter is a web application designed to convert IFC (Industry Foundation Classes) building models into Pascal scene-graph JSON. The application allows users to drop in .ifc files, inspect the extracted elements, preview the resulting scene in the @pascal-app/viewer, and download the generated JSON for use in the Pascal editor.

Note: This tool is in early alpha. Users should expect rough edges such as misplaced elements, missing geometry, or unmapped element types. It is intended for previewing and iteration rather than production workflows.

@pascal-app/ifc-converter provides pure conversion logic to transform IFC data into Pascal scene graphs.

Key Characteristics:

• Input: A Uint8Array containing the raw IFC bytes.
• Output: An object containing { nodes, rootNodeIds, stats }, which follows the schemas defined in @pascal-app/core.
• Environment: This is a headless package. It contains no DOM or React dependencies. It is designed for use in non-UI environments (like workers or CLI tools) or as the logic engine for a UI (like the ifc-converter-app).

The @pascal-app/mcp package implements a Model Context Protocol (MCP) server for the Pascal 3D editor. The package is organized into several functional areas:

• src/bridge/: Contains the SceneBridge class and node shims used to connect the MCP server to the editor's scene state.
• src/tools/: Contains the core tool implementations (e.g., get_scene, apply_patch, create_wall) and their Zod schemas.
• src/resources/: Provides read-only access to scene data, catalogs, and constraints.
• src/prompts/: Contains pre-defined agent prompts for tasks like generating designs from briefs or renovating from photos.
• src/transports/: Supports stdio and http communication methods.
• bin/pascal-mcp.ts: The CLI entry point for running the server.

The project is a Turborepo monorepo with the following package responsibilities:

• @pascal-app/core: Node schemas, scene state (Zustand), registry contracts, spatial queries, and event bus.
• @pascal-app/viewer: 3D rendering via React Three Fiber, shared render systems, default camera/controls, and post-processing.
• @pascal-app/editor: Editing tools, panels, selection, and direct-manipulation UI.
• @pascal-app/nodes: Built-in registry plugin with node definitions, renderers, geometry, and systems.
• @pascal-app/cli: Installs and manages a versioned standalone editor runtime and persistent local data.
• @pascal-app/mcp: Exposes scene tools, resources, prompts, and local storage to MCP-compatible AI hosts.
• @repo/ui: Shared UI components.
• apps/editor: Standalone Next.js host for the editor packages.

The Scene Registry is a global, mutable map that links node IDs to their live THREE.Object3D instances. It is designed to provide $O(1)$ lookups for systems and selection managers, avoiding the need for expensive tree traversals through the Three.js scene graph.

It consists of two main parts:

1. nodes: A primary Map<string, THREE.Object3D> for direct ID-to-object lookups.
2. byType: A collection of Set<string> objects, where each set contains the IDs of nodes belonging to a specific type (e.g., wall, slab, item), allowing systems to iterate over specific categories of objects efficiently.

The Scene Registry maps node IDs to Three.js Object3D instances for fast lookup, allowing systems to access 3D objects without traversing the scene graph.

Node Renderers are React components that create these Three.js objects. They follow a specific pattern:

1. Create a placeholder mesh/group.
2. Register the reference with the registry using the useRegistry hook.
3. Systems then update the geometry based on the node's data.

Using useRegistry

const ref = useRef<Mesh>(null!)
useRegistry(node.id, 'wall', ref)

The useLiveTransforms store does not use a uniform coordinate frame; the meaning of position and rotation depends on the node kind. Consumers (like 2D renderers) must handle these frames explicitly:

Note: For polygon-based movers (e.g., slab, ceiling), position is a delta applied to the polygon vertices, not an absolute position.