Pascal Editor Is More Than a 3D Canvas

Pascal Editor is an open-source, local-first 3D building editor built with React Three Fiber and WebGPU. The useful question is not simply how it draws walls, rooms, or furniture, but what makes the same building understandable to a person in the browser, an AI agent using MCP, a plugin author, and a local process. This series examines that question through Pascal's central design choice: a schema-driven semantic scene graph acts as the shared boundary between intent, editing, rendering, persistence, and verification.

That distinction matters in a simple situation. Suppose someone wants a two-room plan with a door, a window, and a sofa. A canvas can display the result, but display alone does not say which level owns the walls, which wall owns the door, whether the sofa is in a valid footprint, or whether an agent can change the plan without replacing unrelated work. Those questions concern meaning and relationships. Pascal Editor's architecture is built around preserving them.

A building editor whose object is the model

Pascal is easy to mistake for a collection of front-end packages because the repository contains a browser application, a reusable viewer, editing components, built-in node definitions, an MCP server, and a CLI. That packaging is important, but it is not the product's deepest organizing idea. The browser is one way to work with a model; the MCP service is another; the local CLI is an operational envelope around them. They become interchangeable only where they meet the same scene representation.

The model describes architectural things as nodes. A site can contain a building, a building can contain levels, and a level can own walls, zones, slabs, ceilings, roofs, stairs, and floor items. Openings and attached objects retain their relationship to the wall, ceiling, or floor that hosts them. A node therefore carries more than a shape. It carries an identity, a kind, visibility, ownership, and the properties needed by other parts of the system to interpret it.

This is why the repository can expose both direct editing and higher-level construction. A human can draw or adjust a wall. An agent can ask for a room or a story shell. A verifier can inspect whether doors are parented to walls and whether a multi-level plan uses separate story walls. These are different interactions with the same subject, not parallel versions of a building that must later be reconciled.

Why a canvas-first model breaks down

A canvas-first design treats the visible mesh as the main fact and everything else as an accessory. That approach works for showing an image, but it becomes fragile as soon as the building must be edited, queried, or carried across a boundary. The mesh does not by itself explain that a door is an opening in a particular wall, that a room polygon belongs to a level, or that the second component of a plan coordinate is depth rather than height.

Pascal instead stores nodes in a flat dictionary while retaining hierarchy through parent links and child relationships. The flat map makes direct lookup and serialization practical. The hierarchy preserves architectural ownership. Those choices work together: a tool can find a wall by ID, a query can walk from an item to its level, and a renderer can mount the wall's children without turning the saved document into a deeply nested rendering tree.

The distinction becomes visible in the wall-and-door example. A wall has endpoints in the level's plan coordinates. A door has its own identity and is attached to that wall; its position is wall-local, measured along the wall rather than expressed as an unrelated world point. If the wall changes, the door's relationship gives the system information it needs to keep the opening meaningful. If an agent merely moved pixels in a rendered image, that relationship would be lost.

The graph is not perfectly uniform, and that is instructive. Older scenes may contain legacy child representations, so the bridge and load path retain compatibility handling rather than assuming every historical document had today's exact shape. The lesson is not that a semantic model eliminates complexity. It is that complexity is placed at an explicit data boundary where it can be migrated, validated, and explained.

One graph, several controlled consumers

The scene graph is authoritative, but it is not the only representation Pascal needs. The viewer turns nodes into live Three.js objects. Its scene registry maps node IDs to those objects so rendering systems can find a wall, item, or zone without repeatedly walking the entire scene. Geometry builders can read related nodes through supplied context, build local geometry, and let the runtime replace disposable children when a node becomes dirty.

That flow creates an important separation. The saved node says what the wall is; the rendered object is a current projection of that meaning. A dirty mark says that some consumer should rebuild or update a projection; it is not a new architectural fact. This makes it possible to rebuild geometry after an edit, preserve the same semantic identity across a view change, and keep pure builders testable without making them mutate the document.

The viewer also stays editor-agnostic. Presentation state such as camera mode, level display, theme, and selection belongs to the viewer, while tools, overlays, and editor-specific systems are injected from outside. The same canvas can therefore support a read-only view, an embedded viewer, or the full editor without importing the editor's private tool state. A floor plan and a 3D view can be different projections while remaining tied to the same node relationships.

The MCP layer uses the same principle in a different direction. It does not create an AI-only scene format. Its headless bridge reuses the core store and its mutation surface, so creating a wall, placing an item, undoing an edit, or validating a scene has the same semantic target as a browser operation. The bridge has no renderer, which is a real boundary, but the absence of a renderer does not require a second definition of what a wall or room means.

This is also the basis for extensibility. Built-in and external node packs use the same public registry contract. A new kind can declare its schema, capabilities, geometry, floor-plan output, tools, and relationships instead of forcing the host editor to accumulate special cases. The contract is deliberately narrow: plugin visibility, host panels, routes, persistence, and session loading have distinct owners. The point is not unlimited customization; it is adding behavior without breaking the model's shared vocabulary.

flowchart LR H["Human building intent"] --> G["Semantic scene graph"] A["AI-agent intent"] --> M["MCP bridge and tools"] M --> G G --> V["Viewer and editor projection"] G --> P["Local scene persistence"] C["CLI services and runtime"] --> P G --> Q["Validation and spatial checks"] V --> R["Browser rendering"] Q --> B["Boundary-aware result"] R --> X["Rendering and export conditions"]

Local-first is an operating boundary

Pascal's local-first claim is strongest when described as a set of lifecycles. The CLI keeps project data in a local SQLite database, starts an authenticated local MCP service, and treats the web editor runtime as a separate installable artifact. The MCP service can run without downloading or starting the web runtime. That separation lets an agent inspect or edit local projects even when the browser has not been opened, while an editor update can leave project data in place.

It also changes what “installation” means. A runtime archive is checked against a published SHA-256 digest before it is installed, and health checks identify whether the process answering on a port is the expected Pascal process. The local connector gives an MCP client a stable command that forwards to the authenticated loopback service, rather than putting a changing port or secret into client configuration. These are operational choices that reduce accidental coupling between data, runtime, process state, and credentials.

Local-first does not mean that every Pascal workflow is local or that no information can ever leave the machine. The repository also describes hosted MCP and account-backed projects. The local path and hosted path have different trust and storage assumptions, even though they can expose related scene operations. A precise description therefore asks where the graph is stored, which service is being addressed, and who controls the surrounding runtime.

The right promises are narrower than the canvas suggests

A graph-centered architecture makes strong forms of reuse possible, but it also makes boundaries visible. Schema validation can show that nodes have acceptable shapes and relationships. Higher-level verification can identify missing rooms, misplaced openings, suspicious multi-story wall heights, or layout issues. A collision assessment can compare declared furniture dimensions with rotation-aware plan footprints and report when evidence is partial. None of those results is a structural-engineering approval, a construction-code certification, or a proof that a delivery path will work.

The same discipline applies to automation from images. Pascal's vision tools depend on the MCP host's sampling capability. The host returns structured walls, rooms, approximate dimensions, and a confidence value; the translation layer validates the response and preserves warnings when observations cannot become valid nodes. This is a useful path from an image to an editable model, but it is not a promise that an unclear floor plan has become measured construction documentation.

Nor does a successful headless mutation imply that a rendered artifact exists. The MCP package can manipulate node data, but its headless GLB export is explicitly unavailable because export requires the browser renderer. Browser-side geometry, floor-plan presentation, and export-only baking belong to a different runtime boundary. Treating those capabilities as separate is less convenient than pretending they are universal, but it keeps the handoff honest.

The useful promise is shared meaning

Pascal Editor's significance is therefore not that it adds AI commands to a 3D canvas. Its more durable promise is that a building can retain meaning while moving among human tools, viewer projections, plugins, agent operations, local storage, and verification paths. The scene graph is the place where those relationships become explicit, and the surrounding boundaries determine what each consumer may safely claim.

That promise has practical consequences. When a workflow fails, the right question is not only whether the picture looks wrong. It is whether the node was invalid, the ownership relationship was missing, the derived geometry was not rebuilt, the scene was only in memory, a version conflict stopped publication, or the requested conclusion exceeded the available evidence. Pascal's architecture gives each question a different boundary instead of hiding them behind one rendered surface.

To understand how that works, the next step is to look closely at the graph itself: the fields, ownership links, schemas, migrations, and history rules that allow a wall, its opening, and the level that owns them to remain recognizable across clients and versions.

References