planscript 1.4.0 → 2.0.0

package/LANGUAGE_REFERENCE.md

@@ -6,12 +6,16 @@ This document provides a complete specification of the PlanScript language for d
 
 ## Table of Contents
 
+- [Quick Start](#quick-start)
 - [File Structure](#file-structure)
 - [Units](#units)
 - [Origin](#origin)
 - [Defaults](#defaults)
+- [Site](#site)
 - [Plan Block](#plan-block)
 - [Footprint](#footprint)
+- [Zones](#zones)
+- [Courtyards](#courtyards)
 - [Rooms](#rooms)
   - [Rectangle with Two Corners](#rectangle-with-two-corners)
   - [Rectangle with Position and Size](#rectangle-with-position-and-size)
@@ -30,6 +34,78 @@ This document provides a complete specification of the PlanScript language for d
 
 ---
 
+## Quick Start
+
+### Installation
+
+```bash
+npm install -g planscript
+```
+
+Or use directly with npx (no installation required):
+
+```bash
+npx planscript myplan.psc --svg output.svg
+```
+
+### CLI Usage
+
+```bash
+planscript <input.psc> [options]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--svg <file>` | Write SVG output to file |
+| `--json <file>` | Write JSON geometry output to file |
+| `--dimensions` | Include dimension lines in SVG |
+| `--no-labels` | Don't show room labels in SVG |
+| `--no-svg` | Don't generate SVG (useful with --json) |
+| `--help`, `-h` | Show help message |
+
+**Examples:**
+
+```bash
+# Compile and generate SVG
+planscript house.psc --svg house.svg
+
+# Include dimension lines
+planscript house.psc --svg house.svg --dimensions
+
+# Generate both SVG and JSON
+planscript house.psc --svg house.svg --json house.json
+
+# Validate only (check for errors without generating output)
+planscript house.psc --no-svg
+
+# Use npx without installing
+npx planscript examples/house.psc --svg output.svg
+```
+
+### Validation Output
+
+If compilation fails, PlanScript shows detailed error messages:
+
+```
+Compilation failed:
+  validate [E201]: Rooms "living" and "kitchen" overlap
+  validate [E130]: Room "bedroom" is outside the footprint
+```
+
+If successful:
+
+```
+Compilation successful!
+  SVG written to: house.svg
+  Rooms: 5
+  Walls: 12
+  Openings: 6
+```
+
+---
+
 ## File Structure
 
 A PlanScript file (`.psc`) has the following structure. All top-level declarations are optional except for `plan`.
@@ -38,10 +114,13 @@ A PlanScript file (`.psc`) has the following structure. All top-level declaratio
 units <unit>              # Optional: set measurement units
 origin (<x>, <y>)         # Optional: set coordinate origin
 defaults { ... }          # Optional: default values for openings
+site { ... }              # Optional: site orientation (for solar/street context)
 
 plan "<name>" {           # Required: the floor plan definition
   footprint ...           # Required: building boundary
-  room ... { ... }        # One or more rooms
+  zone ... { ... }        # Zero or more zones (grouped rooms)
+  room ... { ... }        # Zero or more standalone rooms
+  courtyard ... { ... }   # Zero or more courtyards (open spaces)
   opening ... { ... }     # Zero or more openings (doors/windows)
   assert ...              # Zero or more validation assertions
 }
@@ -109,6 +188,51 @@ defaults {
 
 ---
 
+## Site
+
+Defines the site orientation, enabling context-aware design validation. This allows you to specify which direction the street faces and validate that rooms have appropriate solar orientation or proximity to the street.
+
+### Basic Syntax
+
+```planscript
+site {
+  street <direction>      # Required: which direction the street/front faces
+  hemisphere <hemisphere> # Optional: north (default) or south
+}
+```
+
+**Directions:** `north`, `south`, `east`, `west`
+
+**Hemispheres:** `north` (default), `south`
+
+### Derived Information
+
+When you specify `street south`, the compiler automatically derives:
+
+| Concept | Meaning |
+|---------|---------|
+| `street` | South (where the entrance/front faces) |
+| `back` | North (opposite of street, typically garden/yard) |
+| `morning_sun` | East (sunrise direction) |
+| `afternoon_sun` | West (sunset direction) |
+
+### Example
+
+```planscript
+site {
+  street south       # Front of house faces south (toward the street)
+  hemisphere north   # Northern hemisphere (default)
+}
+```
+
+With this configuration, you can use orientation assertions to validate your design:
+- Bedrooms should have windows facing east (morning sun)
+- Living room should face west (afternoon sun) or north (garden view)
+- Garage should be near the street
+- Service areas can be toward the street (don't waste good orientations)
+
+---
+
 ## Plan Block
 
 The main container for the floor plan. A file must have exactly one plan block.
@@ -170,6 +294,202 @@ footprint polygon [
 
 ---
 
+## Zones
+
+Zones are logical groupings of rooms that can be positioned as a unit. This allows you to think at a higher level - "place the social zone here, private zone there" - rather than calculating coordinates for each room individually.
+
+### Basic Zone Syntax
+
+```planscript
+zone <id> {
+  room <id> { ... }   # Rooms use local coordinates within the zone
+  room <id> { ... }
+}
+```
+
+Rooms inside a zone use **local coordinates** (relative to the zone's origin at 0,0). When the zone is positioned, all rooms are translated together.
+
+### Zone with Positioning
+
+Zones can attach to other zones or standalone rooms:
+
+```planscript
+zone <id> {
+  attach <direction> <zone_or_room>
+  align <alignment>
+  gap <distance>
+  
+  room <id> { ... }
+  room <id> { ... }
+}
+```
+
+**Directions:**
+| Direction | Description |
+|-----------|-------------|
+| `north_of` | Above the reference |
+| `south_of` | Below the reference |
+| `east_of` | To the right of the reference |
+| `west_of` | To the left of the reference |
+
+**Alignments:**
+| Alignment | Description |
+|-----------|-------------|
+| `top` | Align top edges |
+| `bottom` | Align bottom edges |
+| `left` | Align left edges |
+| `right` | Align right edges |
+| `center` | Center alignment |
+
+### Zone Example
+
+```planscript
+plan "House with Zones" {
+  footprint rect (0, 0) (25, 20)
+  
+  # Entry area (standalone room)
+  room entry { rect (10, 0) (15, 4) }
+  
+  # Social zone - living, dining, kitchen
+  zone social {
+    attach north_of entry
+    align center
+    gap 0
+    
+    room living { rect (0, 0) (8, 6) }
+    room dining {
+      rect size (4, 6)
+      attach east_of living
+      align top
+      gap 0
+    }
+    room kitchen {
+      rect size (4, 6)
+      attach east_of dining
+      align top
+      gap 0
+    }
+  }
+  
+  # Private zone - bedrooms
+  zone private {
+    attach north_of social
+    align left
+    gap 0
+    
+    room master { rect (0, 0) (6, 5) }
+    room bedroom2 {
+      rect size (5, 5)
+      attach east_of master
+      align bottom
+      gap 0
+    }
+  }
+}
+```
+
+In this example:
+1. The `entry` room is placed first at fixed coordinates
+2. The `social` zone attaches north of entry, containing living/dining/kitchen
+3. The `private` zone attaches north of social, containing bedrooms
+
+### Zone Labels
+
+Zones can have optional labels:
+
+```planscript
+zone private {
+  label "Private Wing"
+  room master { ... }
+}
+```
+
+---
+
+## Courtyards
+
+Courtyards define open spaces or voids within the building footprint. They are commonly used for central patios, atriums, light wells, or garden spaces in U-shaped or courtyard-style floor plans.
+
+### Basic Courtyard Syntax
+
+```planscript
+courtyard <id> {
+  rect (<x1>, <y1>) (<x2>, <y2>)
+}
+```
+
+Or with polygon geometry:
+
+```planscript
+courtyard <id> {
+  polygon [
+    (<x1>, <y1>),
+    (<x2>, <y2>),
+    ...
+  ]
+}
+```
+
+### Courtyard with Label
+
+```planscript
+courtyard <id> {
+  rect (<x1>, <y1>) (<x2>, <y2>)
+  label "<display name>"
+}
+```
+
+### Courtyard Examples
+
+**Simple Central Patio:**
+
+```planscript
+plan "U-Shaped House" {
+  footprint rect (0, 0) (30, 40)
+  
+  # Left wing
+  room wing_left { rect (0, 0) (10, 40) label "Left Wing" }
+  
+  # Right wing
+  room wing_right { rect (20, 0) (30, 40) label "Right Wing" }
+  
+  # Back connection
+  room back { rect (10, 30) (20, 40) label "Back" }
+  
+  # Central courtyard (open space)
+  courtyard patio {
+    rect (10, 10) (20, 30)
+    label "Central Patio"
+  }
+}
+```
+
+**Irregular Courtyard:**
+
+```planscript
+courtyard garden {
+  polygon [
+    (12, 15),
+    (22, 15),
+    (22, 28),
+    (17, 32),
+    (12, 28)
+  ]
+  label "Garden"
+}
+```
+
+### Courtyard Rendering
+
+In SVG output, courtyards are rendered with:
+- Light green fill color (to indicate open/outdoor space)
+- Dashed border stroke
+- Italic label text in green
+
+This distinguishes them visually from enclosed rooms.
+
+---
+
 ## Rooms
 
 Rooms define the interior spaces. Each room has a unique identifier and a shape.
@@ -225,7 +545,7 @@ room <id> {
 | `east_of` | To the right of the reference room |
 | `west_of` | To the left of the reference room |
 
-**Alignments:**
+**Alignments (Simple):**
 | Alignment | Description |
 |-----------|-------------|
 | `top` | Align top edges (for east_of/west_of) |
@@ -234,6 +554,16 @@ room <id> {
 | `right` | Align right edges (for north_of/south_of) |
 | `center` | Center alignment |
 
+**Explicit Alignment:**
+
+For more precise control, use explicit edge alignment:
+
+```planscript
+align my <edge> with <room>.<edge>
+```
+
+This allows aligning any edge of the new room with any edge of another room.
+
 **Example:**
 ```planscript
 room kitchen {
@@ -244,6 +574,65 @@ room kitchen {
 }
 ```
 
+**Example with explicit alignment:**
+```planscript
+room bathroom {
+  rect size (3, 2.5)
+  attach north_of bedroom
+  align my left with bedroom.left   # Align left edges precisely
+}
+```
+
+### Auto Dimensions
+
+Use `auto` for width or height to calculate dimensions automatically:
+
+```planscript
+room <id> {
+  rect size (<width>, auto)   # Auto-calculate height
+  attach <direction> <room_ref>
+  extend from <room>.<edge> to <room>.<edge>  # Defines the auto dimension range
+}
+```
+
+When `auto` is used:
+- Without `extend`: Uses the target room's corresponding dimension
+- With `extend`: Calculates the dimension from the specified edge range
+
+**Example:**
+```planscript
+room hallway {
+  rect size (1.5, auto)           # Width is 1.5, height calculated from extend
+  attach east_of living
+  extend from living.top to master.bottom  # Height spans from living.top to master.bottom
+}
+```
+
+### Fill Between Rooms
+
+Automatically fills the gap between two rooms:
+
+```planscript
+room <id> {
+  fill between <room1> and <room2>
+  width <value>    # Optional: explicit width
+  height <value>   # Optional: explicit height
+}
+```
+
+The fill geometry automatically:
+- Detects whether rooms are separated horizontally or vertically
+- Fills the gap between them
+- Spans the overlapping dimension
+
+**Example:**
+```planscript
+room corridor {
+  fill between living and bedrooms
+  width 1.2
+}
+```
+
 ### Rectangle with Span
 
 Creates a room that spans between reference points from other rooms.
@@ -472,6 +861,81 @@ assert min_room_area <room_id> >= <value>
 assert min_room_area bedroom >= 12.0
 ```
 
+### Orientation Assertions
+
+Orientation assertions require a `site` declaration. They validate that rooms have appropriate solar orientation or proximity to the street.
+
+#### Has Window
+
+Ensures a room has a window facing a specific direction:
+
+```planscript
+assert orientation <room_id> has_window <target>
+```
+
+**Targets:**
+| Target | Description |
+|--------|-------------|
+| `north`, `south`, `east`, `west` | Cardinal direction |
+| `morning_sun` | East (for bedrooms - wake up with natural light) |
+| `afternoon_sun` | West (for living areas - evening light) |
+| `street` | Same as the street direction from site |
+
+**Examples:**
+```planscript
+assert orientation master has_window east         # Morning light
+assert orientation living has_window afternoon_sun # Evening light
+assert orientation bedroom has_window morning_sun  # Natural alarm clock
+```
+
+#### Near Street
+
+Ensures a room is located near the street side of the building:
+
+```planscript
+assert orientation <room_id> near street
+```
+
+Use for rooms that need street access (garage, entry) or don't need premium orientations (service areas).
+
+**Example:**
+```planscript
+assert orientation garage near street
+assert orientation entry near street
+```
+
+#### Away From Street
+
+Ensures a room is located at the back of the building (opposite the street):
+
+```planscript
+assert orientation <room_id> away_from street
+```
+
+Use for service areas that shouldn't waste street frontage.
+
+**Example:**
+```planscript
+assert orientation laundry away_from street
+assert orientation storage away_from street
+```
+
+#### Garden View
+
+Ensures a room has a window facing the back (opposite the street):
+
+```planscript
+assert orientation <room_id> garden_view
+```
+
+Use for living areas that should have views of the yard/garden.
+
+**Example:**
+```planscript
+assert orientation living garden_view
+assert orientation dining garden_view
+```
+
 ---
 
 ## Comments
@@ -693,13 +1157,16 @@ plan "Studio Apartment" {
 ### Keywords
 
 ```
-units, origin, defaults, plan, footprint, room, opening, assert,
+units, origin, defaults, site, plan, footprint, zone, room, courtyard, opening, assert,
 rect, polygon, at, size, attach, align, gap, span, from, to, label,
-door, window, between, and, on, shared_edge, width, sill,
+door, window, between, and, on, shared_edge, width, height, sill,
 north_of, south_of, east_of, west_of,
 north, south, east, west,
 top, bottom, left, right, center,
 no_overlap, inside, all_rooms, min_room_area,
+orientation, has_window, near, away_from, garden_view,
+morning_sun, afternoon_sun, street, hemisphere,
+my, with, extend, fill, auto,
 m, cm, mm, ft, in
 ```
 
@@ -737,6 +1204,7 @@ Both syntaxes are equivalent. Bracketed syntax allows trailing commas.
 10        # Integer
 10.5      # Decimal
 50%       # Percentage (for positions)
+auto      # Auto-calculated dimension (for size)
 ```
 
 ### Identifiers

package/dist/ast/types.d.ts

@@ -39,6 +39,13 @@ export interface DefaultsDeclaration extends ASTNode {
     doorWidth?: number;
     windowWidth?: number;
 }
+export type CardinalDirection = 'north' | 'south' | 'east' | 'west';
+export type Hemisphere = 'north' | 'south';
+export interface SiteDeclaration extends ASTNode {
+    type: 'SiteDeclaration';
+    street: CardinalDirection;
+    hemisphere?: Hemisphere;
+}
 export interface FootprintPolygon extends ASTNode {
     type: 'FootprintPolygon';
     points: Point[];
@@ -70,24 +77,49 @@ export interface RoomRectCenterSize extends ASTNode {
 }
 export interface RoomRectSizeOnly extends ASTNode {
     type: 'RoomRectSizeOnly';
-    size: Point;
+    size: SizeValue;
+}
+export type DimensionValue = number | 'auto';
+export interface SizeValue {
+    x: DimensionValue;
+    y: DimensionValue;
+}
+export interface RoomFill extends ASTNode {
+    type: 'RoomFill';
+    between: [string, string];
+    width?: number;
+    height?: number;
 }
-export type RoomGeometry = RoomPolygon | RoomRectDiagonal | RoomRectAtSize | RoomRectCenterSize | RoomRectSizeOnly;
+export type RoomGeometry = RoomPolygon | RoomRectDiagonal | RoomRectAtSize | RoomRectCenterSize | RoomRectSizeOnly | RoomFill;
 export type RelativeDirection = 'north_of' | 'south_of' | 'east_of' | 'west_of';
 export type AlignmentType = 'top' | 'bottom' | 'left' | 'right' | 'center';
+export type AlignEdge = 'top' | 'bottom' | 'left' | 'right';
 export interface AttachDirective extends ASTNode {
     type: 'AttachDirective';
     direction: RelativeDirection;
     target: string;
 }
-export interface AlignDirective extends ASTNode {
+export interface AlignDirectiveSimple extends ASTNode {
     type: 'AlignDirective';
     alignment: AlignmentType;
 }
+export interface AlignDirectiveExplicit extends ASTNode {
+    type: 'AlignDirective';
+    myEdge: AlignEdge;
+    withRoom: string;
+    withEdge: AlignEdge;
+}
+export type AlignDirective = AlignDirectiveSimple | AlignDirectiveExplicit;
 export interface GapDirective extends ASTNode {
     type: 'GapDirective';
     distance: number;
 }
+export interface ExtendDirective extends ASTNode {
+    type: 'ExtendDirective';
+    axis: 'x' | 'y';
+    from: EdgeReference;
+    to: EdgeReference;
+}
 export interface SpanX extends ASTNode {
     type: 'SpanX';
     from: EdgeReference;
@@ -115,6 +147,7 @@ export interface RoomDefinition extends ASTNode {
     attach?: AttachDirective;
     align?: AlignDirective;
     gap?: GapDirective;
+    extend?: ExtendDirective;
 }
 export type OpeningType = 'door' | 'window';
 export type SwingDirection = string;
@@ -183,12 +216,58 @@ export interface AssertionMinRoomArea extends ASTNode {
 export interface AssertionRoomsConnected extends ASTNode {
     type: 'AssertionRoomsConnected';
 }
-export type Assertion = AssertionInsideFootprint | AssertionNoOverlap | AssertionOpeningsOnWalls | AssertionMinRoomArea | AssertionRoomsConnected;
+export type OrientationTarget = 'morning_sun' | 'afternoon_sun' | 'street' | CardinalDirection;
+export interface AssertionOrientationHasWindow extends ASTNode {
+    type: 'AssertionOrientationHasWindow';
+    room: string;
+    target: OrientationTarget;
+}
+export interface AssertionOrientationNearStreet extends ASTNode {
+    type: 'AssertionOrientationNearStreet';
+    room: string;
+}
+export interface AssertionOrientationAwayFromStreet extends ASTNode {
+    type: 'AssertionOrientationAwayFromStreet';
+    room: string;
+}
+export interface AssertionOrientationGardenView extends ASTNode {
+    type: 'AssertionOrientationGardenView';
+    room: string;
+}
+export type OrientationAssertion = AssertionOrientationHasWindow | AssertionOrientationNearStreet | AssertionOrientationAwayFromStreet | AssertionOrientationGardenView;
+export type Assertion = AssertionInsideFootprint | AssertionNoOverlap | AssertionOpeningsOnWalls | AssertionMinRoomArea | AssertionRoomsConnected | OrientationAssertion;
+export interface ZoneDefinition extends ASTNode {
+    type: 'ZoneDefinition';
+    name: string;
+    label?: string;
+    rooms: RoomDefinition[];
+    attach?: AttachDirective;
+    align?: AlignDirective;
+    gap?: GapDirective;
+}
+export type CourtyardGeometry = CourtyardRect | CourtyardPolygon;
+export interface CourtyardRect extends ASTNode {
+    type: 'CourtyardRect';
+    p1: Point;
+    p2: Point;
+}
+export interface CourtyardPolygon extends ASTNode {
+    type: 'CourtyardPolygon';
+    points: Point[];
+}
+export interface CourtyardDefinition extends ASTNode {
+    type: 'CourtyardDefinition';
+    name: string;
+    label?: string;
+    geometry: CourtyardGeometry;
+}
 export interface PlanDefinition extends ASTNode {
     type: 'PlanDefinition';
     name: string;
     footprint: Footprint;
+    zones: ZoneDefinition[];
     rooms: RoomDefinition[];
+    courtyards: CourtyardDefinition[];
     openings: Opening[];
     wallOverrides: WallThicknessOverride[];
     assertions: Assertion[];
@@ -200,6 +279,7 @@ export interface Program extends ASTNode {
     axis?: AxisDeclaration;
     grid?: GridDeclaration;
     defaults?: DefaultsDeclaration;
+    site?: SiteDeclaration;
     plan: PlanDefinition;
 }
 //# sourceMappingURL=types.d.ts.map