diff --git a/.claude/rules/node-schemas.md b/.claude/rules/node-schemas.md new file mode 120000 index 00000000..93ceffa0 --- /dev/null +++ b/.claude/rules/node-schemas.md @@ -0,0 +1 @@ +../../.cursor/rules/node-schemas.mdc \ No newline at end of file diff --git a/.claude/rules/spatial-queries.md b/.claude/rules/spatial-queries.md new file mode 120000 index 00000000..c3345522 --- /dev/null +++ b/.claude/rules/spatial-queries.md @@ -0,0 +1 @@ +../../.cursor/rules/spatial-queries.mdc \ No newline at end of file diff --git a/.cursor/rules/creating-rules.mdc b/.cursor/rules/creating-rules.mdc index 6e3578a0..4ac11580 100644 --- a/.cursor/rules/creating-rules.mdc +++ b/.cursor/rules/creating-rules.mdc @@ -74,3 +74,5 @@ Concrete guidance with examples. | `scene-registry` | Global node ID → Object3D map and `useRegistry` | | `selection-managers` | Two-layer selection (viewer + editor), events, outliner | | `events` | Typed event bus — emitting and listening to node and grid events | +| `node-schemas` | Zod schema pattern for node types, createNode, updateNode | +| `spatial-queries` | Placement validation (canPlaceOnFloor/Wall/Ceiling) for tools | diff --git a/.cursor/rules/events.mdc b/.cursor/rules/events.mdc index d9021dd5..ec751cfb 100644 --- a/.cursor/rules/events.mdc +++ b/.cursor/rules/events.mdc @@ -26,7 +26,7 @@ Example keys: `wall:click`, `item:enter`, `door:double-click`, `grid:pointerdown 'click' | 'move' | 'enter' | 'leave' | 'pointerdown' | 'pointerup' | 'context-menu' | 'double-click' ``` -The `grid:*` events fire when the user interacts with empty space (no node hit). See @apps/editor/hooks/use-grid-events.ts. +The `grid:*` events fire when the user interacts with empty space (no node hit). They are **not** emitted by a mesh — `useGridEvents(gridY)` (@apps/editor/hooks/use-grid-events.ts) manually raycasts against a ground plane and calls `emitter.emit('grid:click', …)`. Mount it in any tool or editor component that needs empty-space interactions. ## NodeEvent Shape diff --git a/.cursor/rules/node-schemas.mdc b/.cursor/rules/node-schemas.mdc new file mode 100644 index 00000000..6cbc9080 --- /dev/null +++ b/.cursor/rules/node-schemas.mdc @@ -0,0 +1,94 @@ +--- +description: Node type definitions, Zod schema pattern, and how to create nodes in the scene +globs: packages/core/src/schema/** +alwaysApply: false +--- + +# Node Schemas + +All node types are defined as Zod schemas in `packages/core/src/schema/nodes/`. Each schema extends `BaseNode` and exports both the schema and its inferred TypeScript type. + +**Sources**: @packages/core/src/schema/base.ts, @packages/core/src/schema/nodes/ + +## BaseNode + +Every node shares these fields: + +```ts +{ + object: 'node' // always literal 'node' + id: string // typed ID e.g. "wall_abc123" + type: string // node type discriminator e.g. "wall" + name?: string // optional display name + parentId: string | null // parent node ID; null = root + visible: boolean // defaults to true + metadata: Record // arbitrary JSON, defaults to {} +} +``` + +## Defining a New Node Type + +```ts +// packages/core/src/schema/nodes/my-node.ts +import { z } from 'zod' +import { BaseNode, objectId, nodeType } from '../base' + +export const MyNode = BaseNode.extend({ + id: objectId('my-node'), // generates IDs like "my-node_abc123" + type: nodeType('my-node'), // sets literal type discriminator + // add node-specific fields: + width: z.number().default(1), + label: z.string().optional(), +}).describe('My node — one-line description of what it represents') + +export type MyNode = z.infer +export type MyNodeId = MyNode['id'] +``` + +Then add `MyNode` to the `AnyNode` union in `packages/core/src/schema/types.ts`. + +## Creating Nodes in Tools + +Always use `.parse()` to validate and generate a proper typed ID. Never construct a plain object manually. + +```ts +import { WallNode } from '@pascal-app/core' +import { useScene } from '@pascal-app/core' + +// 1. Parse validates and fills defaults (including auto-generated id) +const wall = WallNode.parse({ name: 'Wall 1', start: [0, 0], end: [5, 0] }) + +// 2. createNode(node, parentId?) inserts it into the scene +const { createNode } = useScene.getState() +createNode(wall, levelId) +``` + +For batch creation: + +```ts +const { createNodes } = useScene.getState() +createNodes([ + { node: WallNode.parse({ start: [0, 0], end: [5, 0] }), parentId: levelId }, + { node: WallNode.parse({ start: [5, 0], end: [5, 4] }), parentId: levelId }, +]) +``` + +## Updating Nodes + +```ts +const { updateNode } = useScene.getState() +updateNode(wall.id, { height: 2.8 }) // partial update, merges with existing +``` + +## Real Examples + +- **Simple geometry node**: @packages/core/src/schema/nodes/wall.ts — `start`, `end`, `thickness`, `height` +- **Polygon node**: @packages/core/src/schema/nodes/slab.ts — `polygon: [number, number][]`, `holes` +- **Positioned node**: @packages/core/src/schema/nodes/item.ts — `position`, `rotation`, `scale`, `asset` + +## Rules + +- **Always use `.parse()`** — it generates the correct ID prefix and fills defaults. `WallNode.parse({...})` not `{ type: 'wall', id: '...' }`. +- **Never hardcode IDs.** Let `objectId('type')` generate them. +- **Add new node types to `AnyNode`** in `types.ts` or they won't be accepted by the store. +- **Keep schemas in `packages/core`**, not in the viewer or editor — the schema is shared by all packages. diff --git a/.cursor/rules/renderers.mdc b/.cursor/rules/renderers.mdc index d824c681..09acabd9 100644 --- a/.cursor/rules/renderers.mdc +++ b/.cursor/rules/renderers.mdc @@ -40,10 +40,10 @@ import { useRegistry } from '@pascal-app/core' import { useNodeEvents } from '../../hooks/use-node-events' import { useScene } from '@pascal-app/core' -export function MyNodeRenderer({ id }: { id: MyNodeId }) { - const node = useScene(s => s.nodes[id] as MyNode) - const { ref } = useRegistry(id) - const events = useNodeEvents(id) +export function MyNodeRenderer({ node }: { node: MyNode }) { + const ref = useRef(null!) + useRegistry(node.id, 'my-node', ref) // 3 args: id, type, ref — no return value + const events = useNodeEvents(node, 'my-node') return ( diff --git a/.cursor/rules/spatial-queries.mdc b/.cursor/rules/spatial-queries.mdc new file mode 100644 index 00000000..b33ae5f3 --- /dev/null +++ b/.cursor/rules/spatial-queries.mdc @@ -0,0 +1,106 @@ +--- +description: Placement validation for tools — canPlaceOnFloor, canPlaceOnWall, canPlaceOnCeiling +globs: apps/editor/components/tools/** +alwaysApply: false +--- + +# Spatial Queries + +`useSpatialQuery()` validates whether an item can be placed at a given position without overlapping existing items. Every placement tool must call it before committing a node to the scene. + +**Source**: @packages/core/src/hooks/spatial-grid/use-spatial-query.ts + +## Hook + +```ts +const { canPlaceOnFloor, canPlaceOnWall, canPlaceOnCeiling } = useSpatialQuery() +``` + +All three methods return `{ valid: boolean; conflictIds: string[] }`. +`canPlaceOnWall` additionally returns `adjustedY: number` (snapped height). + +--- + +## canPlaceOnFloor + +```ts +canPlaceOnFloor( + levelId: string, + position: [number, number, number], + dimensions: [number, number, number], // scaled width/height/depth + rotation: [number, number, number], + ignoreIds?: string[], // pass [draftItem.id] to exclude self +): { valid: boolean; conflictIds: string[] } +``` + +**Usage in a tool:** +```ts +const pos: [number, number, number] = [x, 0, z] +const { valid } = canPlaceOnFloor(levelId, pos, getScaledDimensions(item), item.rotation, [item.id]) +if (valid) createNode(item, levelId) +``` + +--- + +## canPlaceOnWall + +```ts +canPlaceOnWall( + levelId: string, + wallId: string, + localX: number, // distance along wall from start + localY: number, // height from floor + dimensions: [number, number, number], + attachType: 'wall' | 'wall-side', // 'wall' needs clearance both sides; 'wall-side' only one + side?: 'front' | 'back', + ignoreIds?: string[], +): { valid: boolean; conflictIds: string[]; adjustedY: number } +``` + +`adjustedY` contains the snapped Y so items sit flush on the slab — always use it instead of the raw `localY`: + +```ts +const { valid, adjustedY } = canPlaceOnWall(levelId, wallId, x, y, dims, 'wall', undefined, [item.id]) +if (valid) updateNode(item.id, { wallT: x, wallY: adjustedY }) +``` + +--- + +## canPlaceOnCeiling + +```ts +canPlaceOnCeiling( + ceilingId: string, + position: [number, number, number], + dimensions: [number, number, number], + rotation: [number, number, number], + ignoreIds?: string[], +): { valid: boolean; conflictIds: string[] } +``` + +--- + +## Slab Elevation + +When items rest on a slab (not flat ground), use these to get the correct Y: + +```ts +import { spatialGridManager } from '@pascal-app/core' + +// Y at a single point +const y = spatialGridManager.getSlabElevationAt(levelId, x, z) + +// Y considering the item's full footprint (highest slab point under item) +const y = spatialGridManager.getSlabElevationForItem(levelId, position, dimensions, rotation) +``` + +--- + +## Rules + +- **Always pass `[item.id]` in `ignoreIds`** when validating a draft item that already exists in the scene — otherwise it collides with itself. +- **Use `adjustedY` from `canPlaceOnWall`** — don't use the raw cursor Y for wall-mounted items. +- **Use `getScaledDimensions(item)`** (@packages/core/src/schema/nodes/item.ts) to account for item scale, not the raw `asset.dimensions`. +- Validate on every pointer move for live feedback (highlight ghost red/green). Only `createNode` / `updateNode` on pointer up or click. + +See @apps/editor/components/tools/item/use-placement-coordinator.tsx for a full implementation. diff --git a/.cursor/rules/systems.mdc b/.cursor/rules/systems.mdc index 665a14da..c35a4a9f 100644 --- a/.cursor/rules/systems.mdc +++ b/.cursor/rules/systems.mdc @@ -89,4 +89,4 @@ Core and viewer systems are mounted inside `` alongside renderers. See @ ``` -4. If the system must run before renderers, place it earlier in the JSX tree. +4. **Mount order matters.** Most viewer systems run *after* renderers in the JSX tree — they consume `sceneRegistry` data that renderers populate on mount. Only place a system before renderers if it explicitly does not read the registry.