# Sketchitor — Machine-Readable Grammar Reference
# Plain-text format for LLM context injection.
# See also: https://sketchitor.com/manual

# ─── File Structure ──────────────────────────────────────────────────────────

A .sketch file is a sequence of lines, each one of:
  - A blank line or comment (# ...)
  - A global directive   @name value
  - A shape command      shapeName key=value ...
  - A shape command with a nested block:
      shapeName key=value ... {
        childShapeName key=value ...
      }

# ─── Directives (@) ──────────────────────────────────────────────────────────

@seed          <int>           — PRNG seed for reproducible output (default: random)
@roughness     <float>         — global line roughness 0‥∞ (default 1.0)
@bowing        <float>         — global line bowing 0‥∞ (default 1.0)
@theme         light | dark    — colour theme (default light)
@shadow        true | false    — drop shadow on all shapes (default false)
@font          hand-drawn | virgil | mono  (default hand-drawn)
@fontSize      <float>         — global font size in px
@strokeColor   <color>         — global stroke colour
@fillColor     <color>         — global fill colour
@strokeWidth   <float>         — global stroke width

# ─── Coordinate System ───────────────────────────────────────────────────────

Origin (0,0) is the centre of the SVG viewport.
x increases to the right; y increases downward.
Shapes are positioned by their bounding-box centre (x=, y=).
Sizes and positions are in abstract canvas units (≈ pixels at 1× zoom).

# ─── Common Parameters (all shapes) ─────────────────────────────────────────

id=<ident>              — unique identifier for anchor references
label=<markdown-string> — text label rendered inside/below the shape;
                          parsed as CommonMark markdown (see Markdown Labels).
                          Supports triple-quoted strings for multi-line content.
text=<string>           — alias for label=
font=hand-drawn|virgil|mono
fontSize=<float>        — label font size in px (default 16)
color=<color>           — label text colour
textAnchor=start|middle|end
wrapWidth=<float>       — word-wrap width in canvas units
roughness=<float>       — per-shape roughness override
bowing=<float>          — per-shape bowing override
strokeColor=<color>     — stroke colour
strokeWidth=<float>     — stroke width
fillColor=<color>       — fill colour  (none = transparent)
fillStyle=hachure|cross-hatch|solid|zigzag|dots|dashed|zigzag-line
shadow=true|false        — drop shadow for this shape
multi=true|false         — stacked copies effect
origin=center|topleft|topright|bottomleft|bottomright|top|bottom|left|right

# ─── Expressions in Parameter Values ────────────────────────────────────────

Numeric parameters accept arithmetic expressions:
  x = 100 + 50
  width = box1.right.x - box1.left.x

Anchor references (resolve to a coordinate pair):
  from = box1.bottomright          → Point at bottom-right corner of box1
  x    = box1.center.x + 20       → x-coordinate of box1 centre + 20

Anchor names: top, bottom, left, right, center, middle,
              topleft, topright, bottomleft, bottomright, start, end

# ─── Basic Shapes ────────────────────────────────────────────────────────────

rectangle  x= y= width= height= [cornerRadius=<float>]
circle     x= y= width=           (width = diameter)
ellipse    x= y= width= height=

# ─── Advanced Shapes ─────────────────────────────────────────────────────────

diamond       x= y= width= height=
hexagon       x= y= width= height=
parallelogram x= y= width= height= [skew=<float, default 0.3>]
triangle      x= y= width= height=
cylinder      x= y= width= height=
cloud         x= y= width= height=
page          x= y= width= height= [foldSize=<0‥1, default 0.15>]
document      x= y= width= height=
step          x= y= width= height= [notch=<0‥1, default 0.15>]
callout       x= y= width= height= [tailX= tailY= tailW=]
package       x= y= width= height= [tabWidth=<0‥1, default 0.35>]
person        x= y= width= height=   (label appears below the figure)
stored-data   x= y= width= height=

# ─── Path / Freeform Shapes ──────────────────────────────────────────────────

linearpath  points="x1,y1 x2,y2 ..."
polygon     points="x1,y1 x2,y2 ..."
curve       points="x1,y1 x2,y2 ..."
path        d="<SVG path data>"

# ─── Text ─────────────────────────────────────────────────────────────────────

# "text" is a transparent-border box (no stroke, no fill background).
# It supports full markdown in its label= and exposes the same anchor points
# as any other box shape so arrows can connect to it.

text  x= y= width=300 height=200 label=<markdown-string>
      [font= fontSize= color= textAnchor= wrapWidth=]

# ─── Markdown Labels ────────────────────────────────────────────────────────

# ALL shapes parse their label= value as CommonMark markdown.
# Supported syntax:

# Headings        # H1  ## H2  ### H3  #### H4  ##### H5
# Bold            **text**
# Italic          *text*
# Bold+Italic     ***text***
# Strikethrough   ~~text~~
# Inline code     `code`
# Link            [label](url)   → clickable SVG <a href="url">
# Block image     ![alt](src)    → SVG <image> element
# Unordered list  - item
# Ordered list    1. item
# Fenced code     ```\n…\n```
# Thematic break  ---
# Hard line break two trailing spaces or \
# Emoji           pass-through Unicode (🎉 🚀 ✨)
#
# Plain text (no markdown syntax) renders identically to the old behaviour.
# Triple-quoted strings ("""…""") and \n escapes work as usual.

# Example:
# text x=0 y=0 width=400 height=200 label="""# Title
# **Bold** and *italic* and ~~strike~~.
# - Item one
# - Item two
# [Click here](https://example.com)
# """ size=14

# ─── Connections ─────────────────────────────────────────────────────────────

arrow   from=<id[.anchor]> to=<id[.anchor]> [label= labelPos=above|below|left|right]
line    from=<id[.anchor]> to=<id[.anchor]> [label= labelPos=]
connect from=<id[.anchor]> to=<id[.anchor]> [label= labelPos=]

Arrow / line style parameters:
  arrowHead=normal|open|none
  arrowTail=normal|open|none
  dashed=true|false
  strokeWidth=<float>

# ─── Fill Styles ─────────────────────────────────────────────────────────────

hachure       — diagonal hatching lines (default when fillColor set)
cross-hatch   — two-direction hatching
solid         — flat solid fill
zigzag        — zigzag hatching
dots          — dot pattern
dashed        — dashed hatching
zigzag-line   — zigzag-line pattern

# ─── Colour Values ───────────────────────────────────────────────────────────

Any CSS colour string: "#rrggbb", "rgba(…)", "red", etc.
Theme tokens: "theme:text", "theme:stroke", "theme:background",
              "theme:fill-neutral", "theme:fill-primary",
              "theme:fill-success", "theme:fill-warning",
              "theme:fill-danger", "theme:fill-info", "theme:fill-muted"

# ─── Example ─────────────────────────────────────────────────────────────────

@roughness 1.2
@theme light

rectangle id=start x=0 y=-150 width=160 height=60 fillColor="#d5f4e6" label="Start"
diamond   id=check x=0 y=0    width=160 height=100 fillColor="#fef9e7" label="OK?"
rectangle id=done  x=0 y=150  width=160 height=60  fillColor="#fdedec" label="Done"

arrow from=start.bottom to=check.top
arrow from=check.bottom to=done.top label="yes" labelPos=right