ArchLang

Planos de planta como código — texto adentro, un dibujo arquitectónico preciso afuera.

Un DSL determinista y compilador para planos de planta: escribe (o haz que un LLM escriba) código fuente .arch y se compila a SVG/DXF/PDF con linting y validación geométrica — diferenciable, controlable por versiones, reproducible. Código abierto (MIT). Cero dependencias, y construido para que un agente de IA pueda verificar su propio plano sin mirar una imagen.

▶ Playground en vivo · 📖 Documentación · ⌨ Referencia CLI · 📦 npm · 🧩 VS Code

Úsalo desde tu agente de codificación

npx skills add ChanMeng666/archlang                      # the ArchLang skill, for any agent that reads skills
claude mcp add archlang -- npx -y @chanmeng666/archlang-mcp   # or the MCP server (Claude Code shown)
/plugin marketplace add ChanMeng666/archlang                # or, inside Claude Code: the skills + MCP server as one plugin (plugins/archlang)
/plugin install archlang@archlang

Claude Desktop: cada GitHub Release trae el servidor MCP como una extensión .mcpb de un clic (archlang-mcp-<version>.mcpb), construida por npm run build:mcpb.

Luego pide en lenguaje natural; el agente escribe el .arch, lo compila y lo verifica con lint y describe:

• "Diseña un apartamento de un dormitorio de unos 54 m²: una sala/cocina de 32 m², un dormitorio de 10 m² y un baño de 10 m², con la puerta principal en la pared norte."
• "Dibuja una casa de dos plantas y dos dormitorios, de 8 m × 6 m, con una escalera que conecte los pisos, y dame un SVG por planta."
• "Exporta ese plano como DXF."

Consulta planos de planta que los agentes escribieron a partir de resúmenes de un párrafo, cada uno con su resumen y su código fuente.

[!IMPORTANT]

🤖 Léelo con tu agente de IA — no lo leas a mano.

Este repositorio está escrito priorizando al agente. Apunta Claude Code, GitHub Copilot, Cursor o cualquier agente hacia él: "Lee el README y AGENTS.md, luego ayúdame a ejecutar / ampliar esto." La estructura + AGENTS.md están optimizadas para la comprensión del agente.

👀 Míralo

Aquí hay un programa completo, y debajo el dibujo real al que se compila — no una maqueta. Ni una sola coordenada coloca una puerta, una ventana o un mueble: cada abertura está fijada a una distancia a lo largo de una pared nombrada, cada accesorio se resuelve contra una habitación o una pared, y el baño y el dormitorio se distribuyen mediante un strip. site { street north } nombra las dos fachadas sobre las que gira el plano — la puerta principal da al callejón, el acristalamiento da al jardín.

# 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" }
}

↑ arch compile laneway-house.arch — ese programa, renderizado. Las paredes se unen y se traman solas, las puertas abatibles dibujan sus propios arcos de giro, las hojas correderas y empotradas dibujan paneles en su lugar (una puerta empotrada no tiene arco, porque no tiene giro), y dims auto all mide el edificio que se le dio.

▶ Haz clic en el dibujo — abre el playground en vivo con este plano exacto ya cargado. Cambia un número y míralo redibujar; el compilador se ejecuta en tu navegador, nada se envía a un servidor.

¿Por qué un enlace y no una inserción en vivo? ArchLang sí incluye un visor incrustable — pero el saneador de Markdown de GitHub elimina <iframe> (vuelve como texto escapado, exactamente como <script>), así que ningún README en GitHub puede alojar uno. La inserción funciona en cualquier lugar donde GitHub no esté: consulta Incrusta un plano en cualquier lugar. Fuente: examples/laneway-house.arch.

🌟 Introducción

ArchLang es un pequeño lenguaje declarativo para planos de planta. Declaras un plano — paredes, habitaciones, puertas, ventanas, muebles — y el compilador renderiza un SVG limpio y profesional (también DXF, PDF, PNG y un plano ASCII sin dependencias). Funciona como Typst y LaTeX para documentos: el código fuente es lo que conservas, y el dibujo es lo que el compilador hace con él.

Las coordenadas son milímetros enteros, por lo que la salida es determinista: el mismo código fuente siempre produce bytes idénticos, y cambiar un número cambia exactamente una cosa. "Haz el dormitorio 1 m más ancho" es un diff de un número — no un nuevo render de una imagen rasterizada que redibuja silenciosamente también la cocina.

El compilador es TypeScript puro con cero dependencias en tiempo de ejecución y es isomórfico — el mismo código se ejecuta en Node y en el navegador, por eso el playground es completamente del lado del cliente.

ArchLang es el motor de planos de planta detrás de ArchCanvas, un agente de diseño con IA — pero es independiente y útil en cualquier aplicación o script.

💡 Por qué es diferente

La mayoría de las herramientas de "planos de planta con IA" generan una imagen. Una imagen no se puede verificar, comparar ni razonar — y ni el modelo ni tú pueden saber si el baño es realmente accesible.

ArchLang genera un programa y luego te permite interrogarlo como hechos:

Esa última fila es todo el diseño: compile() nunca lanza excepciones. Devuelve diagnostics con rangos de bytes y una corrección aplicable por máquina, que es lo que hace posible un bucle de autocorrección ajustado.

🤖 El bucle del agente

Un agente puede crear un plano, corregirse a sí mismo y confirmar que el plano coincide con el resumen sin renderizar una imagen en absoluto — que es lo que hace que ArchLang sea barato de manejar desde un modelo solo de texto.

flowchart TD
    B([Brief]) --> S["<b>arch context</b> — the whole language, one call"]
    S --> W["Write <b>.arch</b>"]
    W --> C{"<b>arch compile --json</b>"}
    C -->|"ok: false"| F["<b>arch fix</b><br/><i>each diagnostic carries its own fix</i>"]
    F --> C
    C -->|"ok: true"| D["<b>arch describe --json</b><br/><i>rooms · areas · adjacency · access graph</i>"]
    D --> V{"<b>arch validate --intent</b><br/><i>does it meet the brief?</i>"}
    V -->|"no"| G["<b>arch suggest</b><br/><i>candidate door / window statements</i>"]
    G --> W
    V -->|"yes"| O([SVG · DXF · PDF · PNG])

    style B fill:#ede7f6,stroke:#6b3ae0,color:#1a1a1a
    style O fill:#e8f5e9,stroke:#2e7d32,color:#1a1a1a
    style C fill:#fff8e1,stroke:#7a6000,color:#1a1a1a
    style V fill:#fff8e1,stroke:#7a6000,color:#1a1a1a
    style D fill:#e8f5e9,stroke:#2e7d32,color:#1a1a1a
    style F fill:#fdecea,stroke:#b3261e,color:#1a1a1a
    style G fill:#fdecea,stroke:#b3261e,color:#1a1a1a

Arranque en frío con un comando. arch context imprime todo el contexto del agente — especificación del lenguaje, habilidad de flujo de trabajo, referencia CLI y cada código de diagnóstico — como un documento listo para prompt de sistema (el mismo llms-full.txt que sirve el sitio de documentación).

npx @chanmeng666/archlang context                       # EVERYTHING: spec + skill + CLI + error catalog
npx @chanmeng666/archlang context --section errors      # …or one section of it (the catalog alone: 60 KB → 13 KB)
npx @chanmeng666/archlang spec                          # just the language, one page (~2k tokens)
npx @chanmeng666/archlang help describe                 # one command, with worked examples
npx @chanmeng666/archlang compile plan.arch --json      # render → { ok, diagnostics, summary }
npx @chanmeng666/archlang fix plan.arch --dry-run       # the exact unified diff it would write, applying nothing
npx @chanmeng666/archlang describe plan.arch --json     # VERIFY, without an image
npx @chanmeng666/archlang validate plan.arch --strict   # the ship gate

Cada comando acepta --json (resultado en stdout, mensajes en stderr) con códigos de salida deterministas (0 ok · 2 error de código fuente del usuario · 1 IO · 3 uso) — y un error tipográfico gana ese 3: arch lint --jsn exits 3 with ¿quisiste decir --json? rather than quietly reading --jsn como nombre de archivo, y arch comple sugiere compile.

Un manifiesto, sin desviaciones. La ayuda por comando (arch <cmd> --help), el analizador de banderas y la referencia CLI generada se renderizan desde el mismo manifiesto — por eso no pueden anunciar una bandera que un comando no acepta. arch manifest --json es ese manifiesto como datos, y arch <cmd> --help es la forma económica de leer una fila de él.

Las lecturas están limitadas, por lo que un plano grande no puede inundar una ventana de contexto: describe --select/--room, lint|validate --code/--severity, context --section. Filtrar lo que lees nunca cambia lo que determina — el código de salida siempre sopesa cada diagnóstico. Y como arch fix reescribe tu código fuente, imprime primero el diff unificado y acepta --backup.

Consulta SKILL.md.

claude mcp add archlang -- npx -y @chanmeng666/archlang-mcp

✨ Características

🚀 Inicio rápido

npx @chanmeng666/archlang new -o plan.arch          # scaffold a starter plan
npx @chanmeng666/archlang compile plan.arch -o plan.svg

O instálalo:

npm install @chanmeng666/archlang

Como biblioteca (cero dependencias, funciona en Node y en el navegador):

import { compile } from "@chanmeng666/archlang";

const { svg, diagnostics } = compile(`
plan "Tiny" {
  units mm
  grid 50
  wall exterior thickness 200 { (0,0) (4000,0) (4000,3000) (0,3000) close }
  room id=r at (0,0) size 4000x3000 label "Studio"
  door at (2000,3000) width 900 wall exterior hinge left swing in
  window at (0,1500) width 1200 wall exterior
}`);

// compile() never throws — errors come back as data, each with a span and a fix.
if (diagnostics.some((d) => d.severity === "error")) console.error(diagnostics);
else writeFileSync("tiny.svg", svg);

También exportado, todo puro: describe() (hechos), lint() (solidez), validateIntent() + projectSubscores() (¿coincide con el brief?), repair(), applyFixes(), suggestTopology(), renderAscii(), toDxf() y el núcleo LSP (completion, hover, …).

npm install          # one install bootstraps every workspace
npm run build        # build the library + CLI into dist/
npm run check        # typecheck + lint + the full test suite
npm run check:drift  # every generated artifact must match its source
npm run playground:dev   # build the core, then open the playground

🖼️ Galería

Cada uno de estos es un ejemplo real y compilado de examples/ — y cada dibujo en esta página está generado desde su fuente por npm run gen:example-svgs, así que una imagen aquí nunca puede desviarse del compilador que la creó. Haz clic en un dibujo para abrirlo en el playground, o en el nombre para ver la fuente.

La pieza central — todo el lenguaje en una sola hoja: orientación site, un polígono como rincón de lectura y una suite principal en forma de L, un arco de bahía curvado, los cinco tipos de puertas, un hueco de escalera compartido, un vacío sobre el salón de doble altura, un alero de techo y un par de baños en suite reflejados compuestos desde un único component. Cada habitación es accesible, cada puerta despeja y las tres advertencias que arch lint aún genera se dejan a propósito y se explican en la fuente.

hillside-villa

El plano del sitio — el mismo lenguaje aplicado a todo lo que está FUERA de la línea de muro: un límite de parcela topografiado, nueve outdoor de materiales de suelo desde césped hasta piscina, un fence publicado alrededor del agua, un garage con el sexto tipo de puerta y catorce familias de mobiliario exterior desde los contenedores hasta el trampolín. El suelo se dibuja y se mide, pero enfáticamente no es área de piso.

garden-house

studio El buque insignia: cocina y baño equipados, un baño cerrado desde un pasillo central. Limpio de lint y sin imports.	two-bed Una vivienda más grande: corredor central, cinco habitaciones, ventanas en tres muros exteriores.	attached Sin coordenadas calculadas a mano en absoluto: franjas, aberturas en muro, anclajes.
bungalow El vocabulario de puertas: correderas, de bolsillo y abatibles — paneles, no arcos.	hexagon-pavilion Seis habitaciones poligonales alrededor de una rotonda circular: room … polygon se encuentra con room circle.	terrace-row Un component, placed cuatro veces — reflejados en pares, anchos desde un arreglo let.
library Un edificio público en una hoja real: A2 a 1:200, ejes, cuadro y leyenda.	transit-hall Un vestíbulo: lados de pago y no pago, una serie generada de torniquetes y quioscos.	aquarium Arcos verdaderos, una habitación circular y áreas exactas de πR² — nunca facetados a ningún zoom.
museum La hoja más grande del corpus: A1 a 1:200, galerías, recepción y cafetería.	gallery-l El buque insignia de habitaciones poligonales, amueblado y probado contra `theme presentation`.	materials Anulaciones de `style` por elemento — materiales de muro y rellenos de trama, amueblado.

Y uno que está aquí por su mobiliario — el catálogo de símbolos dibujados en un solo plano, desde el anillo del asiento del inodoro hasta el riel colgante del armario. Veintiséis tipos; ninguno lleva un label, y la mayoría tampoco lleva size:

furnished-flat

Dos más, dibujados en una hoja más pequeña — el mismo lenguaje, dispuesto a una escala fija dentro de un borde A3 con título en lugar de ajustarse a su propio dibujo:

courtyard-house Un anillo de habitaciones alrededor de un patio abierto — el caso donde la cara exterior de una ventana no es el lado que su cuadro delimitador sugiere.	townhouse Tres plantas en un solo archivo (planta baja mostrada) — bloques level, un hueco de escalera, un dibujo por página.
two-storey Un vacío sobre la galería de la planta baja, y aleros en la planta superior.	tiny-house Puertas de granero y abatibles en una carcasa de 7,2 x 3 m, ahora con aleros — roof overhang.

También en examples/ — todo el corpus, por lo que está ahí para mostrar:

• Pieza estrella — hillside-villa (el lenguaje completo en una sola hoja).
• Empieza aquí — one-room (el plan más pequeño que dibuja algo), studio (el buque insignia sin errores de lint), attached (nada posicionado a mano).
• Viviendas — laneway-house, tiny-house, garden-loft, two-bed, bungalow, furnished-flat (el buque insignia del mobiliario), courtyard-house, townhouse (tres plantas), terrace-row (un componente, colocado cuatro veces), two-storey, accessible (accTitle/accDescr).
• Edificios públicos — library, transit-hall, clinic, museum (A1 a 1:200), hexagon-pavilion.
• Geometría y experimentos — gallery-l (habitaciones poligonales), aquarium (arcos y círculos).
• Scripting y composición — parametric (un bucle for que genera unidades), relational (right-of / below), imports, museum-wing + museum-wings (un ala, importada y colocada dos veces).
• Estilo — themed (un tema personalizado + tramado de ladrillo), materials (anulaciones de style por elemento y materiales de pared).

La galería de documentación renderiza todos ellos en vivo y editables en el navegador.

🎬 Escaparate

Los ejemplos anteriores enseñan el lenguaje. El Escaparate es lo que sucede cuando lo aplicas a edificios reales y a famosos ficticios: la West Wing (cuyo Despacho Oval es un verdadero arc, no un polígono facetado), la Villa La Rotonda de Palladio (un cuarto, placed cuatro veces), Bag End, de_dust2, The Skeld, 742 Evergreen Terrace, el anexo de Dunder Mifflin. Cada uno son unas pocas docenas de líneas de código fuente que puedes abrir en el playground y recompilar.

Merece la pena verlos tanto por lo que el compilador dice sobre ellos como por los dibujos: arch lint informa de un W_NO_ENTRANCE real en de_dust2 — un cuarto de siglo de ocupación continua, logrado enteramente mediante generación — y revisa un apartamento de ferrocarril de 2.950 $ al mes en doce avisos repartidos en nueve códigos.

archlang.uk/showcase para el conjunto seleccionado · ChanMeng666/archlang-showcase para el código fuente de cada plano y la historia que hay detrás.

🏗️ Cómo funciona

ArchLang es un pipeline de compilador. El texto fuente se convierte en un Scene IR neutral respecto al backend, y cada backend es un serializador puro de esa escena — por eso añadir un formato nunca toca el lenguaje.

flowchart TD
    SRC["<b>.arch</b> source"] --> LEX["<b>lexer</b><br/><i>hand-written → tokens with byte spans</i>"]
    LEX --> PAR["<b>parser</b><br/><i>recursive descent → AST · recovers, never throws</i>"]
    PAR --> IR["<b>resolve()</b><br/><i>expand scripting · grid-snap<br/>relational placement · host openings</i>"]

    IR -->|"render"| SCN["<b>toScene()</b><br/><i>wall union · hatches · page</i>"]
    IR -->|"read back"| DESC["<b>describe() · lint() · validateIntent()</b><br/><i>the SAME resolved plan, as FACTS —<br/>no rendering required</i>"]

    SCN --> SVG["<b>SVG</b><br/><sub>zero-dep</sub>"]
    SCN --> DXF["<b>DXF</b><br/><sub>zero-dep</sub>"]
    SCN --> TXT["<b>TXT</b><br/><sub>zero-dep</sub>"]
    SCN --> PDF["<b>PDF</b><br/><sub>optional</sub>"]
    SCN --> PNG["<b>PNG</b><br/><sub>optional</sub>"]

    DESC --> FACTS(["rooms · areas · adjacency<br/>access graph · intent score"])

    style SRC fill:#ede7f6,stroke:#6b3ae0,color:#1a1a1a
    style IR fill:#eceef2,stroke:#464d59,color:#1a1a1a
    style SCN fill:#eceef2,stroke:#464d59,color:#1a1a1a
    style DESC fill:#e8f5e9,stroke:#2e7d32,color:#1a1a1a
    style FACTS fill:#e8f5e9,stroke:#2e7d32,color:#1a1a1a
    style SVG fill:#fbfbfc,stroke:#464d59,color:#1a1a1a
    style DXF fill:#fbfbfc,stroke:#464d59,color:#1a1a1a
    style TXT fill:#fbfbfc,stroke:#464d59,color:#1a1a1a
    style PDF fill:#fbfbfc,stroke:#8a8f98,color:#1a1a1a
    style PNG fill:#fbfbfc,stroke:#8a8f98,color:#1a1a1a

La rama punteada es el punto clave: describe, lint y la comprobación de intención leen el mismo plan resuelto que el renderizador — así que lo que un agente verifica es exactamente lo que se dibuja, y no cuesta ni un píxel comprobarlo.

compile() es puro, síncrono y determinista — sin E/S, sin Date.now(), sin Math.random(). El único lugar donde se permiten las APIs de Node es la CLI; todo lo demás recibe su entorno a través de una costura World. Consulta AGENTS.md y los ADRs.

📦 Ecosistema

Incrusta un plano en cualquier lugar

Un plano en vivo y editable en cualquier blog, wiki o página de documentación — un <iframe>, sin paso de compilación, nada enviado a un servidor (el código fuente viaja en el hash #z= comprimido, así que la página es autocontenida):

<iframe src="https://playground.archlang.uk/embed.html#z=…" width="720" height="480"></iframe>

El botón Embed del playground genera el fragmento. Parámetros opcionales: editable=1 (mostrar un editor compacto que se re-renderiza mientras escribes) y theme=blueprint|dark|mono|presentation.

Pero no en GitHub. El saneador de Markdown de GitHub elimina <iframe> — se renderiza como texto escapado, igual que <script> — así que un README (aquí o en cualquier lugar de github.com) no puede alojar un embed en vivo, sin importar cómo se escriba. Los sustitutos honestos que GitHub sí permite son los que este README usa: un SVG estático que el compilador realmente produjo, enlazado a un permalink del playground que abre el mismo plano en vivo. En el sitio de documentación, donde el saneador no aplica, cada plano es en vivo y editable en su lugar.

📚 Documentación

• 📖 Sitio de documentación — guía, referencia, catálogo de errores, ADRs y una galería de ejemplos en vivo y editable. Cada bloque ```arch en una página de documentación es en sí mismo un plano editable.
• ⌨ Referencia de CLI — cada comando, bandera y código de salida (generado desde el manifiesto, así que no puede quedarse desactualizado).
• spec.llm.md — el lenguaje completo en una página (~2k tokens) para agentes de IA; también arch spec.
• SKILL.md — la habilidad del agente: el bucle spec → compile → fix → describe → validate.
• Referencia del lenguaje · Catálogo de errores · El contrato de intención · ADRs
• AGENTS.md — orientación para agentes de IA que trabajan en este repositorio.
• Notas de versión — cada versión, incluido lo que cambia para el código que incrusta o analiza la salida. Instaladas, están en node_modules/@chanmeng666/archlang/CHANGELOG.md; la sección de cada etiqueta es también su Release de GitHub.

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Por favor, lee la Guía de contribución y nuestro Código de conducta. Usa las plantillas de issue y pull-request cuando abras una.

❤️ Soporte y patrocinio

• ¿Preguntas? Abre una Discusión o consulta SUPPORT.md.
• ¿Has encontrado un problema de seguridad? Sigue SECURITY.md.
• Si este proyecto te ayuda, considera patrocinar ☕.

📄 Licencia

Publicado bajo la licencia MIT.

Chan Meng
¿Necesitas una aplicación personalizada como esta? Yo las construyo — hablemos.