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

package/utils/event-props.ts

@@ -16,6 +16,13 @@ export const templateEventPropsMap = {
   Video: {
     nextVideo: { BRICK_VIDEO_NEXT_INDEX: 'number' },
     onProgress: { BRICK_VIDEO_CURRENT_TIME: 'number', BRICK_VIDEO_PLAYABLE_DURATION: 'number' },
+    subtitleCueEnter: {
+      BRICK_VIDEO_SUBTITLE_TEXT: 'string',
+      BRICK_VIDEO_SUBTITLE_INDEX: 'number',
+      BRICK_VIDEO_SUBTITLE_START: 'number',
+      BRICK_VIDEO_SUBTITLE_END: 'number',
+    },
+    subtitleCueExit: { BRICK_VIDEO_SUBTITLE_TEXT: 'string', BRICK_VIDEO_SUBTITLE_INDEX: 'number' },
   },
   VideoStreaming: {},
   Qrcode: {},
@@ -142,10 +149,29 @@ export const templateEventPropsMap = {
     },
   },
   Sketch: {
-    onStrokeEnd: { BRICK_SKETCH_STROKE_COUNT: 'number' },
+    onStrokeEnd: { BRICK_SKETCH_STROKE_COUNT: 'number', BRICK_SKETCH_STATE: '{}' },
+    onClear: { BRICK_SKETCH_STATE: '{}' },
+    onStateChange: { BRICK_SKETCH_STATE: '{}' },
     onToolChange: { BRICK_SKETCH_TOOL: 'string' },
     onExportImage: { BRICK_SKETCH_IMAGE_URI: 'string' },
   },
+  Scene3D: {
+    onLoad: { BRICK_SCENE_3D_OBJECT_ID: 'string', BRICK_SCENE_3D_DURATION_MS: 'number' },
+    onLoadError: { BRICK_SCENE_3D_OBJECT_ID: 'string', BRICK_SCENE_3D_ERROR: 'string' },
+    onObjectClick: {
+      BRICK_SCENE_3D_OBJECT_ID: 'string',
+      BRICK_SCENE_3D_HIT_POINT: '{ x?: number y?: number z?: number }',
+      BRICK_SCENE_3D_HIT_DISTANCE: 'number',
+    },
+    onObjectHover: { BRICK_SCENE_3D_OBJECT_ID: 'string', BRICK_SCENE_3D_HOVER_ENTERED: 'boolean' },
+    onAnimationEnd: { BRICK_SCENE_3D_OBJECT_ID: 'string', BRICK_SCENE_3D_ANIMATION_NAME: 'string' },
+    onFrame: {
+      BRICK_SCENE_3D_FRAME_TIME: 'number',
+      BRICK_SCENE_3D_FRAME_DT: 'number',
+      BRICK_SCENE_3D_FPS: 'number',
+    },
+    onScriptError: { BRICK_SCENE_3D_ERROR: 'string', BRICK_SCENE_3D_PHASE: 'string' },
+  },
   Tick: {
     ticking: { GENERATOR_TICK_COUNTDOWN: 'number', GENERATOR_TICK_VALUE: 'any' },
     completed: { GENERATOR_TICK_COUNTDOWN: 'number', GENERATOR_TICK_VALUE: 'any' },

package/utils/id.ts

@@ -1,80 +1,133 @@
 import { v4 as uuid } from 'uuid'
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
 
 let count = 0
 
-// Used for snapshot mode
-const countUUID = () => {
-  const current = count
-  count += 1
-  return `00000000-0000-0000-0000-${current.toString().padStart(12, '0')}`
+type IdType =
+  | 'animation'
+  | 'brick'
+  | 'canvas'
+  | 'generator'
+  | 'data'
+  | 'switch'
+  | 'property_bank_command'
+  | 'property_bank_calc'
+  | 'dynamic-brick'
+  | 'automation_map'
+  | 'test'
+  | 'test_case'
+  | 'test_var'
+  | 'subspace'
+
+type IdOptions = {
+  snapshotMode?: boolean
 }
 
-// Make a random id if not want to use fixed id
-export const makeId = (
-  type:
-    | 'animation'
-    | 'brick'
-    | 'canvas'
-    | 'generator'
-    | 'data'
-    | 'switch'
-    | 'property_bank_command'
-    | 'property_bank_calc'
-    | 'dynamic-brick'
-    | 'automation_map'
-    | 'test'
-    | 'test_case'
-    | 'test_var'
-    | 'subspace',
-  opts?: {
-    snapshotMode?: boolean
-  },
-) => {
-  if (type === 'subspace') {
-    throw new Error('Currently subspace is not supported for ID generation, please use a fixed ID')
+const APPLICATION_ID_FALLBACK = 'unknown-application'
+
+const usedStableAliases = new Set<string>()
+let applicationIdCache: { cwd: string; id: string } | null = null
+
+const readApplicationId = () => {
+  const cwd = process.cwd()
+  if (applicationIdCache?.cwd === cwd) return applicationIdCache.id
+
+  let id = APPLICATION_ID_FALLBACK
+  try {
+    const app = JSON.parse(readFileSync(join(cwd, 'application.json'), 'utf8'))
+    if (typeof app.id === 'string' && app.id) id = app.id
+  } catch {
+    // `makeId` is also used from tests and utilities outside project roots.
+  }
+
+  applicationIdCache = { cwd, id }
+  return id
+}
+
+const hashToRandomBytes = (parts: string[]) => {
+  const hash = createHash('sha256').update(JSON.stringify(parts)).digest()
+  return new Uint8Array(hash.subarray(0, 16))
+}
+
+const makeStableUuid = (type: string, alias?: string) => {
+  const applicationId = readApplicationId()
+  const seed = alias ?? String(count)
+  if (alias === undefined) count += 1
+
+  if (alias !== undefined) {
+    const aliasKey = JSON.stringify([applicationId, type, alias])
+    if (usedStableAliases.has(aliasKey)) {
+      throw new Error(`Duplicate makeId alias '${alias}' for type '${type}'`)
+    }
+    usedStableAliases.add(aliasKey)
   }
-  let prefix = ''
+
+  return uuid({
+    random: hashToRandomBytes([applicationId, type, seed]),
+  })
+}
+
+const idPrefix = (type: IdType): string => {
   switch (type) {
     case 'animation':
-      prefix = 'ANIMATION_'
-      break
+      return 'ANIMATION_'
     case 'brick':
-      prefix = 'BRICK_'
-      break
+      return 'BRICK_'
     case 'dynamic-brick':
-      prefix = 'DYNAMIC_BRICK_'
-      break
+      return 'DYNAMIC_BRICK_'
     case 'canvas':
-      prefix = 'CANVAS_'
-      break
+      return 'CANVAS_'
     case 'generator':
-      prefix = 'GENERATOR_'
-      break
+      return 'GENERATOR_'
     case 'data':
-      prefix = 'PROPERTY_BANK_DATA_NODE_'
-      break
+      return 'PROPERTY_BANK_DATA_NODE_'
     case 'switch':
-      prefix = 'BRICK_STATE_GROUP_'
-      break
+      return 'BRICK_STATE_GROUP_'
     case 'property_bank_command':
-      prefix = 'PROPERTY_BANK_COMMAND_NODE_'
-      break
+      return 'PROPERTY_BANK_COMMAND_NODE_'
     case 'property_bank_calc':
-      prefix = 'PROPERTY_BANK_COMMAND_MAP_'
-      break
+      return 'PROPERTY_BANK_COMMAND_MAP_'
     case 'automation_map':
-      prefix = 'AUTOMATION_MAP_'
-      break
+      return 'AUTOMATION_MAP_'
     case 'test':
-      prefix = 'TEST_'
-      break
+      return 'TEST_'
     case 'test_case':
-      prefix = 'TEST_CASE_'
-      break
+      return 'TEST_CASE_'
     case 'test_var':
-      prefix = 'TEST_VAR_'
-      break
+      return 'TEST_VAR_'
     default:
+      return ''
+  }
+}
+
+// Make stable ids by default; explicit snapshotMode: false preserves the random escape hatch.
+export const makeId = (type: IdType, aliasOrOpts?: string | IdOptions, opts?: IdOptions) => {
+  if (type === 'subspace') {
+    throw new Error('Currently subspace is not supported for ID generation, please use a fixed ID')
+  }
+
+  const alias = typeof aliasOrOpts === 'string' ? aliasOrOpts : undefined
+  const options = typeof aliasOrOpts === 'string' ? opts : (aliasOrOpts ?? opts)
+
+  const useCountFallback = aliasOrOpts === undefined && opts === undefined
+  const id =
+    alias !== undefined || options?.snapshotMode || useCountFallback
+      ? makeStableUuid(type, alias)
+      : uuid()
+  return `${idPrefix(type)}${id}`
+}
+
+// Deterministic id derived solely from a caller-supplied seed. Unlike makeId it keeps no
+// global state — no incrementing counter, no alias registry — so the same (type, seed)
+// always maps to the same id on every compile and in any process. Compiled artifacts seed
+// their ids this way (e.g. generateCalulationMap's command nodes, seeded by their calc id +
+// structural role) so unchanged source recompiles byte-identically and editing one calc
+// never shifts another's ids. The seed must be unique within a single config.
+export const makeSeededId = (type: IdType, seed: string) => {
+  if (type === 'subspace') {
+    throw new Error('Currently subspace is not supported for ID generation, please use a fixed ID')
   }
-  return `${prefix}${opts?.snapshotMode ? countUUID() : uuid()}`
+  return `${idPrefix(type)}${uuid({ random: hashToRandomBytes([readApplicationId(), type, seed]) })}`
 }

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) |