feat: extending modules

.crush.json

···
+{
+  "options": {
+    "skills_paths": [
+      "~/.config/crush/skills",
+      "./.skills"
+    ]
+  }
+}

.skills/writing-modules/SKILL.md

···
+---
+name: writing-modules
+description: Guide for creating modules for scrn. This skill should be used when users want to create a new module (or update an existing module) that extends scrn's capabilities.
+---
+# Writing Modules for scrn
+
+A comprehensive guide for designing and implementing JSX modules for the scrn e-ink display system.
+
+## Overview
+
+Modules are JSX components that render layouts to 800x480 1-bit BMP images for e-ink displays. They can fetch data, use caching, and compose other modules to create rich display interfaces.
+
+## Module Structure
+
+### Basic Template
+
+Every module follows this pattern:
+
+```jsx
+export default function ModuleName({width, height, propName}) {
+  // 1. Fetch or compute data
+  // 2. Build JSX tree
+  // 3. Return layout
+  
+  return <flex direction="vertical">
+    {/* Your layout here */}
+  </flex>
+}
+```
+
+### Key Principles
+
+1. **Export default function** - The entry point must be a default export
+2. **Receive props** - Always destructure `{width, height, ...customProps}`
+3. **Synchronous execution** - All code runs synchronously, including fetch()
+4. **Pure JSX return** - Return a single JSX tree (usually `<flex>` as root)
+
+## Available Props
+
+Every module receives these standard props:
+
+- `width` - Allocated width in pixels
+- `height` - Allocated height in pixels
+- Any custom props passed from parent components
+
+```jsx
+// In display.jsx
+<Weather weight={60} padding={20} location="Vienna, Austria" />
+
+// In weather.jsx - receives location plus standard width/height
+export default function Weather({width, height, location}) {
+  // ...
+}
+```
+
+## Built-in Node Types
+
+### `<flex>` - Layout Container
+
+The primary layout primitive. Arranges children horizontally or vertically.
+
+```jsx
+<flex 
+  direction="horizontal|vertical"  // Layout direction (default: horizontal)
+  separator="none|solid|dashed"    // Visual separator between children
+  justify="start|end|center"       // Alignment along main axis
+  gap={10}                         // Spacing between children in pixels
+  weight={1}                       // Flex grow factor (relative sizing)
+  size={200}                       // Fixed size in pixels (overrides weight)
+  margin={10}                      // Outer spacing
+  padding={20}                     // Inner spacing
+  cornerRadius={6}                 // Rounded corners
+>
+  {children}
+</flex>
+```
+
+**Examples:**
+
+```jsx
+// Horizontal split (60/40)
+<flex direction="horizontal">
+  <Weather weight={60} />
+  <Tracker weight={40} />
+</flex>
+```
+
+```jsx
+// Vertical stack with fixed header
+<flex direction="vertical">
+  <flex size={100}>Header</flex>
+  <flex weight={1}>Content</flex>
+</flex>
+```
+
+```jsx
+// Center content with gap
+<flex gap={20} justify="center" direction="vertical">
+  <text>Line 1</text>
+  <text>Line 2</text>
+</flex>
+```
+
+### `<text>` - Text Display
+
+Renders text content with font size control.
+
+```jsx
+<text 
+  fontSize={32}     // Font size in pixels (default: 32, inherited)
+  weight={1}        // Flex sizing
+  size={100}        // Fixed height
+>
+  Your text here
+</text>
+```
+
+**Examples:**
+
+```jsx
+// Large temperature display
+<text fontSize={60}>23°C</text>
+```
+
+```jsx
+// Small label
+<text fontSize={22}>Days Left</text>
+```
+
+```jsx
+// Dynamic content
+<text fontSize={120}>{week}</text>
+```
+
+### `<fill>` - Solid Color Block
+
+Renders a solid color rectangle.
+
+```jsx
+<fill 
+  color="white|black|gray"  // Color (gray = checkerboard pattern)
+  weight={1}                // Flex sizing
+  size={10}                 // Fixed size
+/>
+```
+
+**Examples:**
+
+```jsx
+// Progress bar (black filled, gray remainder)
+<flex direction="horizontal">
+  <fill weight={70} color="black" />
+  <fill weight={30} color="gray" />
+</flex>
+```
+
+```jsx
+// Separator line
+<fill size={2} color="black" />
+```
+
+```jsx
+// Spacer
+<fill color="white" />
+```
+
+### `<img>` - Image Display
+
+Renders embedded images from the icons directory.
+
+```jsx
+<img 
+  src="scrn/icons/path/to/image.png"  // Path relative to scrn/icons/
+  size={256}                          // Fixed size (width=height)
+/>
+```
+
+**Examples:**
+
+```jsx
+// Weather icon
+<img size={256} src="scrn/icons/weather/day/clear.png" />
+
+// Must be in internal/module/scrn/icons/ directory
+```
+
+## Data Fetching
+
+### fetch() API
+
+Synchronous HTTP GET using the standard fetch interface:
+
+```jsx
+const url = new URL("/v1/search", "https://api.example.com/")
+url.searchParams.set("name", location)
+url.searchParams.set("count", "10")
+
+const response = fetch(url.toString())
+
+if (response.status === 200) {
+  const data = response.json()  // Parse JSON response
+  // Use data...
+}
+```
+
+**Key differences from browser fetch:**
+- **Synchronous** - Blocks until response received (no Promises)
+- **GET only** - Only HTTP GET requests supported
+- `response.json()` returns parsed object directly
+- `response.status` for status code checking
+
+### URL Construction
+
+Use the `URL` class for clean query string building:
+
+```jsx
+const url = new URL("/v1/forecast", "https://api.open-meteo.com/")
+url.searchParams.set("latitude", coords.latitude)
+url.searchParams.set("longitude", coords.longitude)
+url.searchParams.set("current", "temperature_2m")
+
+fetch(url.toString())  // Converts to full URL string
+```
+
+## Caching
+
+### cache API
+
+Simple key-value in-memory cache (resets on server restart):
+
+```jsx
+// Check cache first
+const cached = cache.get("weather.coordinates")
+if (cached) {
+  return cached
+}
+
+// Fetch fresh data
+const data = fetchFromAPI()
+
+// Store in cache
+cache.set("weather.coordinates", data)
+```
+
+**Best practices:**
+- Use namespaced keys: `"weather.coordinates"`, `"tracker.data"`
+- Cache API responses to reduce network calls
+- Store processed/transformed data for reuse
+- Cache is shared across renders but not persistent
+
+## Responsive Layout
+
+Modules receive `width` and `height` - use them for responsive behavior:
+
+```jsx
+export function PregnancyTracker({width, due}) {
+  // Default layout for wide displays
+  let inner = <flex direction="horizontal">
+    <Meta>
+      <text fontSize={30}>Week</text>
+      <text fontSize={120}>{week}</text>
+    </Meta>
+    <Meta>
+      <text fontSize={30}>Days Left</text>
+      <text fontSize={120}>{left}</text>
+    </Meta>
+  </flex>
+
+  // Compact layout for narrow displays
+  if (width < 500) {
+    inner = <flex direction="vertical" gap={20}>
+      <Meta size={140}>
+        <text fontSize={30}>Week</text>
+        <text fontSize={120}>{week}</text>
+      </Meta>
+      <Meta size={100}>
+        <text fontSize={26}>Days Left</text>
+        <text fontSize={60}>{left}</text>
+      </Meta>
+    </flex>
+  }
+
+  return <flex direction="vertical">
+    {inner}
+    <ProgressBar percentage={percentage} />
+  </flex>
+}
+```
+
+## Importing and Composing
+
+### Import Built-in Modules
+
+```jsx
+// Default import
+import Weather from "scrn/weather"
+
+// Named exports
+import { ProgressBar, Meta } from "scrn/utils"
+import { PregnancyTracker } from "scrn/tracker"
+```
+
+### Using Imported Components
+
+Pass props like any JSX component:
+
+```jsx
+<ProgressBar percentage={0.75} size={60} cornerRadius={6} />
+
+<Meta>
+  <text fontSize={30}>Label</text>
+  <text fontSize={120}>Value</text>
+</Meta>
+```
+
+### Creating Reusable Components
+
+Export utilities for other modules to use:
+
+```jsx
+// In scrn/utils.jsx
+export function ProgressBar({percentage}) {
+  const filled = parseInt(percentage * 100, 10)
+  const empty = 100 - filled
+  
+  return <flex direction="horizontal">
+    <fill weight={filled} color="black" />
+    <fill weight={empty} color="gray" />
+  </flex>
+}
+
+export function Meta({children}) {
+  return <flex direction="horizontal">
+    <fill size={10} color="gray" />
+    <flex padding={10} justify="center" direction="vertical">
+      {children}
+    </flex>
+  </flex>
+}
+```
+
+## Common Patterns
+
+### Data Fetching with Cache
+
+```jsx
+function getData(key, apiUrl) {
+  const cached = cache.get(key)
+  if (cached) {
+    return cached
+  }
+
+  const response = fetch(apiUrl)
+  if (response.status === 200) {
+    const data = response.json()
+    cache.set(key, data)
+    return data
+  }
+
+  return null
+}
+
+export default function MyModule({location}) {
+  const data = getData("mymodule.data", "https://api.example.com/data")
+  
+  if (!data) {
+    return <text>Data not available</text>
+  }
+
+  return <flex>
+    {/* Render data */}
+  </flex>
+}
+```
+
+### Error States
+
+Handle missing data gracefully:
+
+```jsx
+export default function Weather({location}) {
+  const coords = getCoordinates(location)
+
+  let inner = <text>Coordinates not found!</text>
+  
+  if (coords) {
+    const weather = getWeather(coords)
+    
+    if (weather) {
+      inner = <text fontSize={60}>{weather.temp}°C</text>
+    } else {
+      inner = <text>Weather data not found!</text>
+    }
+  }
+
+  return <flex>{inner}</flex>
+}
+```
+
+### Calculations and Formatting
+
+```jsx
+function toDays(millis) {
+  return parseInt(millis / 1000 / 60 / 60 / 24, 10)
+}
+
+export default function Tracker({start, end}) {
+  const s = Date.parse(start)
+  const e = Date.parse(end)
+  const n = Date.now()
+
+  const left = toDays(e - n)
+  const passed = toDays(n - s)
+  const percentage = (n - s) / (e - s)
+
+  return <flex>
+    <text>{left} days left</text>
+    <ProgressBar percentage={percentage} />
+  </flex>
+}
+```
+
+### Layout Composition
+
+```jsx
+export default function Dashboard() {
+  return <flex direction="horizontal" separator="dashed">
+    {/* Left side: 60% width */}
+    <flex weight={60} padding={20} direction="vertical">
+      <flex size={256}>
+        <img size={256} src="scrn/icons/weather/day/clear.png" />
+      </flex>
+      <flex>
+        <text fontSize={60}>23°C</text>
+      </flex>
+    </flex>
+    
+    {/* Right side: 40% width */}
+    <flex weight={40} padding={20} direction="vertical">
+      <ProgressBar percentage={0.65} />
+    </flex>
+  </flex>
+}
+```
+
+## Module Development Workflow
+
+### 1. Create the JSX file
+
+Add to `internal/module/scrn/yourmodule.jsx`:
+
+```jsx
+export default function YourModule({width, height, customProp}) {
+  return <flex direction="vertical">
+    <text>Hello from {customProp}</text>
+  </flex>
+}
+```
+
+### 2. Compile the module
+
+```bash
+cd internal/module
+go generate ./...
+```
+
+This transforms JSX to JS and embeds it in the Go binary.
+
+### 3. Use in display.jsx
+
+```jsx
+import YourModule from "scrn/yourmodule"
+
+export default function Display() {
+  return <YourModule customProp="test" />
+}
+```
+
+### 4. Run and test
+
+```bash
+go run .
+```
+
+Visit `http://localhost:8081/api/image.bmp` to see the rendered output.
+
+## Design Guidelines
+
+### Visual Hierarchy
+
+- Use font sizes to establish hierarchy: 120px (primary), 60px (secondary), 30px (labels), 22px (small text)
+- Use `weight` for proportional sizing, `size` for fixed measurements
+- Add `padding` for breathing room, `margin` for separation
+- Use `separator="dashed"` for visual division
+
+### E-ink Optimization
+
+- **Black and white only** - Gray uses a checkerboard pattern (dithering)
+- **High contrast** - Ensure text is readable with large font sizes
+- **Simple layouts** - Avoid fine details, they won't render well
+- **Large touch targets** - Though this is display-only, consider future interaction
+
+### Performance
+
+- **Cache API calls** - Reduces render time and network load
+- **Minimize fetch calls** - Batch data or reuse cached responses
+- **Simple calculations** - Complex logic slows rendering
+
+### Error Handling
+
+- **Always handle null/missing data** - APIs can fail
+- **Provide fallback UI** - Show error messages, don't crash
+- **Test with offline data** - Use cache.get() as fallback
+
+## Examples from Built-in Modules
+
+### Simple Utility (ProgressBar)
+
+```jsx
+export function ProgressBar({percentage}) {
+  const p = parseInt(percentage * 100, 10)
+  const r = 100 - p
+
+  return <flex direction="horizontal">
+    <fill weight={p} color="black" />
+    <fill weight={r} color="gray" />
+  </flex>
+}
+```
+
+**Lessons:**
+- Single responsibility: just draws a progress bar
+- No data fetching, pure presentation
+- Exported as named export for composition
+
+### API Integration (Weather)
+
+```jsx
+function getCoordinates(location) {
+  const coords = cache.get("weather.coordinates")
+  if (coords) return coords
+
+  const url = new URL("/v1/search", "https://geocoding-api.open-meteo.com/")
+  url.searchParams.set("name", location)
+
+  const ret = fetch(url.toString())
+  if (ret.status === 200) {
+    const data = ret.json()
+    const coords = {
+      latitude: data.results[0].latitude,
+      longitude: data.results[0].longitude,
+    }
+    cache.set("weather.coordinates", coords)
+    return coords
+  }
+
+  return null
+}
+
+export default function Weather({width, height, location}) {
+  const coords = getCoordinates(location)
+  
+  let inner = <text>Coordinates not found!</text>
+  
+  if (coords) {
+    const weather = getWeather(coords)
+    if (weather) {
+      const temp = Math.round(weather.current.temperature_2m)
+      inner = <text fontSize={60}>{temp}°C</text>
+    }
+  }
+
+  return <flex direction="vertical">
+    <flex direction="horizontal">
+      <img size={256} src="scrn/icons/weather/day/clear.png" />
+      {inner}
+    </flex>
+  </flex>
+}
+```
+
+**Lessons:**
+- Helper functions for data fetching
+- Cache layer for coordinates (static data)
+- Error handling with fallback UI
+- Nested flex layouts for positioning
+
+### Responsive Component (PregnancyTracker)
+
+```jsx
+export function PregnancyTracker({width, due}) {
+  const delta = calculateDelta(due)
+  const week = formatWeek(delta)
+  const left = calculateDaysLeft(due)
+
+  // Default: horizontal layout
+  let inner = <flex direction="horizontal">
+    <Meta>
+      <text fontSize={30}>Week</text>
+      <text fontSize={120}>{week}</text>
+    </Meta>
+    <Meta>
+      <text fontSize={30}>Days Left</text>
+      <text fontSize={120}>{left}</text>
+    </Meta>
+  </flex>
+
+  // Narrow: vertical layout with smaller fonts
+  if (width < 500) {
+    inner = <flex direction="vertical" gap={20}>
+      <Meta>
+        <text fontSize={30}>Week</text>
+        <text fontSize={120}>{week}</text>
+      </Meta>
+      <Meta>
+        <text fontSize={26}>Days Left</text>
+        <text fontSize={60}>{left}</text>
+      </Meta>
+    </flex>
+  }
+
+  return <flex direction="vertical">
+    {inner}
+    <ProgressBar percentage={percentage} />
+  </flex>
+}
+```
+
+**Lessons:**
+- Width-based responsive behavior
+- Conditional layout (horizontal vs vertical)
+- Reusable components (Meta, ProgressBar)
+- Font size scaling for different layouts
+
+## Tips and Gotchas
+
+### ✅ Do
+
+- **Cache API responses** for better performance
+- **Handle errors gracefully** with fallback UI
+- **Use URL class** for clean query string building
+- **Test responsive behavior** at different widths
+- **Export reusable utilities** for other modules
+- **Use `weight` for flexible sizing**, `size` for fixed measurements
+- **Round numbers** before display: `Math.round(value)`
+- **Check response status** before parsing: `if (ret.status === 200)`
+
+### ❌ Don't
+
+- **Use async/await** - fetch() is synchronous
+- **Return Promises** - everything is sync
+- **Mutate props** - treat them as read-only
+- **Assume APIs work** - always handle errors
+- **Use tiny fonts** - e-ink needs high contrast
+- **Forget to recompile** - run `go generate` after JSX changes
+- **Use complex images** - 1-bit color only
+- **Skip caching** - avoid redundant network calls
+
+## Troubleshooting
+
+### Module not found
+
+```
+Error: module "scrn/mymodule" not found
+```
+
+**Fix:** Run `go generate ./...` in `internal/module/` to compile JSX files.
+
+### White screen / nothing renders
+
+**Check:**
+- Does your module return JSX? (not null, not undefined)
+- Are prop names spelled correctly?
+- Check server logs for JavaScript errors
+
+### fetch() fails silently
+
+**Fix:** Always check `response.status` before using data:
+
+```jsx
+const ret = fetch(url)
+if (ret.status !== 200) {
+  console.log("Failed to fetch:", ret.status)
+  return null
+}
+```
+
+### Layout looks wrong
+
+**Check:**
+- Are you using `weight` vs `size` correctly?
+- Is `direction` set on parent `<flex>`?
+- Did you forget `padding`/`margin`?
+- Use `justify="center"` for centering
+
+### Image not found
+
+**Ensure:**
+- Image is in `internal/module/scrn/icons/` directory
+- Path starts with `scrn/icons/` (not `/scrn/icons/`)
+- Server was recompiled after adding image
+
+## Advanced Patterns
+
+### Multi-level Caching
+
+```jsx
+function getDataWithFallback(key, apiUrl) {
+  // Try cache first
+  const cached = cache.get(key)
+  if (cached && cached.timestamp > Date.now() - 3600000) {
+    return cached.data
+  }
+
+  // Try API
+  const response = fetch(apiUrl)
+  if (response.status === 200) {
+    const data = response.json()
+    cache.set(key, {
+      data: data,
+      timestamp: Date.now()
+    })
+    return data
+  }
+
+  // Fallback to stale cache
+  if (cached) {
+    return cached.data
+  }
+
+  return null
+}
+```
+
+### Conditional Component Trees
+
+```jsx
+export default function Display({mode}) {
+  const components = {
+    weather: <Weather location="Vienna" />,
+    tracker: <PregnancyTracker due="2026-07-05" />,
+    both: <flex direction="horizontal">
+      <Weather weight={60} />
+      <PregnancyTracker weight={40} />
+    </flex>
+  }
+
+  return components[mode] || components.both
+}
+```
+
+### Dynamic Layouts
+
+```jsx
+function calculateLayout(items, width) {
+  const itemsPerRow = width > 600 ? 3 : 2
+  const rows = []
+  
+  for (let i = 0; i < items.length; i += itemsPerRow) {
+    rows.push(items.slice(i, i + itemsPerRow))
+  }
+  
+  return rows
+}
+
+export default function Grid({items, width}) {
+  const rows = calculateLayout(items, width)
+  
+  return <flex direction="vertical">
+    {rows.map(row => (
+      <flex direction="horizontal">
+        {row.map(item => (
+          <flex weight={1}>
+            <text>{item}</text>
+          </flex>
+        ))}
+      </flex>
+    ))}
+  </flex>
+}
+```
+
+## Summary
+
+Writing modules for scrn involves:
+
+1. **Create JSX component** with `export default function`
+2. **Receive props** including `width`, `height`, and custom props
+3. **Fetch data** using synchronous `fetch()` and `cache` APIs
+4. **Build layout** using `<flex>`, `<text>`, `<fill>`, `<img>`
+5. **Handle errors** with fallback UI
+6. **Return JSX tree** from component function
+7. **Compile with** `go generate ./...`
+8. **Import and use** in display.jsx
+
+The flexibility of JSX combined with Go's runtime creates a powerful system for building dynamic, data-driven e-ink displays.

AGENTS.md

···
+# AGENTS.md - Working with the scrn codebase
+
+This is a **Go-based server that renders JSX components to BMP images** for e-ink displays (TRMNL devices). It executes JSX components in a JavaScript runtime (goja), calculates layouts using a custom flexbox-like system, and renders to 1-bit BMP images.
+
+## Project Overview
+
+- **Language**: Go 1.23.3
+- **Module**: `tangled.org/cdbrdr.com/scrn`
+- **Purpose**: TRMNL-compatible display server that renders JSX layouts to BMP images
+- **Display**: 800x480, 1-bit color (black/white), outputs BMP format
+
+## Essential Commands
+
+```bash
+# Build the binary
+go build -o scrn
+
+# Run the server (uses examples/display.jsx by default)
+go run .
+
+# Run tests
+go test ./...
+go test ./internal/tree/...  # specific package
+
+# Regenerate pre-compiled JS modules (run after modifying JSX files)
+cd internal/module
+go generate ./...
+
+# Download dependencies
+go mod download
+go mod tidy
+```
+
+## Project Structure
+
+```
+.
+├── main.go                    # Entry point: loads display.jsx, starts HTTP server on :8081
+├── internal/
+│   ├── display/
+│   │   ├── display.go         # Display struct: manages goja runtime, renders BMP
+│   │   └── draw.go            # Rendering: draws nodes to image (uses gofont, masks)
+│   ├── handler/
+│   │   └── api.go             # HTTP handlers: /api/setup, /api/display, /api/image.bmp
+│   ├── tree/
+│   │   ├── tree.go            # Node interface, CalculateLayout, style parsing
+│   │   ├── node.go            # parseNode: converts JSX output to internal nodes
+│   │   ├── module.go          # Module nodes: calls JSX functions recursively
+│   │   ├── flex.go            # FlexNode: flexbox layout (horizontal/vertical)
+│   │   ├── text.go            # TextNode: text rendering with font size inheritance
+│   │   ├── fill.go            # FillNode: solid color fills (black/white/gray)
+│   │   ├── img.go             # ImgNode: embedded image rendering
+│   │   └── tree_test.go       # Tests using deep.Equal for struct comparison
+│   ├── module/
+│   │   ├── module.go          # go:embed for JSX files, module loader
+│   │   ├── jsx/
+│   │   │   └── jsx-runtime.js # JSX transform runtime (h/jsx/jsxs functions)
+│   │   ├── scrn/
+│   │   │   ├── *.jsx          # Built-in modules (weather, tracker, utils)
+│   │   │   └── icons/         # PNG/JPG assets for weather icons
+│   │   ├── fetch/
+│   │   │   └── fetch.go       # fetch() polyfill for goja (HTTP GET)
+│   │   └── cache/
+│   │       └── cache.go       # Simple in-memory cache for goja
+│   └── transform/
+│       └── transform.go       # esbuild wrapper: transforms JSX -> JS (IIFE/CJS)
+└── examples/
+    └── display.jsx            # Example main component
+```
+
+## Architecture Flow
+
+1. **main.go** loads `examples/display.jsx` and creates a `Display`
+2. **transform** converts JSX to JS using esbuild with automatic JSX runtime
+3. **display** creates a goja runtime, registers modules (fetch, cache, console, url)
+4. **JSX components** execute and return a tree structure (via jsx-runtime.js)
+5. **tree.CalculateLayout** parses the tree into typed nodes (FlexNode, TextNode, etc.)
+6. **Layout engine** calculates bounds using flexbox algorithm with weights/sizes
+7. **draw.go** renders nodes to `image.Paletted` (black/white palette)
+8. **Output** is BMP with TRMNL-specific header patches
+
+## JSX/Component System
+
+### Built-in Node Types (from jsx-runtime.js)
+
+```jsx
+// Flex container - arranges children horizontally or vertically
+<flex direction="horizontal|vertical" separator="none|solid|dashed" justify="start|end|center" gap={10}>
+
+// Text node - content from children, supports fontSize
+<text fontSize={32}>Hello World</text>
+
+// Fill - solid color block
+<fill color="white|black|gray" />
+
+// Image - from embedded assets
+<img src="scrn/icons/weather/day/clear.png" />
+```
+
+### Style Properties (all nodes)
+
+- `weight` - Flex grow factor (default: 1)
+- `size` - Fixed pixel size (overrides weight)
+- `margin` - Outer margin in pixels
+- `padding` - Inner padding in pixels
+- `cornerRadius` - For rounded corners (via mask)
+- `fontSize` - Inherited font size for text (default: 32)
+
+### Writing Modules
+
+Modules are JSX files in `internal/module/scrn/`:
+
+```jsx
+// Import other modules
+import { ProgressBar } from "scrn/utils"
+
+// Export default function - receives props including width/height
+export default function Weather({width, height, location}) {
+  // Use fetch() to get data
+  const response = fetch(`https://api.example.com/data`)
+
+  // Use cache for persistence between renders
+  cache.set("key", value)
+  const cached = cache.get("key")
+
+  // Return JSX tree
+  return <flex direction="vertical">
+    <text fontSize={60}>{temp}°C</text>
+  </flex>
+}
+```
+
+### Key Rules
+
+- Components **must** export default a function
+- The function receives `width`, `height`, and any props from parent
+- `fetch()` is synchronous (blocking) in this runtime
+- `cache` is in-memory only (resets on server restart)
+- Images must be in `scrn/icons/` path (embedded at build time)
+
+## Code Patterns
+
+### Adding a New Node Type
+
+1. Define `NodeType` constant in `tree/tree.go`
+2. Create struct in `tree/newtype.go` with:
+   - Type-specific fields
+   - `Type() NodeType` method
+   - `Bounds() image.Rectangle` method  
+   - `GetStyle() NodeStyle` method
+3. Add case to `node.go`'s `GetNode()` switch
+4. Add renderer in `draw.go`'s `drawNode()` switch
+
+### Adding a Built-in Module
+
+1. Create `.jsx` file in `internal/module/scrn/`
+2. Run `go generate ./...` in `internal/module` to compile
+3. Import in display files as `import X from "scrn/filename"`
+
+### Error Handling
+
+- Go errors are defined as vars: `ErrNoDefaultExport = errors.New("...")`
+- Goja (JS) errors use `runtime.NewGoError(err)`
+- HTTP handlers log errors and return 500 status
+
+## Testing
+
+Tests use `github.com/go-test/deep` for struct comparison:
+
+```go
+func TestSomething(t *testing.T) {
+    result, err := CalculateLayout(input, rect, nil)
+    expected := &FlexNode{...}
+
+    if diff := deep.Equal(result, expected); diff != nil {
+        t.Error(diff)
+    }
+}
+```
+
+Run with: `go test ./internal/tree/...`
+
+## Important Gotchas
+
+1. **JSX Compilation**: JSX files are transformed at build time via `go generate`. The generated `.js` files are embedded and ignored in `.gitignore`.
+
+2. **Synchronous fetch**: The `fetch()` implementation is blocking/synchronous, not Promise-based like browser fetch.
+
+3. **BMP Header Patching**: The BMP output has hardcoded header patches for TRMNL compatibility (bytes 46, 57, 61).
+
+4. **Font Size Inheritance**: `fontSize` is inherited from parent nodes. The default is 32px.
+
+5. **Flex Layout Algorithm**: 
+   - If `size` is set, it's used as fixed pixels
+   - Otherwise `weight` determines proportional sizing of remaining space
+   - Weights are normalized across siblings
+
+6. **Module Resolution**: Modules are loaded from `node_modules/scrn/*` path in the goja runtime, mapped to embedded files.
+
+7. **Goja Runtime**: Each Display has its own isolated JS runtime. Modules share the same runtime within a Display.
+
+8. **Image Assets**: Only images in `internal/module/scrn/icons/` are available. They're embedded at build time via `//go:embed`.
+
+9. **Color Palette**: Only black, white, and gray. Gray is rendered as a checkerboard pattern.
+
+## Dependencies to Know
+
+- **goja**: JavaScript runtime for Go (ECMAScript 5.1+)
+- **esbuild**: Bundles/transforms JSX (used as Go library)
+- **gin**: HTTP web framework
+- **gofont**: Font rendering for Go images
+- **mapstructure**: Decodes map[string]any into structs (for JSX props)
+
+## API Endpoints (TRMNL-compatible)
+
+- `GET /api/setup` - Returns device registration info
+- `GET /api/display` - Returns display metadata with image URL
+- `GET /api/image.bmp` - Returns rendered BMP image
+- `POST /api/log` - Receives device logs
+
+The server mimics TRMNL's cloud API for local e-ink display testing.

examples/display.jsx

···
 import Weather from "scrn/weather"
-import {PregnancyTracker} from "scrn/tracker"
+import GitHub from "scrn/github"
+import {PregnancyTracker, AgeTracker} from "scrn/tracker"
 
 export default function Display() {
   return <flex direction="horizontal" separator="dashed">
-    <Weather weight={55} padding={20} location="Vienna, Austria" />
-    <PregnancyTracker weight={45} padding={20} due="2025-07-05" />
+    <Weather weight={60} padding={20} location="Vienna, Austria" />
+    <AgeTracker weight={40} padding={20} name="Joe" birthday="2025-10-08" />
   </flex>
 }

go.mod

···
 	github.com/go-viper/mapstructure/v2 v2.2.1
 	github.com/gonutz/gofont v1.0.0
 	github.com/sergeymakinen/go-bmp v1.0.0
+	go.oneofone.dev/resize v1.0.1
 )
 
 require (
···
 	github.com/ugorji/go/codec v1.2.12 // indirect
 	golang.org/x/arch v0.8.0 // indirect
 	golang.org/x/crypto v0.25.0 // indirect
+	golang.org/x/image v0.1.0 // indirect
 	golang.org/x/net v0.27.0 // indirect
 	golang.org/x/sys v0.22.0 // indirect
 	golang.org/x/text v0.21.0 // indirect

go.sum

···
 github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
 github.com/ugorji/go/codec v1.2.12 h1:9LC83zGrHhuUA9l16C9AHXAqEV/2wBQ4nkvumAE65EE=
 github.com/ugorji/go/codec v1.2.12/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg=
+github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
+go.oneofone.dev/resize v1.0.1 h1:HjpVar/4pxMGrjO44ThaMX1Q5UOBw0KxzbxxRDZPQuA=
+go.oneofone.dev/resize v1.0.1/go.mod h1:zGFmn7q4EUZVlnDmxqf+b0mWpxsTt0MH2yx6ng8tpq0=
 golang.org/x/arch v0.0.0-20210923205945-b76863e36670/go.mod h1:5om86z9Hs0C8fWVUuoMHwpExlXzs5Tkyp9hOrfG7pp8=
 golang.org/x/arch v0.8.0 h1:3wRIsP3pM4yUptoR96otTUOXI367OS0+c9eeRi9doIc=
 golang.org/x/arch v0.8.0/go.mod h1:FEVrYAQjsQXMVJ1nsMoVVXPZg6p2JE2mx8psSWTDQys=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
 golang.org/x/crypto v0.25.0 h1:ypSNr+bnYL2YhwoMt2zPxHFmbAN1KZs/njMG3hxUp30=
 golang.org/x/crypto v0.25.0/go.mod h1:T+wALwcMOSE0kXgUAnPAHqTLW+XHgcELELW8VaDgm/M=
+golang.org/x/image v0.1.0 h1:r8Oj8ZA2Xy12/b5KZYj3tuv7NG/fBz3TwQVvpJ9l8Rk=
+golang.org/x/image v0.1.0/go.mod h1:iyPr49SD/G/TBxYVB/9RRtGUT5eNbo2u4NamWeQcD5c=
+golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
+golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
 golang.org/x/net v0.27.0 h1:5K3Njcw06/l2y9vpGCSdcxWOYHOUk3dVNGDXN+FvAys=
 golang.org/x/net v0.27.0/go.mod h1:dDi0PyhWNoiUOrAS8uXv/vnScO4wnHQO4mj9fn/RytE=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.22.0 h1:RI27ohtqKCnwULzJLqkv897zojh5/DwS/ENaMzUOaWI=
 golang.org/x/sys v0.22.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
+golang.org/x/text v0.4.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
 golang.org/x/text v0.21.0 h1:zyQAAkrwaneQ066sspRyJaG9VNi/YJ1NfzcGB3hZ/qo=
 golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 google.golang.org/protobuf v1.34.1 h1:9ddQBjfCyZPOHPUiPxpYESBLc+T8P3E+Vo4IbKZgFWg=

internal/display/draw.go

···
 	"strings"
 
 	"github.com/gonutz/gofont"
+	"go.oneofone.dev/resize"
 	"tangled.org/cdbrdr.com/scrn/internal/display/util"
 	"tangled.org/cdbrdr.com/scrn/internal/module"
 	"tangled.org/cdbrdr.com/scrn/internal/tree"
···
 		return ErrImgSrcNotFound
 	}
 
+	width := n.Rect.Dx()
+	height := n.Rect.Dy()
+	if width > height {
+		src = resize.Resize(uint(width), 0, src, resize.MitchellNetravali)
+	} else if height > width {
+		src = resize.Resize(0, uint(height), src, resize.MitchellNetravali)
+	} else {
+		src = resize.Resize(uint(width), uint(height), src, resize.MitchellNetravali)
+	}
+
 	srect := src.Bounds()
 	sp := image.Pt(
-		n.Rect.Min.X+(n.Rect.Dx()/2)-(srect.Dx()/2),
-		n.Rect.Min.Y+(n.Rect.Dy()/2)-(srect.Dy()/2),
+		n.Rect.Min.X+(width/2)-(srect.Dx()/2),
+		n.Rect.Min.Y+(height/2)-(srect.Dy()/2),
 	)
 	sr := image.Rect(
 		sp.X,

internal/module/scrn/github.jsx

···
+function getGitHubUser(username) {
+  const cacheKey = "github.user." + username
+  const cached = cache.get(cacheKey)
+
+  if (cached) {
+    return cached
+  }
+
+  const url = "https://api.github.com/users/" + username
+  const response = fetch(url)
+
+  if (response.status === 200) {
+    const data = response.json()
+    cache.set(cacheKey, data)
+    return data
+  }
+
+  if (response.status === 404) {
+    return { error: "User not found" }
+  }
+
+  if (response.status === 403) {
+    return { error: "API rate limit exceeded" }
+  }
+
+  return { error: "Failed to fetch user data" }
+}
+
+function formatNumber(num) {
+  if (num >= 1000000) {
+    return (num / 1000000).toFixed(1) + "M"
+  }
+  if (num >= 1000) {
+    return (num / 1000).toFixed(1) + "k"
+  }
+  return num.toString()
+}
+
+function StatBox({label, value, compact}) {
+  if (compact) {
+    return <flex direction="vertical" justify="space-between">
+      <text fontSize={18}>{label}</text>
+      <text fontSize={24}>{value}</text>
+    </flex>
+  }
+  return <flex direction="vertical" justify="center">
+    <text fontSize={22}>{label}</text>
+    <text fontSize={48}>{value}</text>
+  </flex>
+}
+
+export default function GitHub({width, height, username}) {
+  if (!username) {
+    return <flex direction="vertical" justify="center">
+      <text fontSize={32}>No username provided</text>
+    </flex>
+  }
+
+  const user = getGitHubUser(username)
+
+  if (user.error) {
+    return <flex direction="vertical" justify="center">
+      <text fontSize={32}>GitHub Error</text>
+      <text fontSize={22}>{user.error}</text>
+    </flex>
+  }
+
+  const displayName = user.name || user.login
+  const repos = formatNumber(user.public_repos || 0)
+  const followers = formatNumber(user.followers || 0)
+  const following = formatNumber(user.following || 0)
+
+  // Check if narrow layout (50% or less of 800px screen)
+  const isNarrow = width <= 400
+
+  if (isNarrow) {
+    return <flex direction="vertical" padding={16} gap={12}>
+      <fill size={20} color="white" />
+
+      <flex size={50} direction="vertical" justify="center">
+        <text fontSize={28}>{displayName}</text>
+        <text fontSize={16}>@{user.login}</text>
+      </flex>
+
+      <fill size={1} color="gray" />
+
+      <flex weight={1} direction="vertical" gap={30}>
+        <StatBox label="Repositories" value={repos} compact={true} />
+        <StatBox label="Followers" value={followers} compact={true} />
+        <StatBox label="Following" value={following} compact={true} />
+      </flex>
+
+      <fill size={20} color="white" />
+    </flex>
+  }
+
+  return <flex direction="vertical" padding={20} gap={20}>
+    <fill size={20} color="white" />
+
+    <flex size={80} direction="vertical" justify="center">
+      <text fontSize={48}>{displayName}</text>
+      <text fontSize={22}>@{user.login}</text>
+    </flex>
+
+    <fill size={2} color="gray" />
+
+    <flex weight={1} direction="horizontal" gap={20} justify="center">
+      <StatBox label="Repositories" value={repos} />
+      <StatBox label="Followers" value={followers} />
+      <StatBox label="Following" value={following} />
+    </flex>
+
+    <fill size={60} color="white" />
+  </flex>
+}

internal/module/scrn/tracker.jsx

···
   </flex>
 }
 
+export function AgeTracker({width, name, birthday}) {
+  const birth = new Date(birthday)
+  const now = new Date()
+
+  let years = now.getFullYear() - birth.getFullYear()
+  let months = now.getMonth() - birth.getMonth()
+  let days = now.getDate() - birth.getDate()
+
+  if (days < 0) {
+    months--
+    const prevMonth = new Date(now.getFullYear(), now.getMonth(), 0)
+    days += prevMonth.getDate()
+  }
+
+  if (months < 0) {
+    years--
+    months += 12
+  }
+
+
+  if (width < 500) {
+    return <flex direction="vertical">
+      <fill size={20} />
+
+      {name && (
+        <flex direction="vertical">
+          <text fontSize={40}>{name}'s age</text>
+          <fill size={1} color="gray" />
+        </flex>
+      )}
+
+      <flex weight={5}
+                  gap={20}
+                  justify="center"
+                  direction="vertical" >
+        <Meta size={140}>
+          <text size={100} fontSize={120}>{years}</text>
+          <text size={22} fontSize={22}>Years</text>
+        </Meta>
+        <flex size={100} direction="horizontal" gap={20}>
+          <Meta weight={1}>
+            <text size={60} fontSize={60}>{months}</text>
+            <text size={22} fontSize={22}>Months</text>
+          </Meta>
+          <Meta weight={1}>
+            <text size={60} fontSize={60}>{days}</text>
+            <text size={22} fontSize={22}>Days</text>
+          </Meta>
+        </flex>
+      </flex>
+
+      <fill size={20} />
+    </flex>
+  }
+
+  return <flex direction="vertical">
+    {name && (
+      <flex direction="vertical">
+        <text fontSize={50}>{name}'s age</text>
+        <fill size={1} color="gray" />
+      </flex>
+    )}
+
+    <flex weight={3} direction="vertical">
+      <fill color="white" />
+      <flex size={160} direction="horizontal">
+        <Meta>
+          <text size={110} fontSize={120}>{years}</text>
+          <text size={30} fontSize={30}>Years</text>
+        </Meta>
+        <Meta>
+          <text size={110} fontSize={120}>{months}</text>
+          <text size={30} fontSize={30}>Months</text>
+        </Meta>
+        <Meta>
+          <text size={110} fontSize={120}>{days}</text>
+          <text size={30} fontSize={30}>Days</text>
+        </Meta>
+      </flex>
+      <fill color="white" />
+    </flex>
+
+    <fill color="white" />
+  </flex>
+}
+
 export default function Tracker({width, start, end}) {
   const s = Date.parse(start)
   const e = Date.parse(end)

internal/module/scrn/weather.jsx

···
       const temp = Math.round(weather.current.temperature_2m)
       const unit = weather.current_units.temperature_2m
 
-      inner = <text fontSize={80}>
+      inner = <text fontSize={60}>
         {temp} {unit}
       </text>
     } else {

main.go

···
 	r := gin.Default()
 	handler.HandleGroup(r.Group("/api"))
 
-	if err := r.RunTLS(":8081", "localhost.crt", "localhost.key"); err != nil {
+	if err := r.Run(":8081"); err != nil {
 		log.Fatalf("%s", err)
 	}
 }