@fugood/bricks-ctor 2.24.0-beta.40

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-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)
+  // 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-ctor'
+
+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-ctor'
+
+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-ctor'
+
+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-ctor'
+
+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-ctor'
+
+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

package/skills/bricks-project/rules/remote-data-bank.md

@@ -0,0 +1,196 @@
+# Remote Data Bank
+
+Cloud-synchronized Data Bank for real-time data sharing across devices and external API access.
+
+## Remote Update Types
+
+The `remoteUpdate` field configures cloud synchronization:
+
+```typescript
+remoteUpdate?:
+  | { type: 'auto' }           // Sync across all devices
+  | { type: 'device-specific' } // Isolated per device
+  | { type: 'global-data', id: string } // Cross-application global data
+```
+
+### Auto Sync
+
+Sync across all devices using the same application.
+
+```typescript
+import { makeId } from 'bricks-ctor'
+
+const data: Data = {
+  __typename: 'Data',
+  id: makeId('data'),
+  title: 'Announcement',
+  type: 'string',
+  value: '',
+  remoteUpdate: { type: 'auto' },
+  events: {},
+}
+```
+
+### Global Data
+
+Share data across different applications. Must create Global Data first on BANK page.
+
+```typescript
+import { makeId } from 'bricks-ctor'
+
+const data: Data = {
+  __typename: 'Data',
+  id: makeId('data'),
+  title: 'Global Config',
+  type: 'object',
+  value: {},
+  remoteUpdate: { type: 'global-data', id: 'workspace-global-config-id' },
+  events: {},
+}
+```
+
+### Device Specific
+
+Isolate data per device while still allowing web page control.
+
+```typescript
+import { makeId } from 'bricks-ctor'
+
+const data: Data = {
+  __typename: 'Data',
+  id: makeId('data'),
+  title: 'Device Message',
+  type: 'string',
+  value: '',
+  remoteUpdate: { type: 'device-specific' },
+  events: {},
+}
+```
+
+Use case: Control individual displays from a shared web interface without affecting other devices.
+
+## External Access
+
+### Web Update Page
+
+Generate a web page for non-technical users to update data:
+
+1. Visit BANK page
+2. Click `Manage Keys`
+3. Select `Generate Key used by Update Page`
+4. Share the generated link
+
+The page has independent permissions and can be shared with content managers.
+
+### API Access
+
+Programmatic data updates via REST API.
+
+**Setup:**
+1. Visit BANK page → Manage Keys
+2. Create API key with appropriate permissions
+3. Use key in API requests
+
+**Example API Usage:**
+
+```bash
+# Update a property
+curl -X POST https://api.bricks.tools/v1/bank/update \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "applicationId": "app-id",
+    "propertyId": "announcement",
+    "value": "New announcement text"
+  }'
+
+# Get property value
+curl https://api.bricks.tools/v1/bank/get \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -G \
+  -d "applicationId=app-id" \
+  -d "propertyId=announcement"
+```
+
+## Data Routing
+
+Cross-subspace data sharing with access control.
+
+```typescript
+const routedData: Data = {
+  __typename: 'Data',
+  id: 'shared-state',
+  type: 'object',
+  routing: 'read-only', // 'read-only' | default (read-write)
+  // When read-only: only accepts changes from same subspace
+  // Default: accepts changes from any subspace
+}
+```
+
+## Use Cases
+
+### Digital Signage Content Management
+
+```typescript
+import { makeId } from 'bricks-ctor'
+
+// Remote-updated announcement
+const announcement: Data = {
+  __typename: 'Data',
+  id: makeId('data'),
+  title: 'Announcement',
+  type: 'object',
+  value: { title: '', body: '', enabled: false },
+  remoteUpdate: { type: 'auto' },
+  events: {},
+}
+```
+
+Operator updates content via web page → All displays update in real-time.
+
+### Multi-Location Coordination
+
+```typescript
+import { makeId } from 'bricks-ctor'
+
+// Global data shared across locations
+const globalConfig: Data = {
+  __typename: 'Data',
+  id: makeId('data'),
+  title: 'Brand Config',
+  type: 'object',
+  value: {},
+  remoteUpdate: { type: 'global-data', id: 'brand-config-global' },
+  events: {},
+}
+```
+
+Update once → All locations receive update.
+
+### Per-Device Customization
+
+```typescript
+import { makeId } from 'bricks-ctor'
+
+// Device-specific greeting
+const deviceGreeting: Data = {
+  __typename: 'Data',
+  id: makeId('data'),
+  title: 'Greeting',
+  type: 'string',
+  value: '',
+  remoteUpdate: { type: 'device-specific' },
+  events: {},
+}
+```
+
+Each display shows different greeting, controlled from single dashboard.
+
+## Best Practices
+
+1. **Minimize remote data**: Only enable for data that truly needs cloud sync
+2. **Use device-specific wisely**: Good for personalization, not for shared state
+3. **API key security**: Use scoped keys with minimal permissions
+4. **Offline resilience**: Design for temporary disconnection
+5. **Batch updates**: Group related changes to reduce API calls
+6. **Global data governance**: Establish clear ownership for global data keys