@fugood/bricks-ctor 2.25.0-beta.60 → 2.25.0-beta.61

package/skills/bricks-ctor/references/architecture-patterns.md

@@ -1,88 +0,0 @@
-# Architecture Patterns
-
-How to decompose complex flows into the right combination of BRICKS patterns.
-
-## Pattern Selection Priority
-
-Prefer higher-priority patterns; only fall to lower when they genuinely can't solve the sub-problem:
-
-| Priority | Pattern | Use For |
-|----------|---------|---------|
-| 1 | Generator + Events | I/O, AI inference, external data |
-| 2 | Event Action Chains | Orchestration, sequential steps |
-| 3 | System Actions | State changes, navigation, UI triggers |
-| 4 | Data Calculation | Pure data transformation ONLY |
-
-### Generators (Priority 1)
-For all external I/O and AI inference. Each generator emits events that naturally chain into actions.
-- **GeneratorAssistant**: multi-turn LLM conversations, function calling, built-in message history
-- **GeneratorLLM**: single-shot local inference (GGML)
-- **GeneratorHttp**: REST API calls
-- **GeneratorMqtt / GeneratorWebSocket**: real-time messaging
-
-### Event Action Chains (Priority 2)
-The primary way to orchestrate multi-step flows. A single event can contain an array of EventActions executed sequentially.
-- Use `waitAsync: true` to await async actions before the next step
-- Use `dataParams` + `mapping` to pass event data downstream
-- This is the "glue" that wires generators, state, and UI together
-- For Generator result UI: await Generator, write done/version Data; route/current Data stays identity.
-
-Sequential `PROPERTY_BANK` / `PROPERTY_BANK_EXPRESSION` actions in one chain read the data values that existed when the chain started. If a later action needs to read what an earlier action wrote, set `waitAsync: true` on the earlier action.
-
-### System Actions (Priority 3)
-Built-in commands for direct state and UI changes.
-- **PROPERTY_BANK**: set data value
-- **PROPERTY_BANK_EXPRESSION**: inline JS expression for simple compute
-  - The expression engine folds statements into a single expression: only expression
-    statements, simple `const`/`let` declarations, and a final return/expression are
-    supported — **no `if`/`for`/`while`/`switch`** (use ternaries). The same limit
-    applies inside a zero-arg IIFE body. Unsupported statements fail at runtime with
-    the error visible only in a DevTools session, so prefer ternary chains or move the
-    logic to a DataCalculationScript.
-- **CHANGE_CANVAS**: navigate to another canvas
-- **DYNAMIC_ANIMATION**: trigger animation
-- **ALERT / MESSAGE**: system feedback
-
-### Data Calculation (Priority 4)
-ONLY for deriving, formatting, or aggregating values from other data. Not for orchestration, side effects, or flow control.
-
-## Entity Aliases
-
-Set `alias` on entities to give them a stable, human-readable name:
-- Code generation uses alias as the variable name (e.g., `alias: 'submitBtn'` → `export const submitBtn`)
-- At runtime, devtools MCP tools accept alias instead of short ID and selectors can match by alias. Note: bricks-ctor does not directly interact with devtools MCP — aliases here primarily affect code generation
-- Aliases must be unique across the application — duplicates are excluded from resolution
-
-## Flow Decomposition
-
-When the user describes a complex flow, decompose it BEFORE writing code:
-
-### Step 1: Extract I/O boundaries
-Every external interaction maps to a Generator:
-- "call LLM" → GeneratorAssistant or GeneratorLLM
-- "fetch API" → GeneratorHttp
-- "speech to text" → GeneratorSpeechInference
-
-### Step 2: Extract state transitions
-Every UI change maps to a System Action in an event chain:
-- "show loading" → PROPERTY_BANK on a boolean data
-- "go to result screen" → CHANGE_CANVAS
-- "animate in" → DYNAMIC_ANIMATION
-
-### Step 3: Extract pure transformations
-Only actual data derivation maps to Data Calculation:
-- "format the response" → DataCalculationScript
-- "compute a score" → DataCalculationScript or DataCalculationMap
-
-### Step 4: Wire with Event Action Chains
-Connect the pieces through events on generators and bricks.
-
-## Recipe: user-driven state machine (calculator, form wizard, picker)
-
-A brief like "state vars X, Y, Z; button A updates X from X+Y; button B resets" is a state machine. The shape:
-
-- Each state variable is its own `Data` entity. Displays read it via `linkData(() => data.dFoo)`.
-- Each button's `onPress` is an Event Action Chain. For every state var that changes, append one `PROPERTY_BANK_EXPRESSION` whose `expression` reads the current state and returns the new value.
-- Use `Data Calculation` only for reusable pure derivations referenced as inputs to those expressions.
-
-A 10-button calculator with 4 state vars is ~10 small chains of 1–4 inline expressions. If you find yourself writing a single auto-mode `DataCalculationScript` that consumes all state vars and emits all-new state through mirror `dFooResult` data — or pinging a `dLastInput` field to force an auto calc to re-run — the chain shape was the right answer.

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

@@ -1,232 +0,0 @@
-# Automations
-
-E2E testing and scheduled execution for BRICKS applications. Simulates user behavior and validates application state.
-
-## Automation Types
-
-| Type      | Description                                                |
-| --------- | ---------------------------------------------------------- |
-| `launch`  | Run on application launch (restarts app when run manually) |
-| `anytime` | Execute anytime via manual trigger                         |
-| `cron`    | Scheduled execution using crontab expressions              |
-
-## Simulation Actions
-
-Automations can simulate:
-
-- **Brick Press**: Tap/click on bricks
-- **Key Events**: Key up/down for keyboard input
-- **HTTP Request**: API calls
-- **Execute Action**: Trigger system or generator actions
-
-## Assertions
-
-Automations can validate:
-
-- **Brick Exists**: Check if brick is rendered
-- **Event Triggered**: Verify event from Brick/Generator/Canvas
-- **Canvas Changed**: Confirm canvas navigation
-- **Property Assert**: Check Data Bank values
-- **Property Updated**: Wait for property change
-- **Match Screenshot**: Visual regression testing
-
-## TypeScript Example
-
-```typescript
-const testLoginFlow: AutomationTest = {
-  __typename: 'AutomationTest',
-  id: makeId('test'),
-  title: 'Test Login Flow',
-  timeout: 30000,
-  trigger_type: 'launch',
-  cases: [
-    {
-      __typename: 'TestCase',
-      id: makeId('test_case'),
-      name: 'Wait for login canvas',
-      run: ['wait_until_canvas_change', () => mainSubspace, () => loginCanvas, 5000],
-      exit_on_failed: true,
-      commented: false,
-      pre_delay: 0,
-      post_delay: 0,
-      jump_cond: [],
-    },
-    {
-      __typename: 'TestCase',
-      id: makeId('test_case'),
-      name: 'Press username input',
-      run: ['brick_press', () => mainSubspace, () => usernameInput],
-      exit_on_failed: true,
-      commented: false,
-      pre_delay: 0,
-      post_delay: 100,
-      jump_cond: [],
-    },
-    {
-      __typename: 'TestCase',
-      id: makeId('test_case'),
-      name: 'Assert username value',
-      run: ['assert_property', () => mainSubspace, () => usernameData, 'testuser'],
-      exit_on_failed: true,
-      commented: false,
-      pre_delay: 0,
-      post_delay: 0,
-      jump_cond: [],
-    },
-    {
-      __typename: 'TestCase',
-      id: makeId('test_case'),
-      name: 'Press login button',
-      run: ['brick_press', () => mainSubspace, () => loginButton],
-      exit_on_failed: true,
-      commented: false,
-      pre_delay: 0,
-      post_delay: 0,
-      jump_cond: [],
-    },
-    {
-      __typename: 'TestCase',
-      id: makeId('test_case'),
-      name: 'Wait for dashboard',
-      run: ['wait_until_canvas_change', () => mainSubspace, () => dashboardCanvas, 10000],
-      exit_on_failed: true,
-      commented: false,
-      pre_delay: 0,
-      post_delay: 0,
-      jump_cond: [],
-    },
-  ],
-  variables: [],
-}
-```
-
-## Test Methods
-
-| Method                       | Signature                                        | Description          |
-| ---------------------------- | ------------------------------------------------ | -------------------- |
-| `brick_press`                | `[subspace, brick, options?]`                    | Simulate brick press |
-| `brick_exists`               | `[subspace, brick, frame?]`                      | Check brick exists   |
-| `wait_until_brick_exists`    | `[subspace, brick, timeout?, frame?]`            | Wait for brick       |
-| `wait_until_event_trigger`   | `[subspace, sender, eventKey, timeout?]`         | Wait for event       |
-| `wait_until_canvas_change`   | `[subspace, canvas, timeout?]`                   | Wait for canvas      |
-| `keydown`                    | `[keyCode, pressedKey?, flags?]`                 | Key down event       |
-| `keyup`                      | `[keyCode, pressedKey?, flags?]`                 | Key up event         |
-| `http_request`               | `[url, options?]`                                | HTTP request         |
-| `assert_property`            | `[subspace, property, value]`                    | Assert data value    |
-| `wait_until_property_change` | `[subspace, property, value, timeout?]`          | Wait for value       |
-| `execute_action`             | `[subspace, handler, action, params?, options?]` | Execute action       |
-| `match_screenshot`           | `[name, threshold?, maxRetry?]`                  | Screenshot compare   |
-| `delay`                      | `[subspace?, property?, defaultValue?]`          | Delay execution      |
-
-In project TypeScript source, pass entity getters for BRICKS entities:
-
-```typescript
-run: ['brick_press', () => mainSubspace, () => bricks.bSubmitButton]
-run: ['wait_until_canvas_change', () => mainSubspace, () => canvases.cDone, 5000]
-run: ['assert_property', () => mainSubspace, () => data.dStep, 'done']
-```
-
-The compiler resolves these getters to the current generated IDs.
-
-### execute_action Params
-
-The `params` object in `execute_action` uses **runtime event property keys** from `event-props.ts`, NOT the action config `input` names from type definitions.
-
-```typescript
-// CORRECT — use runtime event property key
-run: ['execute_action', () => subspace0, bricks.bInput.id, 'BRICK_TEXT_INPUT_SET_TEXT',
-  { BRICK_TEXT_INPUT_TEXT: 'hello' }]
-
-// WRONG — action config input name doesn't work in automation
-run: ['execute_action', () => subspace0, bricks.bInput.id, 'BRICK_TEXT_INPUT_SET_TEXT',
-  { text: 'hello' }]
-```
-
-Reference `event-props.ts` for the correct runtime keys (e.g., `BRICK_TEXT_INPUT_TEXT`, `GENERATOR_MQTT_PAYLOAD`).
-
-### Prefer UI Interactions Over Direct Generator Calls
-
-For realistic E2E testing, prefer simulating user actions (set text input + press button) over calling generator actions directly:
-
-```typescript
-// GOOD — simulates real user behavior
-{ run: ['execute_action', () => sub, bricks.bInput.id, 'BRICK_TEXT_INPUT_SET_TEXT',
-    { BRICK_TEXT_INPUT_TEXT: 'hello' }] },
-{ run: ['brick_press', () => sub, () => bricks.bSendBtn] },
-{ run: ['wait_until_property_change', () => sub, () => data.dPayload, 'hello', 10000] },
-
-// AVOID — bypasses UI, doesn't test the full flow
-{ run: ['execute_action', () => sub, generators.gClient.id, 'GENERATOR_MQTT_PUBLISH',
-    { topic: 'test', payload: 'hello', qos: '0' }] },
-```
-
-## Recording Automations
-
-In BRICKS Editor Preview mode:
-
-1. Perform operations normally
-2. Open menu (right-bottom corner)
-3. Select "Record Events as Automation"
-4. Generated automation appears in Automations list
-
-## Running Automations
-
-### Manual Run
-
-`Menu` → `Automations` → Select automation → `Run`
-
-### On Launch
-
-`Bind Device` → `Select Automation` (only `launch` or `cron` types)
-
-### Scheduled (Cron)
-
-`Bind Device` → `Cron Automation` (allows multi-select)
-
-Use [crontab.guru](https://crontab.guru) to build cron expressions.
-
-## Screenshot Testing
-
-Visual regression testing with screenshot comparison:
-
-```typescript
-{
-  __typename: 'TestCase',
-  id: makeId('test_case'),
-  name: 'Match dashboard screenshot',
-  run: ['match_screenshot', 'dashboard-initial-state', 0.01, 3],
-  exit_on_failed: true,
-  commented: false,
-  pre_delay: 500, // Wait for UI to settle
-  post_delay: 0,
-  jump_cond: [],
-}
-```
-
-Screenshots can be stored:
-
-- Local file system
-- Media Flow workspace
-
-First run captures baseline. Use "Run with Update" to update baseline.
-
-## Module Support
-
-Automations work with Modules. Use Manual Run in Preview mode for module testing.
-
-## Important Notes
-
-- **Automation map key**: Always use `'AUTOMATION_MAP_DEFAULT'` as the automation map ID (not `makeId()`). The preview test runner reads from `automationMap['AUTOMATION_MAP_DEFAULT']?.map`.
-- **Valid makeId types**: Use `'test'` for AutomationTest, `'test_case'` for TestCase, `'test_var'` for TestVariable. Do NOT use `'automation_test'` or `'automation_test_map'`.
-- **Entity references in run arrays**: Use getter references (`() => subspace`, `() => bricks.bButton`, `() => data.dValue`) in TypeScript source so compile resolves fresh IDs.
-- **handler in execute_action**: Pass the entity's `.id` string (e.g., `bricks.bInput.id`), not a getter function.
-
-## Best Practices
-
-1. **Test culture**: Create automations for every significant flow
-2. **CI/CD integration**: Use `launch` automations for deployment validation
-3. **Incremental waits**: Use `wait_until_property_change` with appropriate timeouts
-4. **Visual testing**: Add screenshot comparisons for critical UI states
-5. **Cron monitoring**: Schedule health checks for production displays
-6. **Isolation**: Each automation should be independent and idempotent
-7. **UI-first testing**: Simulate real user interactions (text input, button press) rather than calling generators directly

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

@@ -1,245 +0,0 @@
-# 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