archlang

<!-- AGENT-FIRST NOTICE -->
> [!IMPORTANT]
> ### 🤖 Read this with your AI agent — don't read it by hand.
> This repo is written agent-first. Point Claude Code, GitHub Copilot, Cursor, or any agent at it:
> *"Read the README and AGENTS.md, then help me run / extend this."*
> Structure + [`AGENTS.md`](AGENTS.md) are optimized for agent comprehension.
<!-- /AGENT-FIRST NOTICE -->

<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="./brand/archlang-wordmark.svg" />
  <img src="./brand/archlang-wordmark-black.svg" alt="ArchLang" width="440" />
</picture>

### Floor plans as code — like Typst/LaTeX, but for architecture.

**Text in, a precise architectural drawing out.** Deterministic, zero-dependency,
and built so an **AI agent can verify its own plan without ever looking at an image**.

[![npm](https://img.shields.io/npm/v/@chanmeng666/archlang?style=flat-square&logo=npm&color=CB3837)](https://www.npmjs.com/package/@chanmeng666/archlang)
[![CI](https://img.shields.io/github/actions/workflow/status/chanmeng666/archlang/ci.yml?branch=main&style=flat-square&logo=githubactions&logoColor=white&label=CI)](https://github.com/chanmeng666/archlang/actions/workflows/ci.yml)
[![Node](https://img.shields.io/node/v/@chanmeng666/archlang?style=flat-square&logo=nodedotjs&color=339933)](https://nodejs.org)
[![Runtime deps](https://img.shields.io/badge/runtime%20deps-0-2e7d32?style=flat-square)](#-why-it-is-different)
[![License](https://img.shields.io/github/license/chanmeng666/archlang?style=flat-square)](LICENSE)
[![Stars](https://img.shields.io/github/stars/chanmeng666/archlang?style=flat-square)](https://github.com/chanmeng666/archlang/stargazers)
[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-EA4AAA?style=flat-square&logo=githubsponsors)](https://github.com/sponsors/ChanMeng666)

**[▶ Live Playground](https://playground.archlang.uk)** · **[📖 Docs](https://archlang.uk)** · **[⌨ CLI reference](https://archlang.uk/cli)** · **[📦 npm](https://www.npmjs.com/package/@chanmeng666/archlang)** · **[🧩 VS Code](https://marketplace.visualstudio.com/items?itemName=ChanMeng.archlang)**

</div>

## 👀 See it

Here is a **whole program**, and below it **the actual drawing it compiles to** — not a mock-up.
Not one coordinate in it places a door, a window or a piece of furniture: every opening is pinned to
a distance along a *named wall*, every fixture resolves against a room or a wall, and the bath and
bedroom are laid out by a `strip`. `site { street north }` names the two facades the plan turns
on — the front door faces the lane, the glazing faces the garden.

```arch
# A one-bedroom laneway cottage — 49 m² that reads as one program.
#
# Nothing here is positioned by hand. Every opening is pinned to a run distance along a
# named wall (`on <wall> at <pos>`), every fixture resolves against a room or a wall
# (`in <room> anchor …`, `against wall …`), and the bath/bedroom pair is laid out by
# `strip`. `site { street north }` names the two facades the plan turns on: the door
# faces the lane, the glass faces the garden.
plan "Laneway House" {
  units mm
  grid 50            # partitions are 100 thick, so a `flush` fixture lands on a …50
  north up
  dims auto all
  site { street north }

  wall id=w_lane   exterior  thickness 200 { (0,0) (7500,0) }
  wall id=w_east   exterior  thickness 200 { (7500,0) (7500,6500) }
  wall id=w_garden exterior  thickness 200 { (0,6500) (7500,6500) }
  wall id=w_west   exterior  thickness 200 { (0,0) (0,6500) }
  wall id=w_hall   partition thickness 100 { (4200,0) (4200,6500) }
  wall id=w_bath   partition thickness 100 { (4200,2500) (7500,2500) }

  room id=r_live at (0,0) size 4200x6500 label "Living / Kitchen" uses living kitchen
  strip down at (4200,0) gap 0 width 3300 {
    room id=r_bath size 2500 label "Bath"    uses bath
    room id=r_bed  size 4000 label "Bedroom" uses bedroom
  }

  door id=d_front  on w_lane at 2100 width 900 hinge near start swing into r_live
  door id=d_garden sliding on w_garden at 2700 width 1800 slide left
  door id=d_bed    on w_hall at 5600 width 800 hinge left swing into r_bed
  # `w_hall` is walked lane→garden, so `slide right` sends the panel down the solid wall
  # below the jamb; `slide left` would aim it at 500 mm and trip `W_POCKET_RUN`.
  door id=d_bath   pocket on w_hall at 900 width 800 slide right

  window on w_west   at 2400 width 1200
  window on w_garden at 700  width 1000
  window on w_garden at 5850 width 1600
  window on w_east   at 1500 width 600

  furniture fridge       against wall w_west offset 400  in r_live
  furniture stove        against wall w_west offset 1200 in r_live
  furniture kitchen_sink against wall w_west offset 2000 in r_live
  furniture table  in r_live centered size 1300x900 label "Table"
  furniture sofa   in r_live anchor bottom-left flush inset 250 size 900x2000  label "Sofa"
  furniture bed    in r_bed  anchor bottom-right flush inset 250 size 1500x2000 label "Bed"
  furniture robe   in r_bed  anchor top-left     flush inset 200 size 1800x600  label "Wardrobe"
  furniture shower in r_bath anchor top-right    flush size 900x900
  furniture wc     in r_bath anchor bottom-left  flush size 400x700
  furniture basin  in r_bath anchor bottom-right flush size 600x450

  title { project "Laneway House" drawn_by "ArchLang" date "2026-08-16" }
}
```

<div align="center">

<a href="https://playground.archlang.uk/#z=jVZdbhs3EH7fU3yQXhxAdmjZUuw2CZC2AQrESIs0QdAn70gcaVmvSIGkvHIDA3nqAYqeoQfoEXqUnKQYciWtHMepnijuzMdvvvkh-3gBZ_lwwto7t0BNlhu6wdTFSHPGp49_4fQci3__QawowjPpAArihKV3c0-Lo6Jf9PHaxcrYOSr2DBOwdMFE4yxrTG5QkdVHeHnN_gZuyVYsxchYMYgOBL-y0CZEslMG1c7OQUUflhas0VBd46B0Fk9l-RwU8XTpwvPy0QCcYGdmHVee4Tm4-poDaE7GhijQEprzoIRT9HFQGounsv0cZKeV8_j08e9ygHLjlA6UvUcDkNWIFWNCsXq8UWpJxksINRkNt4qY3BR9lCF6syyPUAYTGR8QomeOsM7HCrdlCicktNg4zGhKuv2_rMkirrwVcb9JW9o5X_TFqrWR9AzSal5TCJ0vc_Ka7VGRUHoXbRp_dKvAPXwogJU1MWCxKIC5Nxojhc6vjyX5mBIWQJ5xrBRiZaZXAwTJTjmrV6EqtyrXZLUQBYlKI1WgjXG1LABtFgG0krzWdQHcK0ZRIMts9LPmUkIDwOvI3jiPfLrlEDBUCh9woAbqEQ6ejFRa3O55M4X4sPfGLy_GI_UZRpbwYQbZ78sYDX-NRyZxv3clK-xS0fE-zt6nwzaKtLgPQ4r0f2AMO4EMW5gCuVOMfuYva3PN0mWZcDC_M8RxLWeipgnX6F2Ya2nkx3hl4rRi28MqcECdt6_ypqRfmgLaNTYhboKY0xIKjdGxwsmJkCukFnccUizp6GHn1O8oVj0xTIeJzV031mgZq45bbtyWY9vGBXLc0mnirC9n3tkIqey2JiliKMplnudKQeYcwzJ5hEg-IjRpntnokIXbQ2zrKtRGi1lCbvcE-8kW-_hMqWTGqHkW90BSTC2tVCYUMRpvXc-2tMRzn9CEdSEdXmbPUqZWQ_UV6zRPPv3xZ2aTOr3M53szr2KJwNLlaTqR5TqnUP4GV5s8lRP0hGvXpA-_0WLy7QZFuJRo3KrWILOAiYm2Ulgs8lSVuijfX_780_evXr69fPPudXm0H3ZbzW56xXE_-vO94Du001wxVrsmO7Q9KVqf7rQeKnXHbpcTScnGTj1gNzobbfHGn9m1M4kijkfbc8WsAGYrb00apDNv9JzbMbx3-7TM3WwWOEopA8buCmwHEaK73iA8BCExfwGi7dXLYOzVQxBDdQeij7cVw6_SdU4W717_8PLNxYtfB9CeGosJz5znXEKG821FUfrGapHJRKm6XFIzkqJIoJEmNcu1gWsTzKS-EdvolvAUK_YCYlHlhjIxPVPyPZ5fE4In7T1Aba4yzfRIyE8UrgOnd8oAVrZBmDrntbEU-WhPFwmsI_vmsTBxMbrFYeo1YzfpyZPqTKn1yWmqhh1OjqcDNGUbWdgmp-MTpdbnu1n1Vsx7-0kWeb5CJd3RLaHhqCV0rtQ6pW0D_oub0T52O1wSdlrvY6euuh9cKjuj76bsPrZ3E74PO7plJi2_PeyNkjIO1-MO8ffktcDdEaZyDfv2ABkXnQMy8-0BWz3O76SnmWInQAejK24X41Sp9ZM7GBMKxn4ZoytiwhgrtT4dpWkQTazlfbT07jeexs_eb6mVLic36L3w0-qC7LwHTZHRG6rh-FCdHR6Pe7gtbov_AA">
<img src="./examples/laneway-house.svg" alt="The floor plan the program above compiles to — click to open it in the live playground" width="620" />
</a>

**↑ `arch compile laneway-house.arch` — that program, rendered.** The walls join and hatch
themselves, the hinged doors draw their own swing arcs, the sliding and pocket leaves draw panels
instead (a pocket door has no arc, because it has no swing), and `dims auto all` measures the
building it was given.

**▶ [Click the drawing](https://playground.archlang.uk/#z=jVZdbhs3EH7fU3yQXhxAdmjZUuw2CZC2AQrESIs0QdAn70gcaVmvSIGkvHIDA3nqAYqeoQfoEXqUnKQYciWtHMepnijuzMdvvvkh-3gBZ_lwwto7t0BNlhu6wdTFSHPGp49_4fQci3__QawowjPpAArihKV3c0-Lo6Jf9PHaxcrYOSr2DBOwdMFE4yxrTG5QkdVHeHnN_gZuyVYsxchYMYgOBL-y0CZEslMG1c7OQUUflhas0VBd46B0Fk9l-RwU8XTpwvPy0QCcYGdmHVee4Tm4-poDaE7GhijQEprzoIRT9HFQGounsv0cZKeV8_j08e9ygHLjlA6UvUcDkNWIFWNCsXq8UWpJxksINRkNt4qY3BR9lCF6syyPUAYTGR8QomeOsM7HCrdlCicktNg4zGhKuv2_rMkirrwVcb9JW9o5X_TFqrWR9AzSal5TCJ0vc_Ka7VGRUHoXbRp_dKvAPXwogJU1MWCxKIC5Nxojhc6vjyX5mBIWQJ5xrBRiZaZXAwTJTjmrV6EqtyrXZLUQBYlKI1WgjXG1LABtFgG0krzWdQHcK0ZRIMts9LPmUkIDwOvI3jiPfLrlEDBUCh9woAbqEQ6ejFRa3O55M4X4sPfGLy_GI_UZRpbwYQbZ78sYDX-NRyZxv3clK-xS0fE-zt6nwzaKtLgPQ4r0f2AMO4EMW5gCuVOMfuYva3PN0mWZcDC_M8RxLWeipgnX6F2Ya2nkx3hl4rRi28MqcECdt6_ypqRfmgLaNTYhboKY0xIKjdGxwsmJkCukFnccUizp6GHn1O8oVj0xTIeJzV031mgZq45bbtyWY9vGBXLc0mnirC9n3tkIqey2JiliKMplnudKQeYcwzJ5hEg-IjRpntnokIXbQ2zrKtRGi1lCbvcE-8kW-_hMqWTGqHkW90BSTC2tVCYUMRpvXc-2tMRzn9CEdSEdXmbPUqZWQ_UV6zRPPv3xZ2aTOr3M53szr2KJwNLlaTqR5TqnUP4GV5s8lRP0hGvXpA-_0WLy7QZFuJRo3KrWILOAiYm2Ulgs8lSVuijfX_780_evXr69fPPudXm0H3ZbzW56xXE_-vO94Du001wxVrsmO7Q9KVqf7rQeKnXHbpcTScnGTj1gNzobbfHGn9m1M4kijkfbc8WsAGYrb00apDNv9JzbMbx3-7TM3WwWOEopA8buCmwHEaK73iA8BCExfwGi7dXLYOzVQxBDdQeij7cVw6_SdU4W717_8PLNxYtfB9CeGosJz5znXEKG821FUfrGapHJRKm6XFIzkqJIoJEmNcu1gWsTzKS-EdvolvAUK_YCYlHlhjIxPVPyPZ5fE4In7T1Aba4yzfRIyE8UrgOnd8oAVrZBmDrntbEU-WhPFwmsI_vmsTBxMbrFYeo1YzfpyZPqTKn1yWmqhh1OjqcDNGUbWdgmp-MTpdbnu1n1Vsx7-0kWeb5CJd3RLaHhqCV0rtQ6pW0D_oub0T52O1wSdlrvY6euuh9cKjuj76bsPrZ3E74PO7plJi2_PeyNkjIO1-MO8ffktcDdEaZyDfv2ABkXnQMy8-0BWz3O76SnmWInQAejK24X41Sp9ZM7GBMKxn4ZoytiwhgrtT4dpWkQTazlfbT07jeexs_eb6mVLic36L3w0-qC7LwHTZHRG6rh-FCdHR6Pe7gtbov_AA)** — it opens the
live playground with **this exact plan already loaded**. Change a number and watch it redraw;
the compiler runs in your browser, nothing is sent to a server.

</div>

> **Why a link and not a live embed?** ArchLang *does* ship an embeddable viewer — but
> **GitHub's markdown sanitizer strips `<iframe>`** (it comes back as escaped text, exactly like
> `<script>`), so no README on GitHub can host one. The embed works everywhere GitHub isn't:
> see [Embed a plan anywhere](#embed-a-plan-anywhere). Source:
> [`examples/laneway-house.arch`](examples/laneway-house.arch).

## 🌟 Introduction

**ArchLang** is a small declarative language for floor plans. You *declare* a plan — walls, r