# SlexKit Capabilities for LLMs

Use `std.*` for pure deterministic calculations and formatting. Use `api.*` only for host-injected or secure-runtime capabilities that may require policy.

## Expression Context

- `g` (always): Reactive state proxy.
- `std` (always): Pure deterministic SlexKit standard library.
- `api` (host-injected): Host or secure runtime capability object.
- `$event` (event handlers): Event payload for on* handlers.
- `$item` ($for): Current array item.
- `$index` ($for): Current item index.
- `$key` ($for): Current item key.

## std.math

Small numeric helpers for common interactive calculations.

- `std.math.clamp(value, min, max)`: Clamp a number into a range. Example: `std.math.clamp(g.score, 0, 100)`
- `std.math.round(value, digits = 0)`: Round with a fixed number of decimal digits. Example: `std.math.round(g.latency, 1)`
- `std.math.safeDivide(numerator, denominator, fallback = 0)`: Divide with a fallback for zero or invalid denominators. Example: `std.math.safeDivide(g.used, g.total, 0)`
- `std.math.percent(part, total, digits = 1)`: Return part / total as a percentage number. Example: `std.math.percent(g.done, g.total, 1)`
- `std.math.lerp(start, end, t)`: Linear interpolation. Example: `std.math.lerp(0, 100, g.progress)`

## std.stats

Finite-number aggregations for arrays.

- `std.stats.sum(values)`: Sum finite numeric values. Empty arrays return 0. Example: `std.stats.sum(g.samples)`
- `std.stats.mean(values)`: Average finite numeric values. Empty arrays return NaN. Example: `std.stats.mean(g.samples)`
- `std.stats.min(values)`: Minimum finite numeric value. Empty arrays return NaN. Example: `std.stats.min(g.samples)`
- `std.stats.max(values)`: Maximum finite numeric value. Empty arrays return NaN. Example: `std.stats.max(g.samples)`
- `std.stats.median(values)`: Median finite numeric value. Empty arrays return NaN. Example: `std.stats.median(g.samples)`

## std.format

Deterministic display formatting with en-US defaults.

- `std.format.fixed(value, digits = 2)`: Format a number with fixed decimal places. Example: `std.format.fixed(g.voltage, 3)`
- `std.format.number(value, digits = 0, locale = 'en-US')`: Locale number formatting. Example: `std.format.number(g.requests)`
- `std.format.compact(value, digits = 1, locale = 'en-US')`: Compact number formatting. Example: `std.format.compact(g.users)`
- `std.format.percent(ratio, digits = 1)`: Format a ratio as a percentage string. Example: `std.format.percent(g.done / g.total, 1)`
- `std.format.currency(value, currency = 'USD', locale = 'en-US')`: Format a currency value. Example: `std.format.currency(g.revenue, 'USD')`

## std.units

Small unit display helpers for common dashboards.

- `std.units.withUnit(value, unit, digits = 2)`: Format a value with a unit suffix. Example: `std.units.withUnit(g.power, 'W', 1)`
- `std.units.bytes(value, digits = 1)`: Format bytes as B, KB, MB, GB, TB, or PB. Example: `std.units.bytes(g.payloadBytes)`
- `std.units.duration(ms, digits = 1)`: Format milliseconds as ms, s, min, or h. Example: `std.units.duration(g.elapsedMs)`
- `std.units.si(value, unit = '', digits = 2)`: Format with SI prefixes. Example: `std.units.si(g.frequency, 'Hz', 2)`

## Policy-Gated Runtime API

- `api.get(url, options)` (network, secure default: denied): Policy-gated GET request.
- `api.post(url, body, options)` (network, secure default: denied): Policy-gated POST request.
- `api.fetch(url, options)` (network, secure default: denied): Policy-gated GET or POST request.
- `api.setTimeout(fn, ms)` (timer, secure default: denied): Policy-gated timeout.
- `api.clearTimeout(id)` (timer, secure default: denied): Clear a policy-gated timeout.
- `api.setInterval(fn, ms)` (timer, secure default: denied): Policy-gated interval.
- `api.clearInterval(id)` (timer, secure default: denied): Clear a policy-gated interval.
- `api.raf(fn)` (animation, secure default: denied): Policy-gated animation frame.
- `api.cancelRaf(id)` (animation, secure default: denied): Cancel a policy-gated animation frame.
- `api.createCanvas(width, height)` (canvas, secure default: denied): Create a policy-counted canvas.
- `api.getCanvasContext(canvas, contextId, options)` (canvas, secure default: denied): Get a policy-checked canvas context.
- `api.onDispose(fn)` (lifecycle, secure default: available): Register runtime cleanup.
- `api.now()` (lifecycle, secure default: available): Runtime clock.
- `api.isTimeoutError(error)` (diagnostics, secure default: available): Check timeout errors.
- `api.isNetworkError(error)` (diagnostics, secure default: available): Check network errors.
- `api.isPolicyError(error)` (diagnostics, secure default: available): Check policy errors.
- `api.errorMessage(error)` (diagnostics, secure default: available): Extract a displayable error message.

Secure mode blocks native `fetch`, `XMLHttpRequest`, `WebSocket`, `setTimeout`, `setInterval`, and `requestAnimationFrame`. Use `api.get`, `api.post`, `api.fetch`, `api.setTimeout`, `api.setInterval`, and `api.raf` when host policy enables them.

## Recipe: Std Calculator

```slex
{
  slex: "0.1",
  namespace: "std_calculator",
  g: { done: 7, total: 12, samples: [120, 95, 143, 110], bytes: 1536000 },
  layout: {
    "card:summary": {
      title: "Stdlib calculator",
      "stat:progress": { label: "Progress", "$value": "std.format.percent(std.math.safeDivide(g.done, g.total), 1)" },
      "stat:average": { label: "Average", "$value": "std.format.fixed(std.stats.mean(g.samples), 1)", unit: "ms" },
      "stat:payload": { label: "Payload", "$value": "std.units.bytes(g.bytes)" }
    }
  }
}
```

## Recipe: Secure Network Card

```slex
{
  slex: "0.1",
  namespace: "secure_network_card",
  g: {
    status: "idle",
    async load() {
      this.status = "loading";
      try {
        var result = await api.get("https://api.example.com/status", { credentials: "omit" });
        this.status = "HTTP " + result.status;
      } catch (error) {
        this.status = api.isPolicyError(error) ? "blocked by policy" : api.errorMessage(error);
      }
    }
  },
  layout: {
    "card:network": {
      title: "Secure network card",
      "button:load": { label: "Load", onclick: "g.load()" },
      "text:status": { "$text": "g.status" }
    }
  }
}
```

## Recipe: Timer and Animation Policy

- Timers are disabled in secure mode unless `policy.timer.enabled` is true.
- Use `api.setTimeout` and `api.setInterval`; do not use native scheduling globals.
- Animation is disabled unless `policy.animation.enabled` is true; use `api.raf`.