@fugood/bricks-project 2.23.0-beta.9 → 2.23.2

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

@@ -0,0 +1,153 @@
+# 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)](generator_LLM) - Local Large Language Model inference
+- [Speech-to-Text (GGML)](generator_SpeechInference) - Local Speech-to-Text inference
+
+## 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-project'
+
+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,
+    buttressEnabled: true,
+    buttressUrl: 'http://192.168.1.100:2080',
+    buttressFallbackType: 'use-local',
+    buttressStrategy: '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-project/rules/data-calculation.md

@@ -0,0 +1,208 @@
+# 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-project'
+
+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)
+  // code: await Bun.file(`${import.meta.dir}/format-price.sandbox.js`).text(),
+  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) |

package/skills/bricks-project/rules/local-sync.md

@@ -0,0 +1,129 @@
+# Local Sync
+
+Synchronize data between devices on a Local Area Network (LAN) without remote server storage. High synchronization rate for real-time multi-device experiences.
+
+## Features
+
+- **Update Data**: Sync Data Bank values across local devices
+- **Execute Data Calculation**: Trigger calculations on other devices
+- **No Remote Storage**: Direct device-to-device communication
+
+## Main / Minor Device Model
+
+| Role | Description |
+|------|-------------|
+| Main | Manages Data Bank if enabled, first device to start |
+| Minor | Follows main device, subsequent devices |
+
+### Role Determination
+
+1. First device to start becomes Main
+2. If simultaneous start: `Priority as Main Device` (0-9, set in Device Page) + random number determines Main
+
+## Configuration
+
+### Run Mode Options
+
+| Mode | Description |
+|------|-------------|
+| `all` | Run on all devices |
+| `main-only` | Only run on Main device |
+| `minor-only` | Only run on Minor devices |
+
+Apply run mode to:
+- Data properties
+- Generators
+- Data Calculations
+
+### Subspace Local Sync Settings
+
+```typescript
+const subspace: Subspace = {
+  __typename: 'Subspace',
+  id: 'main',
+  localSyncChangeCanvas: 'all', // 'all' | 'main-only' | 'minor-only' | 'none'
+  // ...
+}
+```
+
+### Data Local Sync
+
+```typescript
+import { makeId } from 'bricks-project'
+
+const data: Data = {
+  __typename: 'Data',
+  id: makeId('data'),
+  title: 'Shared Counter',
+  type: 'number',
+  value: 0,
+  localSyncUpdateMode: 'main-only', // 'main-only' | 'minor-only' | undefined (all)
+  events: {},
+}
+```
+
+### Generator Local Sync
+
+```typescript
+import { makeId } from 'bricks-project'
+
+const generator: GeneratorTimer = {
+  __typename: 'Generator',
+  templateKey: 'Timer',
+  id: makeId('generator'),
+  title: 'Sync Timer',
+  description: '',
+  localSyncRunMode: 'main-only', // Timer only runs on main device
+  property: {},
+  events: {},
+  switches: [],
+}
+```
+
+## Use Cases
+
+### Synchronized Displays
+Multiple screens showing coordinated content:
+- Main device controls timing/state
+- Minor devices follow state changes
+
+### Interactive Kiosks
+Touch on one device, update all:
+- User interacts with input device (Minor)
+- Main device processes and broadcasts result
+- All devices update simultaneously
+
+### Video Walls
+Coordinated multi-screen layouts:
+- Main device manages playback state
+- Minor devices sync position/frame
+
+## System Data
+
+Access local sync status via System Data:
+
+```typescript
+// Is current device the main device?
+systemData.isLocalSyncMainDevice // boolean
+```
+
+## Important Notes
+
+1. **Version Matching**: All devices must use same BRICKS Foundation minor version
+   - ✅ v2.11.0 matches v2.11.1
+   - ❌ v2.11.0 does NOT match v2.10.8
+
+2. **Network Requirements**:
+   - All devices on same LAN
+   - mDNS/Bonjour enabled
+   - Firewall allows local discovery
+
+3. **Startup Order**: Consider device startup sequence when Main role matters
+
+## Best Practices
+
+1. **Designate Main explicitly**: Set high `Priority as Main Device` on intended main
+2. **Idempotent logic**: Design for eventual consistency, not strict ordering
+3. **Minimal sync scope**: Only enable local sync for data that truly needs it
+4. **Test multi-device**: Validate behavior with actual device count
+5. **Handle disconnection**: Design for graceful degradation if devices disconnect

package/skills/bricks-project/rules/media-flow.md

@@ -0,0 +1,158 @@
+# Media Flow
+
+Centralized media asset management for BRICKS applications. Store, organize, and reference images, videos, and audio files.
+
+## Enable Media Workspace
+
+1. Visit `Media` tab in workspace page
+2. Enable media workspace for your workspace
+
+## Media Box
+
+Organize assets into boxes (folders). Each box can contain files of various types.
+
+### Generator Media Flow
+
+Use `Generator Media Flow` to:
+- Get file list from a box
+- Download files
+- Subscribe to box changes
+
+Quick setup: Create new Property with `As Media Resource file list?` option.
+
+```typescript
+import { makeId } from 'bricks-project'
+
+const mediaListGenerator: GeneratorMediaFlow = {
+  __typename: 'Generator',
+  templateKey: 'MediaFlow',
+  id: makeId('generator'),
+  title: 'Promo Images',
+  description: '',
+  property: {
+    boxId: 'promo-box-id',
+  },
+  outlets: {
+    files: () => promoFilesData, // Array of file objects
+  },
+  events: {},
+  switches: [],
+}
+```
+
+## Property Kinds for Media
+
+Link Data properties to Media Flow for asset selection:
+
+| Kind | Description |
+|------|-------------|
+| `media-resource-image` | Image asset selector |
+| `media-resource-video` | Video asset selector |
+| `media-resource-audio` | Audio asset selector |
+| `lottie-file-uri` | Lottie animation selector |
+
+```typescript
+import { makeId } from 'bricks-project'
+
+const backgroundImage: Data = {
+  __typename: 'Data',
+  id: makeId('data'),
+  title: 'Background Image',
+  type: 'string',
+  kind: { type: 'media-resource-image' },
+  value: '',
+  events: {},
+}
+```
+
+Assets with these kinds are **preloaded** during application launch.
+
+## Compatible Bricks & Generators
+
+### Bricks
+- **Brick Image**: Display images from Media Flow
+- **Brick Video**: Play videos from Media Flow
+- **Brick Lottie**: Render Lottie animations
+- **Brick Slideshow**: Cycle through Media Flow file list
+
+### Generators
+- **Generator Sound Player**: Play audio files
+- **Generator File Reader**: Read file contents
+
+## Slideshow with Media Flow
+
+Connect Generator Media Flow output to Brick Slideshow:
+
+```typescript
+import { makeId, linkData } from 'bricks-project'
+
+const slideshow: BrickSlideshow = {
+  __typename: 'Brick',
+  templateKey: 'Slideshow',
+  id: makeId('brick'),
+  title: 'Promo Slideshow',
+  description: '',
+  property: {
+    images: linkData(() => promoFilesData),
+    interval: 5000, // ms between slides
+    transition: 'fade',
+  },
+  events: {},
+  switches: [],
+}
+```
+
+## File Object Structure
+
+Files from Media Flow include:
+
+```typescript
+interface MediaFile {
+  id: string
+  name: string
+  url: string
+  thumbnailUrl?: string
+  mimeType: string
+  size: number
+  width?: number  // For images/videos
+  height?: number
+  duration?: number // For videos/audio
+  createdAt: string
+  updatedAt: string
+}
+```
+
+## Upload & Management
+
+### Via Editor
+1. Open Media tab in BRICKS Editor
+2. Select or create a box
+3. Drag & drop files or use upload button
+
+### Via CLI
+```bash
+bricks media boxes              # List media boxes
+bricks media box <box-id>       # Box details
+bricks media files <box-id>     # List files in box
+bricks media file <file-id>     # File details
+```
+
+> Note: CLI currently supports read-only operations. Upload is not yet supported.
+
+### Via API
+Use BRICKS API for programmatic upload and management.
+
+## Screenshot Storage
+
+Automation `Match Screenshot` can save screenshots to Media Flow workspace:
+- Baseline images stored in specified box
+- Easy visual comparison and management
+
+## Best Practices
+
+1. **Organize by purpose**: Create boxes for different content types (backgrounds, icons, videos)
+2. **Optimize assets**: Compress images/videos before upload
+3. **Preload critical assets**: Use `media-resource-*` kinds for important visuals
+4. **Slideshow performance**: Limit file count and resolution for smooth playback
+5. **Version control**: Use box naming conventions for content versions
+6. **CDN benefit**: Media Flow URLs are CDN-backed for fast delivery