@fugood/bricks-project 2.25.0-beta.4 → 2.25.0-beta.41

package/skills/bricks-ctor/references/buttress.md

@@ -0,0 +1,245 @@
+# Buttress (Remote Inference)
+
+Backend system for offloading compute-intensive AI generator tasks from BRICKS devices to more powerful machines.
+
+## Purpose
+
+When mobile devices or embedded systems lack hardware for local AI inference (LLM, speech-to-text), Buttress transparently delegates work to a server with appropriate resources (GPU).
+
+## How It Works
+
+1. **Capability Exchange**: Client and server share hardware capabilities
+2. **Strategy Selection**: System decides local vs. remote execution
+3. **Transparent Offloading**: Generator operates same way, execution happens remotely
+
+## Supported Generators
+
+- LLM (GGML) (LlmMlx.ts) - Local Large Language Model inference with GGML
+- LLM (MLX) (LlmGgml.ts) - Local Large Language Model inference with MLX
+- Speech-to-Text (GGML) (SpeechToTextGgml.ts) - Local Speech-to-Text inference with GGML
+
+## Client Configuration
+
+In generator properties, configure `buttressConnectionSettings`:
+
+| Setting | Description |
+|---------|-------------|
+| `enabled` | Toggle Buttress offloading |
+| `autoDiscoverType` | `auto` (LAN auto-discovery, recommended) or `manual` (typed URL) |
+| `url` | Server URL (`manual` mode only — leave empty for `auto`) |
+| `fallbackType` | If Buttress is unreachable: `use-local` runs locally, `no-op` blocks the load |
+| `strategy` | Execution preference (see below) |
+
+The launcher provides the access token automatically — there is **no user-facing access-token setting**. In `auto` mode the launcher discovers servers bound to the device's workspace and uses its workspace-scoped JWT; in `manual` mode it sends the same JWT only when the typed URL belongs to a server bound to the same workspace (verified against the server's `/buttress/info`).
+
+### `autoDiscoverType` options
+
+| Mode | When to use | What the device does |
+|------|-------------|----------------------|
+| `auto` | LAN deployment with a workspace-bound buttress-server | Listens for UDP announcements and picks the strongest server bound to its workspace; reconnects automatically when the workspace flips |
+| `manual` | Internet-reachable server, mixed networks, or a public/unbound server | Connects to the typed `url` directly; sends a token only when the server is bound to the same workspace |
+
+### Strategy options
+
+| Strategy | Description |
+|----------|-------------|
+| `prefer-local` | Use local if capable, fallback to Buttress |
+| `prefer-buttress` | Use Buttress if available, fallback to local |
+| `prefer-best` | Auto-select based on capability comparison |
+
+## Generator Configuration Examples
+
+### Auto-discovery (recommended)
+
+Workspace-bound launcher + workspace-bound buttress-server on the same LAN. No URL needed — discovery picks the highest-scoring server that runs the requested backend.
+
+```typescript
+import { makeId } from 'bricks-ctor'
+
+const llmGenerator: GeneratorLLM = {
+  __typename: 'Generator',
+  templateKey: 'GENERATOR_LLM',
+  id: makeId('generator'),
+  title: 'Chat LLM',
+  description: '',
+  property: {
+    modelUrl: 'https://huggingface.co/ggml-org/gemma-3-12b-it-qat-GGUF/resolve/main/gemma-3-12b-it-qat-q4_0.gguf',
+    contextSize: 8192,
+    buttressConnectionSettings: {
+      enabled: true,
+      autoDiscoverType: 'auto',
+      fallbackType: 'use-local',
+      strategy: 'prefer-best',
+    },
+  },
+  events: {},
+  switches: [],
+}
+```
+
+### Manual URL
+
+Use when the server isn't on the launcher's broadcast domain (cross-subnet, internet, behind a reverse proxy) or you want to point at a specific public/unbound server.
+
+```typescript
+buttressConnectionSettings: {
+  enabled: true,
+  autoDiscoverType: 'manual',
+  url: 'http://192.168.1.100:2080',
+  fallbackType: 'use-local',
+  strategy: 'prefer-best',
+}
+```
+
+> ⚠️ With `fallbackType: 'no-op'` the generator refuses to load locally if Buttress is unreachable. Use `'use-local'` whenever the device can also run the model standalone.
+
+## Integrating a discovered buttress-server
+
+The ctor-desktop "Local Devices" panel (and the `bricks buttress scan` CLI) can hand you a server's identity, workspace, and announced generator caps. When the user asks to integrate one:
+
+1. **Confirm workspace match.** The discovery message says whether the server's workspace matches this project's. If it doesn't, do NOT add the integration — instruct the user to run `bricks buttress unbind && bricks buttress bind` from this workspace's owner CLI on the server host. The launcher won't trust a cross-workspace server.
+
+2. **Map announced types to generator templates.** For each `generators[].type` in the announce, target the matching templateKey (create the generator if absent):
+
+   | Announced type | templateKey                  | Default model |
+   |----------------|------------------------------|---------------|
+   | `ggml-llm`     | `GENERATOR_LLM`              | `ggml-org/gemma-3-12b-it-qat-GGUF` (≥20 GB usable) or `ggml-org/gpt-oss-20b-GGUF` (~12 GB usable) |
+   | `mlx-llm`      | `GENERATOR_MLX_LLM`          | `mlx-community/Qwen3-4B-4bit` (or a larger 4-bit quant if `usableBytes` allows) |
+   | `ggml-stt`     | `GENERATOR_SPEECH_INFERENCE` | `BricksDisplay/whisper-ggml` (filename `ggml-small-q8_0.bin`) |
+
+   Pick a model that fits the announced `usableBytes`. Set `contextSize` to match.
+
+3. **Use the canonical auto-discovery config** from "Auto-discovery (recommended)" above. Don't switch to manual mode just because the server is on the LAN — auto mode picks the workspace-bound server automatically and rebinds when the device's workspace flips.
+
+### Real-device caveat
+
+Buttress LAN auto-discovery uses native UDP via `react-native-jsi-udp`. The iOS Simulator silently fails to bind UDP, so auto mode is a no-op there. With `fallbackType: 'use-local'` the generator falls back to local inference in the simulator — dev/test stays functional. **Validate the buttress path itself only when deploying to a real Foundation device; don't gate the build on simulator validation.**
+
+## Server Setup
+
+### Requirements
+- [Bun](https://bun.sh) v1.3+
+- GPU recommended for LLM/STT
+
+### Installation
+
+```bash
+bun add -g @fugood/buttress-server
+```
+
+### Start Server
+
+```bash
+bricks-buttress
+# or with config
+bricks-buttress --config ./config.toml
+```
+
+### CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `-p, --port` | Port (default: 2080) |
+| `-c, --config` | TOML config file path |
+| `-v, --version` | Show version |
+| `-h, --help` | Show help |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `HF_TOKEN` | Hugging Face token for model downloads |
+| `ENABLE_OPENAI_COMPAT_ENDPOINT` | Set to `1` for OpenAI-compatible API |
+| `BRICKS_BUTTRESS_STATE_DIR` | Override the workspace state directory (default `~/.bricks-cli/buttress`) |
+
+## Bind the Server to a Workspace
+
+To use `autoDiscoverType: 'auto'` — and to require workspace-scoped JWT auth — pair the buttress-server with a BRICKS workspace using the `bricks buttress` CLI commands. An unbound server stays in legacy public mode and accepts any LAN client.
+
+### One-time bind
+
+```bash
+# Log into the cloud bricks-server with the workspace owner's account
+bricks auth login
+
+# Pair the buttress-server running on this machine with the active workspace
+bricks buttress bind
+
+# Restart bricks-buttress so it picks up the new state.json
+```
+
+`bricks buttress bind` writes `~/.bricks-cli/buttress/state.json` containing the workspace id, the issuer's Ed25519 public key, and a stable `serverId` (defaults to `buttress-<machineId>`). Override location with `--state-dir` or `$BRICKS_BUTTRESS_STATE_DIR`. For headless setups, use `bricks buttress bind --print` to emit state.json to stdout.
+
+### Verify and manage
+
+```bash
+# Show local binding + workspace-side bound list
+bricks buttress status
+
+# Discover buttress-servers on the LAN (with version, auth state, generator caps)
+bricks buttress scan
+
+# Issue a long-lived workspace access token (CI / ctor agents that already hold a workspace token)
+bricks buttress issue-token --ttl 86400
+
+# Detach this server from the workspace
+bricks buttress unbind
+```
+
+After binding, launchers in the same workspace will auto-discover this server; manual-mode generators will only send their access token if the server's reported workspace matches their own.
+
+## Server Configuration (TOML)
+
+```toml
+[server]
+port = 2080
+
+[runtime]
+cache_dir = "./.buttress-cache"
+n_threads = 6
+flash_attn_type = "on"
+cache_type_k = "q8_0"
+cache_type_v = "q8_0"
+
+# LLM Generator
+[[generators]]
+type = "ggml-llm"
+[generators.backend]
+variant_preference = ["cuda", "vulkan", "default"]
+gpu_memory_fraction = 0.95
+[generators.model]
+repo_id = "ggml-org/gemma-3-12b-it-qat-GGUF"
+download = true
+n_ctx = 8192
+
+# STT Generator
+[[generators]]
+type = "ggml-stt"
+[generators.backend]
+variant_preference = ["cuda", "vulkan", "default"]
+[generators.model]
+repo_id = "BricksDisplay/whisper-ggml"
+filename = "ggml-small-q8_0.bin"
+download = true
+use_gpu = true
+```
+
+## Use Cases
+
+### Resource-Constrained Devices
+Digital signage with basic hardware offloads LLM to powerful server.
+
+### Shared GPU Resources
+Multiple devices share single GPU server for inference.
+
+### Development Testing
+Test AI features on lightweight dev machines by connecting to beefy server.
+
+## Best Practices
+
+1. **Network reliability**: Ensure stable LAN connection to Buttress server
+2. **Fallback strategy**: Configure appropriate fallback for critical features
+3. **Server monitoring**: Monitor Buttress server resource usage
+4. **Model consistency**: Ensure client and server use compatible models
+5. **Security**: Run Buttress on private network, not public internet
+6. **Latency awareness**: Account for network latency in UX design

package/skills/bricks-ctor/references/data-calculation.md

@@ -0,0 +1,239 @@
+# Data Calculation (JS Sandbox)
+
+Transform and compute Data Bank values using JavaScript scripts. Calcs are for **pure data transformation only** — see [Architecture Patterns](architecture-patterns.md) for the pattern selection guide.
+
+| If you need to... | Use instead |
+|---|---|
+| Call an LLM / AI model | Generator (Assistant, LLM, HTTP) |
+| Sequence multiple actions | Event Action Chain |
+| Set a data value directly | PROPERTY_BANK system action |
+| Compute a simple expression | PROPERTY_BANK_EXPRESSION |
+| Transform/format/parse data | Data Calculation (correct use) |
+
+## Authoring Contract
+
+```typescript
+import { makeId } from 'bricks-ctor'
+import { readFile } from 'node:fs/promises'
+
+const calculation: DataCalculationScript = {
+  __typename: 'DataCalculationScript',
+  id: makeId('property_bank_calc'),
+  title: 'Format Price',
+  description: 'Formats price with currency symbol',
+  note: '',
+  triggerMode: 'auto', // 'auto' (default) | 'manual'
+  enableAsync: false,
+  // Inline code for short scripts...
+  code: `
+    const price = inputs.price || 0
+    const currency = inputs.currency || 'USD'
+    return new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency,
+    }).format(price)
+  `,
+  // ...or load from a file (preferred for longer scripts):
+  // code: await readFile(new URL('./format-price.sandbox.js', import.meta.url), 'utf8'),
+  inputs: [
+    { key: 'price', data: () => priceData, trigger: true },
+    { key: 'currency', data: () => currencyData, trigger: false },
+  ],
+  output: () => formattedPriceData,
+  outputs: [], // Additional named outputs (see Multiple Outputs)
+  error: null, // or () => errorData for error handling
+}
+```
+
+### Field Rules (defaults and constraints)
+
+- `trigger` **defaults to `false` when omitted** — always set it explicitly. A calc whose inputs are all non-trigger never auto-runs.
+- `triggerMode` defaults to `'auto'` when omitted.
+- `output` receives the **whole return value**. `outputs` entries extract fields by key from a returned object — `key` is a lodash-get path, so deep paths like `'user.name'` work. `output`, `outputs`, and `error` can be combined.
+- `error` receives the error **message string** when the script throws. Both extraction steps run on every execution: a success overwrites the error Data, a failure overwrites the output Data(s) — don't expect stale values to persist.
+- **Auto mode rejects the same Data in both `inputs` and `output`/`outputs`/`error`** — compile fails with `Not allow duplicate set property id between inputs / outputs / output / error`. Manual mode allows the overlap (self-referential updates, see Recipes).
+- `.sandbox.js` files use an `export function main() { ... }` wrapper — compile unwraps it. Raw statements also work, but the wrapper keeps linters happy since script bodies use top-level `return`.
+
+## Trigger Modes
+
+| Mode | Description |
+|------|-------------|
+| `auto` | Run on every write to a `trigger: true` input (even if the value is unchanged) |
+| `manual` | Never auto-runs; only via `PROPERTY_BANK_COMMAND` action. Allows the same Data as both input and output |
+
+Use `manual` to prevent circular dependencies, for explicit control, or when an output must feed back into an input.
+
+## Triggering via PROPERTY_BANK_COMMAND
+
+`input` references a Data that is an input of the target calc — the system runs the calc(s) that data feeds into. It does NOT reference the DataCalculation itself.
+
+- **Manual calc**: ANY input works — `trigger` flags are ignored for manual-mode calcs.
+- **Auto calc**: only `trigger: true` inputs work; commanding a `trigger: false` input is a silent no-op.
+
+```typescript
+const triggerCalc: EventAction = {
+  handler: 'system',
+  action: {
+    __actionName: 'PROPERTY_BANK_COMMAND',
+    parent: 'System',
+    dataParams: [
+      { input: () => priceData }, // Reference to an input Data of the calc
+    ],
+  },
+}
+```
+
+- When the same chain **writes a calc input first** (e.g. `PROPERTY_BANK` setting `dLastButton`) then issues `PROPERTY_BANK_COMMAND`, set `waitAsync: true` on the write so the calc reads the new value rather than the pre-chain snapshot. See [Event Action Chains](architecture-patterns.md#event-action-chains-priority-2).
+- When a **later action reads the calc's outputs**, set `waitAsync: true` on the `PROPERTY_BANK_COMMAND` action itself — it awaits the full calc chain including output writes.
+- A dataParam's `value` acts as an execution gate: `{ input: () => d, value: false }` skips that trigger (combine with `mapping` for conditional runs).
+
+## Script Sandbox
+
+Scripts run in `use strict` mode as a function body — top-level `return` returns the calc result. No `fetch`, `XMLHttpRequest`, or `require` in any mode: I/O belongs to Generators.
+
+### Built-in Globals
+
+| Global | Description |
+|--------|-------------|
+| `inputs` | Object with input values (keyed by input `key`) |
+| `console` | `{ log, error, warn, info }` — output is only visible in DevTools debug sessions; production is a no-op |
+| `Platform` | `{ OS, isTV, isPad, isVision, isElectron }` |
+| `TextEncoder`, `TextDecoder` | Text encoding/decoding |
+| `Buffer` | Node.js Buffer (without `allocUnsafe`/`allocUnsafeSlow`) |
+| `btoa`, `atob` | Base64 encoding/decoding |
+
+### Async Mode
+
+Sync mode (default) has **no `Promise`, timers, or `await`**. Enable `enableAsync: true` to unlock:
+
+- `Promise`, `setTimeout`, `setInterval`, `setImmediate`, `clearTimeout`, `clearInterval`, `clearImmediate`, `requestAnimationFrame`
+- Full lodash (sync mode omits `debounce`, `delay`, `defer`)
+- `await` at the top level of the script
+
+```typescript
+code: `
+  const result = await new Promise((resolve) => {
+    setTimeout(() => resolve(inputs.value * 2), 100)
+  })
+  return result
+`,
+enableAsync: true,
+```
+
+### Runtime Environment
+
+| Platform | Engine |
+|----------|--------|
+| Android | Hermes engine sandbox |
+| iOS | JavaScriptCore sandbox |
+| Electron desktop | Web Worker (V8) |
+| Web preview / Simulator | Web Worker (V8) |
+
+Simulator (Path 1) runs scripts on V8 while devices run Hermes/JSC — engine-sensitive code (date parsing, Intl, regex features) can pass in the Simulator and fail on device.
+
+### Available Libraries
+
+All exposed as globals. No network/file-download capability in any of them.
+
+| Global | Library | Notes |
+|--------|---------|-------|
+| `_`, `lodash` | lodash | Sync mode omits `debounce`/`delay`/`defer` |
+| `voca` | voca | String manipulation |
+| `invariant` | invariant | Assertions |
+| `json5` | json5 | JSON5 parsing |
+| `qs` | qs | Query string parsing |
+| `url` | node-url | URL parsing |
+| `bytes` | bytes | Byte parsing/formatting |
+| `ms` | ms | Millisecond conversion |
+| `base45` | base45 | Base45 encoding |
+| `iconv` | iconv-lite | Character encoding |
+| `math`, `mathjs` | mathjs | Math library |
+| `chroma` | chroma-js | Color manipulation |
+| `moment` | moment | Date/time; auto parseFormat for string args |
+| `nanoid` | nanoid | Unique ID generation |
+| `md5` | md5 | MD5 hashing |
+| `crypto` | crypto-browserify | Crypto functions |
+| `kjurJWS` | jsrsasign | JWT/JWS signing (`KJUR.jws.JWS`) |
+| `coseVerify` | cose-js | COSE verification (sync) |
+| `fflate` | fflate | `{ zlibSync, unzlibSync, gzipSync, gunzipSync, compressSync, decompressSync, strFromU8 }` |
+| `cbor` | cbor | `{ encode, decode, decodeFirstSync, decodeAllSync, addSemanticType }` |
+| `fs` | (in-repo fs-compat) | File system; no download/upload methods |
+| `parseDocument` | officeparser (in-repo fork) | Office document parsing (async) |
+| `TurndownService` | turndown | HTML to Markdown |
+| `OpenCC` | opencc-js | Chinese conversion `{ Converter, ConverterFactory, CustomConverter, Locale }` |
+| `TOON` | @toon-format/toon | TOON format parsing |
+
+## Recipes
+
+### Multiple Outputs
+
+Return an object; each `outputs` entry extracts its `key`:
+
+```typescript
+outputs: [
+  { key: 'total', data: () => totalData },
+  { key: 'tax', data: () => taxData },
+  { key: 'subtotal', data: () => subtotalData },
+],
+output: null,
+error: null,
+code: `
+  const subtotal = inputs.price * inputs.quantity
+  const tax = subtotal * 0.1
+  const total = subtotal + tax
+  return { total, tax, subtotal }
+`,
+```
+
+### Manual Self-Referential Update
+
+When an update is too complex for `PROPERTY_BANK_EXPRESSION` and must read its own previous value — manual mode allows the same Data as input and output:
+
+```typescript
+const appendHistory: DataCalculationScript = {
+  __typename: 'DataCalculationScript',
+  id: makeId('property_bank_calc'),
+  title: 'Append History Entry',
+  triggerMode: 'manual',
+  enableAsync: false,
+  code: `
+    const history = Array.isArray(inputs.history) ? inputs.history : []
+    return [...history, { entry: inputs.entry, at: moment().toISOString() }].slice(-50)
+  `,
+  inputs: [
+    { key: 'history', data: () => historyData, trigger: true },
+    { key: 'entry', data: () => entryData, trigger: true },
+  ],
+  output: () => historyData, // same Data as input — manual mode only
+  outputs: [],
+  error: null,
+}
+// Run it from an event chain: PROPERTY_BANK writes entryData (waitAsync: true),
+// then PROPERTY_BANK_COMMAND with input: () => entryData.
+```
+
+## Failure Modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Calc never auto-runs | `trigger` omitted on inputs (defaults to `false`) | Set `trigger: true` explicitly |
+| `PROPERTY_BANK_COMMAND` does nothing | Auto calc + `trigger: false` input, or `input` doesn't reference an input Data of the calc | Command a `trigger: true` input (auto) or any input (manual) |
+| Compile error `Not allow duplicate set property id...` | Auto mode with same Data as input and output | Use `triggerMode: 'manual'`, or split into separate Data |
+| Calc reads stale value written earlier in the same chain | Missing `waitAsync: true` on the preceding write | Set `waitAsync: true` on the write action |
+| Works in Simulator, fails on device | V8 vs Hermes/JSC engine difference | Verify on device (Path 2); avoid engine-sensitive parsing |
+| `console.log` shows nothing | Console only emits during DevTools debug sessions | Attach DevTools, or write debug values to an output Data |
+| `Promise`/`setTimeout` undefined, or `Async mode is required` error | `enableAsync: false` | Set `enableAsync: true` |
+
+## Best Practices
+
+1. **Avoid circular deps**: Set non-triggering inputs (`trigger: false`) or use `manual` mode
+2. **Error handling**: Always set `error` output for scripts that might fail
+3. **Keep scripts pure**: Avoid side effects, return computed values
+4. **Debounce rapid updates**: Use `manual` mode + timer for high-frequency inputs (auto calcs re-run on every write, even unchanged)
+
+## Anti-Patterns (AVOID)
+
+See [Architecture Patterns](architecture-patterns.md) for the full pattern selection guide.
+
+### Using Data Calc as an orchestrator
+Scripts that manage state machines, control UI flow, or coordinate multi-step processes belong in Event Action Chains. Symptoms: if/else on "what happens next", mirror `dFooResult` outputs that copy back to `dFoo` via `valueChange`, or a `dLastInput` field set-then-cleared to force an auto calc. See the "user-driven state machine" recipe in [Architecture Patterns](architecture-patterns.md).

package/skills/bricks-ctor/references/simulator.md

@@ -0,0 +1,131 @@
+# Simulator
+
+What the Simulator can and can't faithfully reproduce — so a passing Simulator run means what you think it means. This is the fidelity companion to Path 1 in [Verification Toolchain](verification-toolchain.md); read that for how to *drive* the Simulator (compile, screenshot, Automations).
+
+## What it is
+
+- The default Path 1 target: it renders your compiled project on your computer, with no device required.
+- It runs in Chromium/Electron — a browser-class runtime, not the device runtime. Two consequences to design verification around: it has a browser's capabilities and limits (below), and its JavaScript engine differs from the device's (iOS runs JSC, Android runs Hermes), so engine-specific behavior won't surface here.
+
+A Simulator screenshot proves **layout, navigation, Standby Transitions, Data wiring, and generator/Automation wiring**. It does *not* prove anything that depends on real hardware, real models, or capabilities the preview runtime lacks.
+
+## Automation screenshots
+
+`match_screenshot` stores Simulator automation artifacts at the project level:
+
+```text
+.bricks/automation_screenshots/
+  last/
+  failed/
+  diff/
+```
+
+There is no application-id subdirectory; in CTOR the project is the application. Generated project `.gitignore` files exclude this directory.
+
+When a `match_screenshot` baseline is missing or updated, the baseline goes under `last/`. When a screenshot mismatch occurs, the current capture goes under `failed/` and the pixel diff goes under `diff/`. File names follow `<screenshotName>+local+<timestamp>.png`.
+
+In CTOR Desktop, `simulator_invoke` reports any automation screenshot files created or changed by the invocation in an `Automation screenshots:` section. It still separately reports the ordinary preview capture at `.bricks/simulator-screenshot.jpg`.
+
+## What the Simulator can't reproduce
+
+Because it runs in a browser-class preview rather than on device hardware, the Simulator cannot exercise these — a green run says nothing about them. Verify on a real device (Path 2):
+
+| Area | In the Simulator |
+|------|------------------|
+| BLE (Central / Peripheral), Video Streaming | Not available |
+| Raw network sockets — UDP, TCP, TCP Server, MQTT Broker | Not available (also why Buttress LAN discovery is a no-op — see [Buttress](buttress.md)) |
+| Android Intent | Not available (Android-only) |
+| On-device database **persistence** (SQLite / Vector Store) | Not available — both run in-memory in the Simulator (see caveats below), so data never survives a reload |
+| GGML Text-to-Speech | No vocoder in the preview — use an ONNX TTS model to hear speech |
+
+These work, but with browser caveats:
+
+| Area | Caveat |
+|------|--------|
+| Serial Port | Works via WebSerial — requires browser support and a user gesture |
+| WebView / WebCrawler | Subject to browser CORS — a load/fetch that works on device may be blocked |
+| On-device AI (LLM / STT / VAD / Vector Store / Reranker) | Runs **single-threaded** — far slower than the device, not representative of real latency. Also subject to the model fallbacks below |
+| On-device database (SQLite — `GENERATOR_SQLITE`) | Runs for real on the in-memory WASM `sqlite-vec` build — `execute` / `query` / `transaction` / batch all work. `storageType: file` is transparently treated as in-memory, so nothing persists across reloads (see above) |
+| Scene3D / Maps / Sketch / WebRTC | Supported |
+
+Feature availability also varies across the device platforms themselves (iOS / tvOS / Android / the desktop OSes). When a deployment targets a specific platform's capability, confirm it on that platform.
+
+## Network security
+
+The Simulator blocks insecure connections from `applicationPreview` by default: `http://` and `ws://` requests fail, while `https://` and `wss://` are allowed. The Simulator internally allows its own preview host when running the development preview.
+
+Generated projects include this project-level setting:
+
+```json
+{
+  "allowedInsecureHosts": []
+}
+```
+
+Add explicit entries only when you deliberately need to test an insecure endpoint in the Simulator. A bare `host:port` allows both `http://` and `ws://` for that host:
+
+```json
+{
+  "allowedInsecureHosts": ["localhost:8080"]
+}
+```
+
+Use a URL form when only one insecure protocol should be allowed:
+
+```json
+{
+  "allowedInsecureHosts": ["http://localhost:8080"]
+}
+```
+
+In that example, `http://localhost:8080` is allowed and `ws://localhost:8080` remains blocked.
+
+Prefer HTTPS/WSS for anything that is not local development.
+
+## Feature fallbacks — what the Simulator fakes
+
+So that camera and AI features are usable without device permissions, multi-gigabyte downloads, API keys, or a remote inference backend, the Simulator **transparently substitutes a lightweight stand-in** for a few bricks/generators. The config you author is untouched — only the Simulator's runtime behavior differs. **A fallback render proves wiring and layout, not the real feature.**
+
+| Brick / Generator | In the Simulator | Does NOT prove |
+|-------------------|------------------|----------------|
+| Camera (`BRICK_CAMERA`) | A 3D mock canvas, no camera permission prompt. `takePicture` snapshots the canvas; recording produces a placeholder clip | Real camera feed, focus, recording, permission flow |
+| Thermal Printer (`GENERATOR_THERMAL_PRINTER`) | A simulated printer — `init` / `checkStatus` / `scan` fake per-driver status and discovered devices (ESC/POS, Star, TSC, Castles); `print` renders an approximate on-screen receipt. A bottom-left bubble shows live status with a fault toggle to exercise error wiring. Print results can be exported as PNG via `bricks-cli` (see below) | Real device connection, actual paper output, exact native driver status codes |
+| LLM (`GENERATOR_LLM`) | Swapped to a tiny local stand-in model | Output quality / latency of your real model |
+| Reranker — GGML (`GENERATOR_RERANKER`) | Swapped to a small local multilingual reranker model | Ranking quality / latency of your real model |
+| Speech-to-Text — GGML (`GENERATOR_SPEECH_INFERENCE`) | Swapped to a tiny local model | Accuracy / latency of your real model |
+| Speech-to-Text — ONNX (`GENERATOR_ONNX_STT`) | Swapped to a tiny whisper model | Accuracy / latency of your real model |
+| Text-to-Speech — ONNX (`GENERATOR_TTS`) | Swapped to a tiny VITS model (no vocoder or speaker embedding) | Voice / quality / latency of your real model |
+| Vector Store (`GENERATOR_VECTOR_STORE`) | Runs with a tiny local embedding model — an OpenAI-source config works **without a key** | Real embeddings / dimensions / recall (and no persistence — see above) |
+| Buttress (all generators) | **Disabled** — there is no remote inference backend in the Simulator | The Buttress offload path — see [Buttress](buttress.md) |
+| MLX LLM (`GENERATOR_MLX_LLM`) | Runs as authored, except Buttress is disabled | The MLX / Buttress path |
+
+These swaps make the AI generators runnable in the Simulator for wiring checks — validate real models, quality, and latency on a device (Path 2).
+
+### Inspecting simulated thermal printer print results
+
+With the Simulator running (CDP at `localhost:19852`, see [Verification Toolchain](verification-toolchain.md)), `bricks-cli` can read the simulated printers and export a print result as a PNG image — no need to open the bubble popover or screenshot the whole window:
+
+```bash
+# Printers + print history (newest first; shows the --index value per result)
+bricks devtools simulator thermal-printer list -p 19852
+bricks devtools simulator thermal-printer list -p 19852 -j --commands   # full print payloads as JSON
+
+# Render one print result to PNG (defaults: the only printer, --index 0 = latest)
+bricks devtools simulator thermal-printer print-result -p 19852 -o receipt.png
+bricks devtools simulator thermal-printer print-result -p 19852 --index 1 --scale 2 -o older.png
+```
+
+The PNG is the same approximate receipt the on-screen preview shows (rendered from the print payload). It proves the payload wiring — content, ordering, alignment, barcode/QR/image presence — not pixel-exact native raster output. Print history is in-memory (up to 10 per printer) and clears on preview reload.
+
+### Running the real implementation instead
+
+Each substituted brick/generator can be switched back to its real implementation per item: open the **gear (Simulator settings)** in the editor's preview toolbar, uncheck the item, and **Apply**. Apply persists the choice and reloads the preview so it takes effect (a plain refresh won't). Use this to, e.g., point a Vector Store at a real API key in the preview. The browser limits above still apply, and **Buttress stays disabled regardless** — there's no backend for it here.
+
+The Thermal Printer is the exception: it has no real web implementation to switch to (the native drivers can't run in a browser), so it is **always simulated** and is not in the gear list.
+
+## Enough vs. escalate
+
+- **Simulator is enough for:** layout, navigation, Standby Transitions, Data wiring, Automation / state-machine happy paths, and confirming a generator fires and handles its events.
+- **Escalate to a real device for:** anything in the "can't reproduce" tables, real camera / peripherals / payment / identity, real model quality & latency, multi-device Local Sync, on-device persistence, the Buttress offload path, and engine-specific behavior.
+
+The full Path 1/2/3 decision rule lives in [Verification Toolchain](verification-toolchain.md).