docs(api): per-symbol pages, fuzzy search, deep token linking, hover cards

Rebuild the API Reference around one page per symbol and richer, verified content.

Pages & navigation
- One HTML page per symbol (kw-*, type-*, phase-*, screen-*, fn-*, annot-*, op-*)
  instead of a single scrolling page; namespace overview pages (ns-screen …
  ns-color) and a searchable index (api.html) with client-side fuzzy search.
- Sticky-header scroll offset (scroll-margin) so a jumped-to entry/param/color is
  never hidden, plus a flash highlight on the scrolled-to target.

Deep linking in every snippet & example
- Namespace members split: `Screen`→namespace page, `fill_rectangle`→method page;
  `Color`→palette page, `Charcoal`→its swatch — separately.
- Named arguments (`width:`) link to that parameter's anchor on the method page.
- Hover any token for a summary card built from the real API data (symbols.json).

Content & coverage
- Full authoritative surface documented from the compiler: every keyword, type,
  the 6 phases (Start/Input/FixedUpdate/Update/LateUpdate/Render, each its own
  page), all 22 annotations, namespace methods with parameter docs, builtins,
  the world_* reflection ABI, networking, operators — 155 symbols.
- Longer, clearer explanations; "model"/"model instance" terminology, not "entity";
  descriptive identifiers in every example (Position{column,row}, Velocity{delta_x,
  delta_y}, Health{current,maximum}, Player/Enemy) — no Pos/Seg/x/dx.
- Accuracy fixes from compiler ground-truth: world_count() takes no arg,
  world_query_next(property, cursor) arg order, event fields bind by name; dropped
  `when` and `module` (not in the self-hosted parser).

Tooling
- inventory.json + check.py: coverage guard (every symbol has a page), duplicate-
  token guard, and broken-link guard — fail CI so docs can't drift.
- validate.py: compiles every ```ludic example against bin/ludicc (158 compile).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/language/screen/screen-clear.md

@@ -5,12 +5,29 @@ category: screen
 kind: namespace-method
 tokens: Screen.clear
 sig: Screen.clear(color)
-tip: Fill the entire screen with one color.
+tip: Fill the whole framebuffer with one color to start a fresh frame.
 order: 0
+ns: Screen
+member: clear
 ---
 
-Fill the entire screen with one color.
+Paints every pixel of the framebuffer a single color, wiping whatever the previous frame drew. Call it first inside your <code>Render</code> handler so each frame starts from a known background instead of leftover pixels. The one argument is a color, which can be a named palette value such as <code>Color.MidnightBlue</code> or a raw hex literal like <code>0x0d1020</code>. After clearing, draw the scene on top and finish with <code>Screen.show()</code>.
+
+Parameters:
+- `color` — the background color to fill with, e.g. a `Color.*` name or a `0xRRGGBB` literal
 
 ```ludic
-Screen.clear(Color.MidnightBlue)
+program ClearBackground {
+  var elapsed_frames: int = 0
+
+  handler CountFrames phase Update {
+    elapsed_frames = elapsed_frames + 1
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    Screen.draw_number(x: 8, y: 8, value: elapsed_frames, color: Color.White, scale: 1)
+    Screen.show()
+  }
+}
 ```

docs/language/screen/screen-draw_number.md

@@ -5,12 +5,34 @@ category: screen
 kind: namespace-method
 tokens: Screen.draw_number
 sig: Screen.draw_number(x, y, value, color, scale)
-tip: Draw an integer — no allocation, no string conversion.
+tip: Draw an integer directly, with no string allocation or conversion.
 order: 5
+ns: Screen
+member: draw_number
 ---
 
-Draw an integer — no allocation, no string conversion.
+Draws an integer as digits using the built-in font, without first turning it into a string — so it never allocates and is safe to call every frame for constantly-changing values. Use it for scores, timers, frame counts, health totals, and any HUD number, while reserving <code>Screen.draw_text</code> for fixed labels. It takes the same top-left position, color, and integer <code>scale</code> as <code>draw_text</code>. Negative values are drawn with a leading minus sign.
+
+Parameters:
+- `x` — the left edge of the first digit, in pixels
+- `y` — the top edge of the number, in pixels
+- `value` — the integer to draw
+- `color` — the digit color, e.g. a `Color.*` name or a `0xRRGGBB` literal
+- `scale` — integer size multiplier (`1` = native size)
 
 ```ludic
-Screen.draw_number(x: 52, y: 4, value: score, color: Color.Gold, scale: 1)
+program ScoreHud {
+  var score: int = 0
+
+  handler EarnPoints phase Update {
+    score = score + 1
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    Screen.draw_text(x: 6, y: 4, text: "SCORE", color: Color.White, scale: 1)
+    Screen.draw_number(x: 52, y: 4, value: score, color: Color.Gold, scale: 1)
+    Screen.show()
+  }
+}
 ```

docs/language/screen/screen-draw_rectangle.md

@@ -5,8 +5,41 @@ category: screen
 kind: namespace-method
 tokens: Screen.draw_rectangle
 sig: Screen.draw_rectangle(x, y, width, height, color)
-tip: Draw a one-pixel rectangle outline.
+tip: Draw a one-pixel-thick rectangle outline (not filled).
 order: 2
+ns: Screen
+member: draw_rectangle
 ---
 
-Draw a one-pixel rectangle outline.
+Draws just the border of a rectangle — a one-pixel-thick outline — leaving the interior untouched so whatever is behind it shows through. It takes the same top-left position and size as <code>Screen.fill_rectangle</code>, but is meant for framing rather than filling: selection boxes, UI panels, health-bar borders, or highlighting the tile under a cursor. Use it together with <code>fill_rectangle</code> when you want a filled shape with a contrasting edge. Coordinates are in pixels from the top-left of the screen.
+
+Parameters:
+- `x` — the left edge, in pixels from the left of the screen
+- `y` — the top edge, in pixels from the top of the screen
+- `width` — the outline width in pixels
+- `height` — the outline height in pixels
+- `color` — the outline color, e.g. a `Color.*` name or a `0xRRGGBB` literal
+
+```ludic
+program SelectionFrame {
+  property Position { column: int = 0, row: int = 0 }
+  model Enemy { Position }
+
+  const TILE_SIZE: int = 16
+
+  handler SpawnEnemy phase Start {
+    spawn Enemy { Position { column: 6, row: 5 } }
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    for (Position) in query [Position, {Enemy}] {
+      let pixel_x = Position.column * TILE_SIZE
+      let pixel_y = Position.row * TILE_SIZE
+      Screen.fill_rectangle(x: pixel_x, y: pixel_y, width: TILE_SIZE, height: TILE_SIZE, color: Color.Crimson)
+      Screen.draw_rectangle(x: pixel_x, y: pixel_y, width: TILE_SIZE, height: TILE_SIZE, color: Color.Gold)
+    }
+    Screen.show()
+  }
+}
+```

docs/language/screen/screen-draw_text.md

@@ -7,10 +7,32 @@ tokens: Screen.draw_text
 sig: Screen.draw_text(x, y, text, color, scale)
 tip: Draw a string with the built-in font at an integer scale.
 order: 4
+ns: Screen
+member: draw_text
 ---
 
-Draw a string with the built-in font at an integer scale.
+Draws a string using Ludic's built-in bitmap font, starting at the top-left pixel <code>(x, y)</code>. The <code>scale</code> is an integer multiplier: <code>1</code> is the native font size, <code>2</code> is double-height and double-width, and so on — there are no fractional sizes. Use it for labels, menus, and messages such as titles or "GAME OVER"; for numbers that change every frame prefer <code>Screen.draw_number</code>, which needs no string conversion. The text is drawn in the given color over whatever is already on screen.
+
+Parameters:
+- `x` — the left edge of the first character, in pixels
+- `y` — the top edge of the text, in pixels
+- `text` — the string to draw
+- `color` — the text color, e.g. a `Color.*` name or a `0xRRGGBB` literal
+- `scale` — integer size multiplier (`1` = native size)
 
 ```ludic
-Screen.draw_text(x: 6, y: 4, text: "SCORE", color: Color.White, scale: 1)
+program TitleScreen {
+  var elapsed_frames: int = 0
+
+  handler CountFrames phase Update {
+    elapsed_frames = elapsed_frames + 1
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    Screen.draw_text(x: 40, y: 60, text: "CHRONORIFT", color: Color.Gold, scale: 3)
+    Screen.draw_text(x: 64, y: 120, text: "PRESS ANY KEY", color: Color.White, scale: 1)
+    Screen.show()
+  }
+}
 ```

docs/language/screen/screen-fill_rectangle.md

@@ -5,12 +5,43 @@ category: screen
 kind: namespace-method
 tokens: Screen.fill_rectangle
 sig: Screen.fill_rectangle(x, y, width, height, color)
-tip: Draw a filled rectangle.
+tip: Draw a solid, filled rectangle at a pixel position.
 order: 1
+ns: Screen
+member: fill_rectangle
 ---
 
-Draw a filled rectangle.
+Draws a solid block of color from the top-left corner <code>(x, y)</code> spanning <code>width</code> by <code>height</code> pixels. This is the workhorse for drawing tiles, sprites-from-primitives, health bars, and background panels, since a Ludic game paints every pixel itself rather than loading image assets. Coordinates are in pixels measured from the top-left of the screen, so multiply a grid <code>column</code>/<code>row</code> by your tile size to place things on a board. Parts of the rectangle that fall outside the framebuffer are simply clipped.
+
+Parameters:
+- `x` — the left edge, in pixels from the left of the screen
+- `y` — the top edge, in pixels from the top of the screen
+- `width` — the rectangle width in pixels
+- `height` — the rectangle height in pixels
+- `color` — the fill color, e.g. a `Color.*` name or a `0xRRGGBB` literal
 
 ```ludic
-Screen.fill_rectangle(x: 8, y: 8, width: 16, height: 16, color: Color.Crimson)
+program FilledTiles {
+  property Position { column: int = 0, row: int = 0 }
+  model Player { Position }
+
+  const TILE_SIZE: int = 16
+
+  handler SpawnPlayer phase Start {
+    spawn Player { Position { column: 4, row: 3 } }
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    for (Position) in query [Position, {Player}] {
+      Screen.fill_rectangle(
+        x: Position.column * TILE_SIZE,
+        y: Position.row * TILE_SIZE,
+        width: TILE_SIZE,
+        height: TILE_SIZE,
+        color: Color.LimeGreen)
+    }
+    Screen.show()
+  }
+}
 ```

docs/language/screen/screen-height.md

@@ -5,8 +5,37 @@ category: screen
 kind: namespace-method
 tokens: Screen.height
 sig: Screen.height() -> int
-tip: Framebuffer height in pixels.
+tip: The framebuffer height in pixels.
 order: 8
+ns: Screen
+member: height
 ---
 
-Framebuffer height in pixels.
+Returns the height of the framebuffer in pixels — the number of drawable rows. Use it, together with <code>Screen.width</code>, to position elements relative to the bottom or vertical center of the screen instead of assuming a fixed size. A common use is keeping a moving object on screen by clamping its pixel row against this value. It takes no arguments and can be read during any handler.
+
+```ludic
+program GroundLine {
+  property Position { column: int = 0, row: int = 0 }
+  model Player { Position }
+
+  const TILE_SIZE: int = 16
+
+  handler SpawnPlayer phase Start {
+    spawn Player { Position { column: 3, row: 0 } }
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    let ground_y = Screen.height() - TILE_SIZE
+    for (Position) in query [Position, {Player}] {
+      Screen.fill_rectangle(
+        x: Position.column * TILE_SIZE,
+        y: ground_y,
+        width: TILE_SIZE,
+        height: TILE_SIZE,
+        color: Color.LimeGreen)
+    }
+    Screen.show()
+  }
+}
+```

docs/language/screen/screen-put_pixel.md

@@ -5,8 +5,42 @@ category: screen
 kind: namespace-method
 tokens: Screen.put_pixel
 sig: Screen.put_pixel(x, y, color)
-tip: Set a single pixel.
+tip: Set a single pixel at a pixel coordinate to one color.
 order: 3
+ns: Screen
+member: put_pixel
 ---
 
-Set a single pixel.
+Sets exactly one pixel at <code>(x, y)</code> to the given color — the finest-grained drawing operation Ludic offers. Reach for it when you are plotting individual points such as stars, particles, a scatter of sparks, or hand-drawn curves where a full rectangle would be too coarse. For anything larger than a point prefer <code>Screen.fill_rectangle</code>, since one call per pixel is far more expensive than one call per block. Coordinates are pixels from the top-left of the screen, and out-of-range coordinates are ignored.
+
+Parameters:
+- `x` — the pixel column, in pixels from the left of the screen
+- `y` — the pixel row, in pixels from the top of the screen
+- `color` — the pixel color, e.g. a `Color.*` name or a `0xRRGGBB` literal
+
+```ludic
+program Starfield {
+  property Position { column: int = 0, row: int = 0 }
+  model Star { Position }
+
+  handler SeedStars phase Start {
+    Random.seed(value: 1)
+    for spawn_index in 0 .. 40 {
+      spawn Star {
+        Position {
+          column: Random.range(low: 0, high: 255),
+          row: Random.range(low: 0, high: 223)
+        }
+      }
+    }
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    for (Position) in query [Position, {Star}] {
+      Screen.put_pixel(x: Position.column, y: Position.row, color: Color.White)
+    }
+    Screen.show()
+  }
+}
+```

docs/language/screen/screen-show.md

@@ -5,12 +5,36 @@ category: screen
 kind: namespace-method
 tokens: Screen.show
 sig: Screen.show()
-tip: Present the finished frame — copy everything you have drawn to the window.
+tip: Present the finished frame — copy everything drawn this frame to the window.
 order: 6
+ns: Screen
+member: show
 ---
 
-Present the finished frame — copy everything you have drawn to the window. Call it once, last, in your Render handler.
+Presents the frame: it copies everything you have drawn into the framebuffer this pass onto the visible window all at once. Call it exactly once, as the very last statement of your <code>Render</code> handler, after every <code>Screen.clear</code>, <code>fill_rectangle</code>, <code>draw_text</code>, and other draw call. Because drawing happens off-screen and only <code>show</code> makes it visible, the player never sees a half-drawn frame (no flicker or tearing). Forgetting to call it means your drawing never appears; it takes no arguments.
 
 ```ludic
-Screen.show()
+program PresentFrame {
+  property Position { column: int = 0, row: int = 0 }
+  model Player { Position }
+
+  const TILE_SIZE: int = 16
+
+  handler SpawnPlayer phase Start {
+    spawn Player { Position { column: 5, row: 5 } }
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    for (Position) in query [Position, {Player}] {
+      Screen.fill_rectangle(
+        x: Position.column * TILE_SIZE,
+        y: Position.row * TILE_SIZE,
+        width: TILE_SIZE,
+        height: TILE_SIZE,
+        color: Color.LimeGreen)
+    }
+    Screen.show()
+  }
+}
 ```

docs/language/screen/screen-status.md

@@ -5,8 +5,29 @@ category: screen
 kind: namespace-method
 tokens: Screen.status
 sig: Screen.status(text)
-tip: Set the persistent one-line status/HUD string.
+tip: Set the persistent one-line status/HUD string shown by the runtime.
 order: 9
+ns: Screen
+member: status
 ---
 
-Set the persistent one-line status/HUD string.
+Sets a single persistent line of status text that the runtime displays outside your normal drawing — a lightweight HUD line for debugging or a title-bar style message. Unlike <code>Screen.draw_text</code>, it is not part of the framebuffer you clear and present each frame: you set it once (or whenever it changes) and it persists until you set it again. Use it for coarse status such as the current level, connection state, or a frame-rate readout while iterating. It takes a single string argument.
+
+Parameters:
+- `text` — the status line to display
+
+```ludic
+program StatusLine {
+  var elapsed_frames: int = 0
+
+  handler UpdateStatus phase Update {
+    elapsed_frames = elapsed_frames + 1
+    Screen.status(text: `frame {elapsed_frames}`)
+  }
+
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    Screen.show()
+  }
+}
+```

docs/language/screen/screen-width.md

@@ -5,8 +5,22 @@ category: screen
 kind: namespace-method
 tokens: Screen.width
 sig: Screen.width() -> int
-tip: Framebuffer width in pixels.
+tip: The framebuffer width in pixels.
 order: 7
+ns: Screen
+member: width
 ---
 
-Framebuffer width in pixels.
+Returns the width of the framebuffer in pixels — the number of drawable columns. Use it to lay out and center content relative to the actual screen size rather than hard-coding a fixed number, so your HUD or menu stays positioned correctly if the resolution changes. It pairs with <code>Screen.height</code> for full-screen calculations such as clamping a moving object inside the visible area. It takes no arguments and can be read during any handler.
+
+```ludic
+program CenteredLabel {
+  handler DrawWorld phase Render {
+    Screen.clear(Color.MidnightBlue)
+    let label_width = 10 * 6
+    let centered_x = (Screen.width() - label_width) / 2
+    Screen.draw_text(x: centered_x, y: 40, text: "CHRONORIFT", color: Color.Gold, scale: 1)
+    Screen.show()
+  }
+}
+```