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

package/skills/bricks-ctor/references/data-calculation.md

@@ -1,252 +0,0 @@
-# Data Calculation (JS Sandbox)
-
-Transform and compute Data Bank values using JavaScript scripts. Calcs are for **pure data transformation only** — see [Architecture Patterns](architecture-patterns.md) for the pattern selection guide.
-
-| 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) |
-
-## Authoring Contract
-
-```typescript
-import { makeId } from 'bricks-ctor'
-import { readFile } from 'node:fs/promises'
-
-const calculation: DataCalculationScript = {
-  __typename: 'DataCalculationScript',
-  id: makeId('property_bank_calc'),
-  title: 'Format Price',
-  description: 'Formats price with currency symbol',
-  note: '',
-  triggerMode: 'auto', // 'auto' (default) | 'manual'
-  enableAsync: false,
-  // Inline code for short scripts...
-  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 a file (preferred for longer scripts):
-  // 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 (see Multiple Outputs)
-  error: null, // or () => errorData for error handling
-}
-```
-
-### Field Rules (defaults and constraints)
-
-- `trigger` **defaults to `false` when omitted** — always set it explicitly. A calc whose inputs are all non-trigger never auto-runs.
-- `triggerMode` defaults to `'auto'` when omitted.
-- `output` receives the **whole return value**. `outputs` entries extract fields by key from a returned object — `key` is a lodash-get path, so deep paths like `'user.name'` work. `output`, `outputs`, and `error` can be combined.
-- `error` receives the error **message string** when the script throws. Both extraction steps run on every execution: a success overwrites the error Data, a failure overwrites the output Data(s) — don't expect stale values to persist.
-- **Auto mode rejects the same Data in both `inputs` and `output`/`outputs`/`error`** — compile fails with `Not allow duplicate set property id between inputs / outputs / output / error`. Manual mode allows the overlap (self-referential updates, see Recipes).
-- `.sandbox.js` files use an `export function main() { ... }` wrapper — compile unwraps it. Raw statements also work, but the wrapper keeps linters happy since script bodies use top-level `return`.
-
-## Trigger Modes
-
-| Mode | Description |
-|------|-------------|
-| `auto` | Run on every write to a `trigger: true` input (even if the value is unchanged) |
-| `manual` | Never auto-runs; only via `PROPERTY_BANK_COMMAND` action. Allows the same Data as both input and output |
-
-Use `manual` to prevent circular dependencies, for explicit control, or when an output must feed back into an input.
-
-## Triggering via PROPERTY_BANK_COMMAND
-
-`input` references a Data that is an input of the target calc — the system runs the calc(s) that data feeds into. It does NOT reference the DataCalculation itself.
-
-- **Manual calc**: ANY input works — `trigger` flags are ignored for manual-mode calcs.
-- **Auto calc**: only `trigger: true` inputs work; commanding a `trigger: false` input is a silent no-op.
-
-```typescript
-const triggerCalc: EventAction = {
-  handler: 'system',
-  action: {
-    __actionName: 'PROPERTY_BANK_COMMAND',
-    parent: 'System',
-    dataParams: [
-      { input: () => priceData }, // Reference to an input Data of the calc
-    ],
-  },
-}
-```
-
-- When the same chain **writes a calc input first** (e.g. `PROPERTY_BANK` setting `dLastButton`) then issues `PROPERTY_BANK_COMMAND`, set `waitAsync: true` on the write so the calc reads the new value rather than the pre-chain snapshot. See [Event Action Chains](architecture-patterns.md#event-action-chains-priority-2).
-- When a **later action reads the calc's outputs**, set `waitAsync: true` on the `PROPERTY_BANK_COMMAND` action itself — it awaits the full calc chain including output writes.
-- A dataParam's `value` acts as an execution gate: `{ input: () => d, value: false }` skips that trigger (combine with `mapping` for conditional runs).
-
-## One trigger source per result panel
-
-A panel that shows the result of an async action (Generator HTTP/LLM response, request telemetry) reads from a calc whose **trigger should come from a single source**: either the live async outlet, or a completion marker the action chain writes — not both.
-
-- **Outlet-triggered** (`{ data: () => dResponse, trigger: true }`): the calc reruns as outlets land. Use when each outlet is only written once its value is final.
-- **Marker-triggered**: run the generator with `waitAsync: true`, then write a `done` Data the calc triggers on. Use when several outlets settle separately and the panel must wait for all of them.
-
-Wiring both at once — triggering on the live outlet _and_ gating on a separately-written marker — lets the calc run before the outlets have settled (it renders `undefined`/stale) while the marker path masks it intermittently. A panel that updates "sometimes" usually has two competing triggers: pick one, and order it with `waitAsync` so the trigger fires after the values it reads are written.
-
-Scope the panel's calc to the **single value it derives** (the formatted display string), and write sibling status labels — running/done, progress, selected route — imperatively in the event chain with `PROPERTY_BANK`. A calc rewrites _every_ one of its outputs on each run, so a return that omits a key writes `undefined` to that output Data (see [Field Rules](#field-rules-defaults-and-constraints)): folding status labels into a multi-output result calc resets them to `undefined` on any run that returns only the derived value. If a calc genuinely must drive several outputs, return all of their keys every run.
-
-## Script Sandbox
-
-Scripts run in `use strict` mode as a function body — top-level `return` returns the calc result. No `fetch`, `XMLHttpRequest`, or `require` in any mode: I/O belongs to Generators.
-
-### Built-in Globals
-
-| Global | Description |
-|--------|-------------|
-| `inputs` | Object with input values (keyed by input `key`) |
-| `console` | `{ log, error, warn, info }` — output is only visible in DevTools debug sessions; production is a no-op |
-| `Platform` | `{ OS, isTV, isPad, isVision, isElectron }` |
-| `TextEncoder`, `TextDecoder` | Text encoding/decoding |
-| `Buffer` | Node.js Buffer (without `allocUnsafe`/`allocUnsafeSlow`) |
-| `btoa`, `atob` | Base64 encoding/decoding |
-
-### Async Mode
-
-Sync mode (default) has **no `Promise`, timers, or `await`**. Enable `enableAsync: true` to unlock:
-
-- `Promise`, `setTimeout`, `setInterval`, `setImmediate`, `clearTimeout`, `clearInterval`, `clearImmediate`, `requestAnimationFrame`
-- Full lodash (sync mode omits `debounce`, `delay`, `defer`)
-- `await` at the top level of the script
-
-```typescript
-code: `
-  const result = await new Promise((resolve) => {
-    setTimeout(() => resolve(inputs.value * 2), 100)
-  })
-  return result
-`,
-enableAsync: true,
-```
-
-### Runtime Environment
-
-| Platform | Engine |
-|----------|--------|
-| Android | Hermes engine sandbox |
-| iOS | JavaScriptCore sandbox |
-| Electron desktop | Web Worker (V8) |
-| Web preview / Simulator | Web Worker (V8) |
-
-Simulator (Path 1) runs scripts on V8 while devices run Hermes/JSC — engine-sensitive code (date parsing, Intl, regex features) can pass in the Simulator and fail on device.
-
-### Available Libraries
-
-All exposed as globals. No network/file-download capability in any of them.
-
-| Global | Library | Notes |
-|--------|---------|-------|
-| `_`, `lodash` | lodash | Sync mode omits `debounce`/`delay`/`defer` |
-| `voca` | voca | String manipulation |
-| `invariant` | invariant | Assertions |
-| `json5` | json5 | JSON5 parsing |
-| `qs` | qs | Query string parsing |
-| `url` | node-url | URL parsing |
-| `bytes` | bytes | Byte parsing/formatting |
-| `ms` | ms | Millisecond conversion |
-| `base45` | base45 | Base45 encoding |
-| `iconv` | iconv-lite | Character encoding |
-| `math`, `mathjs` | mathjs | Math library |
-| `chroma` | chroma-js | Color manipulation |
-| `moment` | moment | Date/time; auto parseFormat for string args |
-| `nanoid` | nanoid | Unique ID generation |
-| `md5` | md5 | MD5 hashing |
-| `crypto` | crypto-browserify | Crypto functions |
-| `kjurJWS` | jsrsasign | JWT/JWS signing (`KJUR.jws.JWS`) |
-| `coseVerify` | cose-js | COSE verification (sync) |
-| `fflate` | fflate | `{ zlibSync, unzlibSync, gzipSync, gunzipSync, compressSync, decompressSync, strFromU8 }` |
-| `cbor` | cbor | `{ encode, decode, decodeFirstSync, decodeAllSync, addSemanticType }` |
-| `fs` | (in-repo fs-compat) | File system; no download/upload methods |
-| `parseDocument` | officeparser (in-repo fork) | Office document parsing (async) |
-| `TurndownService` | turndown | HTML to Markdown |
-| `OpenCC` | opencc-js | Chinese conversion `{ Converter, ConverterFactory, CustomConverter, Locale }` |
-| `TOON` | @toon-format/toon | TOON format parsing |
-
-## Recipes
-
-### Multiple Outputs
-
-Return an object; each `outputs` entry extracts its `key`:
-
-```typescript
-outputs: [
-  { key: 'total', data: () => totalData },
-  { key: 'tax', data: () => taxData },
-  { key: 'subtotal', data: () => subtotalData },
-],
-output: null,
-error: null,
-code: `
-  const subtotal = inputs.price * inputs.quantity
-  const tax = subtotal * 0.1
-  const total = subtotal + tax
-  return { total, tax, subtotal }
-`,
-```
-
-### Manual Self-Referential Update
-
-When an update is too complex for `PROPERTY_BANK_EXPRESSION` and must read its own previous value — manual mode allows the same Data as input and output:
-
-```typescript
-const appendHistory: DataCalculationScript = {
-  __typename: 'DataCalculationScript',
-  id: makeId('property_bank_calc'),
-  title: 'Append History Entry',
-  triggerMode: 'manual',
-  enableAsync: false,
-  code: `
-    const history = Array.isArray(inputs.history) ? inputs.history : []
-    return [...history, { entry: inputs.entry, at: moment().toISOString() }].slice(-50)
-  `,
-  inputs: [
-    { key: 'history', data: () => historyData, trigger: true },
-    { key: 'entry', data: () => entryData, trigger: true },
-  ],
-  output: () => historyData, // same Data as input — manual mode only
-  outputs: [],
-  error: null,
-}
-// Run it from an event chain: PROPERTY_BANK writes entryData (waitAsync: true),
-// then PROPERTY_BANK_COMMAND with input: () => entryData.
-```
-
-## Failure Modes
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| Calc never auto-runs | `trigger` omitted on inputs (defaults to `false`) | Set `trigger: true` explicitly |
-| `PROPERTY_BANK_COMMAND` does nothing | Auto calc + `trigger: false` input, or `input` doesn't reference an input Data of the calc | Command a `trigger: true` input (auto) or any input (manual) |
-| Compile error `Not allow duplicate set property id...` | Auto mode with same Data as input and output | Use `triggerMode: 'manual'`, or split into separate Data |
-| Calc reads stale value written earlier in the same chain | Missing `waitAsync: true` on the preceding write | Set `waitAsync: true` on the write action |
-| Result/telemetry panel shows `undefined` or stale data intermittently | Calc triggered by two sources at once (live outlet + a separately-written marker) | Trigger from one source — see [One trigger source per result panel](#one-trigger-source-per-result-panel) |
-| Sibling status Data (selected/progress) resets to `undefined` after a calc runs | Multi-output result calc whose return omitted those keys on that run | Scope the calc to one output and write status labels imperatively, or return every output key each run — see [One trigger source per result panel](#one-trigger-source-per-result-panel) |
-| Works in Simulator, fails on device | V8 vs Hermes/JSC engine difference | Verify on device (Path 2); avoid engine-sensitive parsing |
-| `console.log` shows nothing | Console only emits during DevTools debug sessions | Attach DevTools, or write debug values to an output Data |
-| `Promise`/`setTimeout` undefined, or `Async mode is required` error | `enableAsync: false` | Set `enableAsync: true` |
-
-## 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 (auto calcs re-run on every write, even unchanged)
-
-## 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. Symptoms: if/else on "what happens next", mirror `dFooResult` outputs that copy back to `dFoo` via `valueChange`, or a `dLastInput` field set-then-cleared to force an auto calc. See the "user-driven state machine" recipe in [Architecture Patterns](architecture-patterns.md).

package/skills/bricks-ctor/references/local-sync.md

@@ -1,129 +0,0 @@
-# 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-ctor/references/media-flow.md

@@ -1,165 +0,0 @@
-# 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',
-    passcode: 'box-read-only-passcode',
-  },
-  outlets: {
-    files: () => promoFilesData, // Array of file objects
-  },
-  events: {},
-  switches: [],
-}
-```
-
-When hand-writing `GENERATOR_MEDIA_FLOW`, do not use a bare `boxId`. The editor
-flow creates the required authorization, but manual config must include either
-`property.passcode` from a Media Box passcode or `property.accessToken`.
-Without one, devices cannot read the box and the generator will report an
-authorization error.
-
-## 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