@fugood/bricks-ctor 2.24.0-beta.40

package/skills/bricks-project/rules/animation.md

@@ -0,0 +1,159 @@
+# Animation
+
+BRICKS Animation system for animating brick transforms and opacity. Animations are defined at the Subspace level and triggered via events or Dynamic Animation actions.
+
+## Animation Types
+
+### Timing Animation
+Standard duration-based animation with easing.
+
+```typescript
+import { makeId } from 'bricks-ctor'
+
+const fadeIn: AnimationDef = {
+  __typename: 'Animation',
+  id: makeId('animation'),
+  title: 'Fade In',
+  runType: 'once', // 'once' | 'loop'
+  property: 'opacity',
+  config: {
+    __type: 'AnimationTimingConfig',
+    toValue: 1,
+    duration: 300, // ms
+    easing: 'easeOutCubic',
+    delay: 0, // ms
+    isInteraction: true,
+  },
+}
+```
+
+### Spring Animation
+Physics-based spring animation.
+
+```typescript
+const bounce: AnimationDef = {
+  __typename: 'Animation',
+  id: makeId('animation'),
+  title: 'Bounce In',
+  property: 'transform.scale',
+  config: {
+    __type: 'AnimationSpringConfig',
+    toValue: 1,
+    friction: 7,
+    tension: 40,
+    speed: 12,
+    bounciness: 8,
+  },
+}
+```
+
+### Decay Animation
+Velocity-based deceleration animation.
+
+```typescript
+const slideOut: AnimationDef = {
+  __typename: 'Animation',
+  id: makeId('animation'),
+  title: 'Slide Out',
+  property: 'transform.translateX',
+  config: {
+    __type: 'AnimationDecayConfig',
+    toValue: 500,
+    velocity: 0.5,
+    deceleration: 0.997,
+    isInteraction: true,
+  },
+}
+```
+
+## Animatable Properties
+
+| Property | Description |
+|----------|-------------|
+| `transform.translateX` | Horizontal position offset |
+| `transform.translateY` | Vertical position offset |
+| `transform.scale` | Uniform scale |
+| `transform.scaleX` | Horizontal scale |
+| `transform.scaleY` | Vertical scale |
+| `transform.rotate` | Rotation (degrees) |
+| `transform.rotateX` | X-axis rotation |
+| `transform.rotateY` | Y-axis rotation |
+| `opacity` | Transparency (0-1) |
+
+## Easing Functions
+
+Standard easing from [easings.net](https://easings.net):
+- `easeInSine`, `easeOutSine`, `easeInOutSine`
+- `easeInQuad`, `easeOutQuad`, `easeInOutQuad`
+- `easeInCubic`, `easeOutCubic`, `easeInOutCubic`
+- `easeInQuart`, `easeOutQuart`, `easeInOutQuart`
+- `easeInQuint`, `easeOutQuint`, `easeInOutQuint`
+- `easeInExpo`, `easeOutExpo`, `easeInOutExpo`
+- `easeInCirc`, `easeOutCirc`, `easeInOutCirc`
+- `easeInBack`, `easeOutBack`, `easeInOutBack`
+- `easeInElastic`, `easeOutElastic`, `easeInOutElastic`
+- `easeInBounce`, `easeOutBounce`, `easeInOutBounce`
+- Custom: `'cubic-bezier(x1, y1, x2, y2)'`
+
+## Composed Animations
+
+Combine multiple animations in parallel or sequence.
+
+```typescript
+const enterAnimation: AnimationComposeDef = {
+  __typename: 'AnimationCompose',
+  id: makeId('animation'),
+  title: 'Enter Animation',
+  runType: 'once',
+  composeType: 'parallel', // 'parallel' | 'sequence'
+  items: [
+    () => fadeIn,
+    () => scaleUp,
+  ],
+}
+```
+
+## Brick Animation Events
+
+Bricks support automatic animation binding:
+
+```typescript
+// In brick definition
+animations: {
+  showStart: () => fadeInAnimation,  // On brick first render
+  standby: () => standbyAnimation,   // After standby transition
+  breatheStart: () => pulseAnimation, // Breathing effect (looping)
+}
+```
+
+## Dynamic Animation (Runtime)
+
+Trigger animations programmatically via System Action:
+
+```typescript
+const runAnimation: EventAction = {
+  handler: 'system',
+  action: {
+    __actionName: 'DYNAMIC_ANIMATION',
+    parent: 'System',
+    params: [
+      { input: 'brickId', value: () => targetBrick },
+      { input: 'animationId', value: () => pulseAnimation },
+      { input: 'runType', value: 'once' }, // 'once' | 'loop'
+      { input: 'resetInitialValue', value: false },
+    ],
+  },
+}
+```
+
+Related actions:
+- `DYNAMIC_ANIMATION_RESET` - Reset animation state
+- `DYNAMIC_ANIMATION_STOP` - Stop running animation
+
+## Best Practices
+
+1. **Performance**: Keep animations simple, prefer `opacity` and `transform` over layout changes
+2. **Timing**: Use `easeOut` for enter animations, `easeIn` for exit
+3. **Spring animations**: Good for natural, bouncy UI elements
+4. **Looping**: Use `runType: 'loop'` for attention-grabbing elements
+5. **Composition**: Use `sequence` for staged reveals, `parallel` for coordinated effects

package/skills/bricks-project/rules/architecture-patterns.md

@@ -0,0 +1,69 @@
+# 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
+
+### 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
+- **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.

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

@@ -0,0 +1,221 @@
+# 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-project/rules/buttress.md

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