@fugood/bricks-ctor 2.25.0-beta.9 → 2.25.0

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

@@ -1,221 +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      |
-
-### 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'`.
-- **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/rules/buttress.md

@@ -1,156 +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 Buttress settings:
-
-| Setting | Description |
-|---------|-------------|
-| `Enabled` | Toggle Buttress offloading |
-| `URL` | Buttress server URL (e.g., `http://192.168.1.100:2080`) |
-| `Fallback Type` | Action if Buttress unavailable: `use-local` or `no-op` |
-| `Strategy` | Execution preference |
-
-### 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 Example
-
-```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,
-      url: 'http://192.168.1.100:2080',
-      fallbackType: 'use-local',
-      strategy: 'prefer-best',
-    },
-  },
-  events: {},
-  switches: [],
-}
-```
-
-## 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 |
-
-## 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/rules/data-calculation.md

@@ -1,209 +0,0 @@
-# Data Calculation (JS Sandbox)
-
-Transform and compute Data Bank values using JavaScript scripts.
-
-## DataCalculationScript
-
-JavaScript code executed in a sandbox with access to inputs and outputs.
-
-```typescript
-import { makeId } from 'bricks-ctor'
-
-const calculation: DataCalculationScript = {
-  __typename: 'DataCalculationScript',
-  id: makeId('property_bank_calc'),
-  title: 'Format Price',
-  description: 'Formats price with currency symbol',
-  note: '',
-  triggerMode: 'auto', // 'auto' | 'manual'
-  enableAsync: false,
-  // Inline code
-  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 file (preferred for longer scripts)
-  // import { readFile } from 'node:fs/promises'
-  // 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
-  error: null, // or () => errorData for error handling
-}
-```
-
-## Trigger Modes
-
-| Mode | Description |
-|------|-------------|
-| `auto` | Run when input values change (with trigger: true) |
-| `manual` | Only run via `PROPERTY_BANK_COMMAND` action |
-
-Use `manual` to prevent circular dependencies or for explicit control.
-
-## Script Sandbox Features
-
-Scripts run in `use strict` mode with a sandboxed set of globals and libraries.
-
-### Built-in Globals
-
-| Global | Description |
-|--------|-------------|
-| `inputs` | Object with input values |
-| `console` | `{ log, error, warn, info }` for debugging |
-| `Platform` | `{ OS, isTV, isPad, isVision, isElectron }` |
-| `TextEncoder`, `TextDecoder` | Text encoding/decoding |
-| `Buffer` | Node.js Buffer (without `allocUnsafe`) |
-| `btoa`, `atob` | Base64 encoding/decoding |
-
-### Available Libraries
-
-**Utility**
-| Library | Global | Description |
-|---------|--------|-------------|
-| [lodash](https://lodash.com) | `_`, `lodash` | Utility (sync: no debounce/delay/defer) |
-| [voca](https://vocajs.com) | `voca` | String manipulation |
-| [invariant](https://github.com/zertosh/invariant) | `invariant` | Assertions |
-
-**Data & Encoding**
-| Library | Global | Description |
-|---------|--------|-------------|
-| [json5](https://github.com/json5/json5) | `json5` | JSON5 parsing |
-| [qs](https://github.com/ljharb/qs) | `qs` | Query string parsing |
-| [url](https://github.com/defunctzombie/node-url) | `url` | URL parsing |
-| [bytes](https://github.com/visionmedia/bytes.js) | `bytes` | Byte parsing/formatting |
-| [ms](https://github.com/vercel/ms) | `ms` | Millisecond conversion |
-| [base45](https://github.com/irony/base45) | `base45` | Base45 encoding |
-| [iconv-lite](https://github.com/ashtuchkin/iconv-lite) | `iconv` | Character encoding |
-
-**Math & Color**
-| Library | Global | Description |
-|---------|--------|-------------|
-| [mathjs](https://mathjs.org) | `math`, `mathjs` | Math library |
-| [chroma-js](https://gka.github.io/chroma.js) | `chroma` | Color manipulation |
-
-**Date/Time**
-| Library | Global | Description |
-|---------|--------|-------------|
-| [moment](https://momentjs.com) | `moment` | Date/time (auto parseFormat) |
-
-**ID & Hash**
-| Library | Global | Description |
-|---------|--------|-------------|
-| [nanoid](https://github.com/ai/nanoid) | `nanoid` | Unique ID generation |
-| [md5](https://github.com/pvorb/node-md5) | `md5` | MD5 hashing |
-
-**Crypto**
-| Library | Global | Description |
-|---------|--------|-------------|
-| [crypto-browserify](https://github.com/crypto-browserify/crypto-browserify) | `crypto` | Crypto functions |
-| [jsrsasign](https://github.com/kjur/jsrsasign) | `kjurJWS` | JWT/JWS signing |
-| [cose-js](https://github.com/erdtman/COSE-JS) | `coseVerify` | COSE verification (sync) |
-
-**Compression**
-| Library | Global | Description |
-|---------|--------|-------------|
-| [fflate](https://github.com/101arrowz/fflate) | `fflate` | `{ zlibSync, unzlibSync, gzipSync, gunzipSync, compressSync, decompressSync, strFromU8 }` |
-| [cbor](https://github.com/hildjj/node-cbor) | `cbor` | `{ encode, decode, decodeFirstSync, decodeAllSync }` |
-
-**File & Document**
-| Library | Global | Description |
-|---------|--------|-------------|
-| fs | `fs` | File system (limited, no download/upload) |
-| [officeparser](https://github.com/nicktang) | `parseDocument` | Office document parsing (async) |
-| [turndown](https://github.com/mixmark-io/turndown) | `TurndownService` | HTML to Markdown |
-| [opencc-js](https://github.com/nk2028/opencc-js) | `OpenCC` | Chinese conversion `{ Converter, ConverterFactory, CustomConverter, Locale }` |
-| [toon-format](https://github.com/nicktang) | `TOON` | TOON format parsing |
-
-### Runtime Environment
-
-| Platform | Engine |
-|----------|--------|
-| Android | Hermes engine sandbox |
-| iOS | JavaScriptCore sandbox |
-
-### Async Mode
-
-Enable `enableAsync: true` to unlock additional capabilities:
-
-**Additional async globals:**
-- `Promise`, `setTimeout`, `setInterval`, `setImmediate`
-- `clearTimeout`, `clearInterval`, `clearImmediate`
-- `requestAnimationFrame`
-- Full lodash (including `debounce`, `delay`, `defer`)
-
-```typescript
-code: `
-  const result = await new Promise((resolve) => {
-    setTimeout(() => resolve(inputs.value * 2), 100)
-  })
-  return result
-`,
-enableAsync: true,
-```
-
-### Multiple Outputs
-
-```typescript
-outputs: [
-  { key: 'total', data: () => totalData },
-  { key: 'tax', data: () => taxData },
-  { key: 'subtotal', data: () => subtotalData },
-],
-code: `
-  const subtotal = inputs.price * inputs.quantity
-  const tax = subtotal * 0.1
-  const total = subtotal + tax
-  return { total, tax, subtotal }
-`,
-```
-
-## Triggering Manually
-
-Use `PROPERTY_BANK_COMMAND` system action to trigger a manual calculation:
-
-```typescript
-const triggerCalc: EventAction = {
-  handler: 'system',
-  action: {
-    __actionName: 'PROPERTY_BANK_COMMAND',
-    parent: 'System',
-    dataParams: [
-      { input: () => computeTotalCalc }, // Reference to DataCalculation
-    ],
-  },
-}
-```
-
-## 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
-
-## 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, not here.
-
-**Symptom**: Script has if/else branches deciding "what happens next" or tracks "current step".
-
-### Quick reference
-
-| 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) |