@fugood/bricks-ctor 2.25.0-beta.1 → 2.25.0-beta.10

package/compile/__tests__/index.test.js

@@ -0,0 +1,115 @@
+import { compile } from '../index'
+
+const SUBSPACE_ID = 'SUBSPACE_00000000-0000-0000-0000-000000000001'
+const CANVAS_ID = 'CANVAS_00000000-0000-0000-0000-000000000001'
+const ANIMATION_ID = 'ANIMATION_00000000-0000-0000-0000-000000000001'
+
+const makeApp = (animations) => {
+  const rootCanvas = {
+    __typename: 'Canvas',
+    id: CANVAS_ID,
+    items: [],
+  }
+  const rootSubspace = {
+    __typename: 'Subspace',
+    id: SUBSPACE_ID,
+    title: 'Main Subspace',
+    layout: {
+      width: 96,
+      height: 54,
+    },
+    rootCanvas,
+    canvases: [rootCanvas],
+    animations,
+    bricks: [],
+    generators: [],
+    data: [],
+    dataRouting: [],
+    dataCalculation: [],
+  }
+
+  return {
+    name: 'Compile animation test',
+    rootSubspace,
+    subspaces: [rootSubspace],
+  }
+}
+
+describe('compile animations', () => {
+  test('normalizes mixed legacy spring config', async () => {
+    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      const config = await compile(
+        makeApp([
+          {
+            __typename: 'Animation',
+            id: ANIMATION_ID,
+            alias: 'btnPressOut',
+            title: 'Button Press Out',
+            property: 'transform.scale',
+            config: {
+              __type: 'AnimationSpringConfig',
+              toValue: 1,
+              friction: 5,
+              tension: 200,
+              speed: 14,
+              bounciness: 8,
+            },
+          },
+        ]),
+      )
+
+      expect(config.subspace_map[SUBSPACE_ID].animation_map[ANIMATION_ID].config).toEqual({
+        toValue: 1,
+        friction: 5,
+        tension: 200,
+      })
+      const warning = warnSpy.mock.calls[0][0]
+      expect(warning).toContain('Resolved animation spring config')
+      expect(warning).toContain('Button Press Out')
+      expect(warning).toContain('btnPressOut')
+      expect(warning).toContain('transform.scale')
+      expect(warning).toContain('Main Subspace')
+      expect(warning).not.toContain('ANIMATION_')
+      expect(warning).not.toContain('SUBSPACE_')
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+
+  test('rejects invalid animation property', async () => {
+    await expect(
+      compile(
+        makeApp([
+          {
+            __typename: 'Animation',
+            id: ANIMATION_ID,
+            property: 'transform.skewX',
+            config: {
+              __type: 'AnimationTimingConfig',
+              toValue: 1,
+            },
+          },
+        ]),
+      ),
+    ).rejects.toThrow(/Invalid animation property/)
+  })
+
+  test('rejects invalid animation config type', async () => {
+    await expect(
+      compile(
+        makeApp([
+          {
+            __typename: 'Animation',
+            id: ANIMATION_ID,
+            property: 'opacity',
+            config: {
+              __type: 'AnimationUnknownConfig',
+              toValue: 1,
+            },
+          },
+        ]),
+      ),
+    ).rejects.toThrow(/Invalid animation config type/)
+  })
+})

package/compile/action-name-map.ts

@@ -327,6 +327,29 @@ export const templateActionNameMap = {
       animated: 'BRICK_MAPS_ANIMATED',
     },
   },
+  BRICK_SKETCH: {
+    BRICK_SKETCH_SET_TOOL: {
+      tool: 'BRICK_SKETCH_TOOL',
+    },
+    BRICK_SKETCH_SET_COLOR: {
+      color: 'BRICK_SKETCH_COLOR',
+    },
+    BRICK_SKETCH_SET_STROKE_WIDTH: {
+      strokeWidth: 'BRICK_SKETCH_STROKE_WIDTH',
+    },
+    BRICK_SKETCH_IMPORT_STATE: {
+      stateJson: 'BRICK_SKETCH_STATE_JSON',
+    },
+    BRICK_SKETCH_EXPORT_IMAGE: {
+      imageFormat: 'BRICK_SKETCH_IMAGE_FORMAT',
+      imageQuality: 'BRICK_SKETCH_IMAGE_QUALITY',
+    },
+    BRICK_SKETCH_ADD_STROKE: {
+      strokePoints: 'BRICK_SKETCH_STROKE_POINTS',
+      strokeColor: 'BRICK_SKETCH_STROKE_COLOR',
+      strokeWidth: 'BRICK_SKETCH_STROKE_WIDTH',
+    },
+  },
 
   GENERATOR_FILE: {
     GENERATOR_FILE_READ_CONTENT: {

package/compile/index.ts

@@ -301,6 +301,162 @@ const animationTypeMap = {
   AnimationTimingConfig: 'timing',
   AnimationSpringConfig: 'spring',
   AnimationDecayConfig: 'decay',
+} as const
+
+type CompiledAnimationType = (typeof animationTypeMap)[keyof typeof animationTypeMap]
+type WarningMetadata = Record<string, unknown>
+
+const animationProperties = new Set([
+  'transform.translateX',
+  'transform.translateY',
+  'transform.scale',
+  'transform.scaleX',
+  'transform.scaleY',
+  'transform.rotate',
+  'transform.rotateX',
+  'transform.rotateY',
+  'opacity',
+])
+
+const animationComposeTypes = new Set(['parallel', 'sequence'])
+const springConfigFamilies = [
+  ['stiffness', 'damping', 'mass'],
+  ['tension', 'friction'],
+  ['bounciness', 'speed'],
+]
+const springConfigFamilyKeys = new Set(springConfigFamilies.flat())
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+
+const hasDefinedConfigValue = (config: Record<string, unknown>, key: string) =>
+  config[key] !== undefined
+
+const assertConfigValue = (
+  config: Record<string, unknown>,
+  key: string,
+  errorReference: string,
+) => {
+  if (!hasDefinedConfigValue(config, key)) {
+    throw new Error(`Invalid animation config ${errorReference}: missing "${key}"`)
+  }
+}
+
+const assertAnimationProperty = (property: unknown, errorReference: string) => {
+  if (typeof property !== 'string' || !animationProperties.has(property)) {
+    throw new Error(
+      `Invalid animation property${errorReference ? ` ${errorReference}` : ''}: ${String(
+        property,
+      )}`,
+    )
+  }
+  return property
+}
+
+const getAnimationType = (config: unknown, errorReference: string): CompiledAnimationType => {
+  if (!isRecord(config)) {
+    throw new Error(`Invalid animation config ${errorReference}: config must be an object`)
+  }
+
+  const animationType = animationTypeMap[config.__type as keyof typeof animationTypeMap]
+  if (!animationType) {
+    throw new Error(`Invalid animation config type ${errorReference}: ${String(config.__type)}`)
+  }
+  return animationType
+}
+
+const assertAnimationComposeType = (composeType: unknown, errorReference: string) => {
+  if (typeof composeType !== 'string' || !animationComposeTypes.has(composeType)) {
+    throw new Error(`Invalid animation compose type ${errorReference}: ${String(composeType)}`)
+  }
+  return composeType
+}
+
+const pickDefinedConfigValues = (config: Record<string, unknown>, keys: string[]) =>
+  keys.reduce((acc, key) => {
+    if (hasDefinedConfigValue(config, key)) acc[key] = config[key]
+    return acc
+  }, {})
+
+const getDefinedConfigKeys = (config: Record<string, unknown>, keys: string[]) =>
+  keys.filter((key) => hasDefinedConfigValue(config, key))
+
+const formatWarningMetadata = (metadata: WarningMetadata = {}) =>
+  Object.entries(metadata)
+    .filter(([, value]) => value !== undefined && value !== null && value !== '')
+    .map(([key, value]) => `${key}: ${String(value)}`)
+    .join(', ')
+
+const formatWarningReference = (metadata?: WarningMetadata) => {
+  const metadataText = formatWarningMetadata(metadata)
+  return metadataText ? ` [${metadataText}]` : ''
+}
+
+const normalizeSpringConfig = (
+  config: Record<string, unknown>,
+  errorReference: string,
+  warningMetadata?: WarningMetadata,
+): Record<string, unknown> => {
+  assertConfigValue(config, 'toValue', errorReference)
+
+  const usedFamilies = springConfigFamilies.filter((keys) =>
+    keys.some((key) => hasDefinedConfigValue(config, key)),
+  )
+  if (usedFamilies.length <= 1) return config
+
+  const configWithoutSpringFamily = Object.entries(config).reduce((acc, [key, value]) => {
+    if (!springConfigFamilyKeys.has(key)) acc[key] = value
+    return acc
+  }, {})
+
+  // Match runtime normalization: physical spring values are most explicit,
+  // otherwise preserve BRICKS' historical tension/friction controls.
+  const resolvedFamily =
+    usedFamilies.find((keys) => keys.includes('stiffness')) ||
+    usedFamilies.find((keys) => keys.includes('tension')) ||
+    usedFamilies[0]
+  const resolvedFamilyKeys = getDefinedConfigKeys(config, resolvedFamily)
+  const droppedFamilyKeys = usedFamilies
+    .filter((keys) => keys !== resolvedFamily)
+    .flatMap((keys) => getDefinedConfigKeys(config, keys))
+
+  console.warn(
+    `[Warning] Resolved animation spring config${formatWarningReference(
+      warningMetadata,
+    )}: using ${resolvedFamilyKeys.join('/')}, dropping ${droppedFamilyKeys.join('/')}`,
+  )
+
+  return {
+    ...configWithoutSpringFamily,
+    ...pickDefinedConfigValues(config, resolvedFamily),
+  }
+}
+
+const compileAnimationConfig = (
+  animationType: CompiledAnimationType,
+  config: unknown,
+  errorReference: string,
+  warningMetadata?: WarningMetadata,
+) => {
+  if (!isRecord(config)) {
+    throw new Error(`Invalid animation config ${errorReference}: config must be an object`)
+  }
+
+  const compiledConfig = compileProperty(omit(config, '__type'), errorReference)
+
+  if (!isRecord(compiledConfig)) {
+    throw new Error(`Invalid animation config ${errorReference}: config must compile to an object`)
+  }
+
+  if (animationType === 'timing') {
+    assertConfigValue(compiledConfig, 'toValue', errorReference)
+  } else if (animationType === 'spring') {
+    return normalizeSpringConfig(compiledConfig, errorReference, warningMetadata)
+  } else if (animationType === 'decay') {
+    assertConfigValue(compiledConfig, 'velocity', errorReference)
+  }
+
+  return compiledConfig
 }
 
 const compileFrame = (frame: Canvas['items'][number]['frame']) => ({
@@ -629,39 +785,63 @@ export const compile = async (app: Application) => {
             `(animation index: ${animationIndex}, subspace: ${subspaceId})`,
           )
 
-          if (animation.__typename === 'Animation') {
+          const animationTypename = animation.__typename
+          if (animationTypename === 'Animation') {
             const animationDef = animation as AnimationDef
+            const animationErrorReference = `(animation: ${animationId}, subspace ${subspaceId})`
+            const animationWarningMetadata = {
+              animationIndex,
+              animationTitle: animationDef.title,
+              animationAlias: animationDef.alias,
+              animationProperty: animationDef.property,
+              subspaceIndex,
+              subspaceTitle: subspace.title,
+            }
+            const animationType = getAnimationType(animationDef.config, animationErrorReference)
             map[animationId] = {
               alias: animationDef.alias,
               title: animationDef.title,
               description: animationDef.description,
               hide_short_ref: animationDef.hideShortRef,
               animationRunType: animationDef.runType,
-              property: animationDef.property,
-              type: animationTypeMap[animationDef.config.__type],
-              config: compileProperty(
-                omit(animationDef.config, '__type'),
-                `(animation: ${animationId}, subspace ${subspaceId})`,
+              property: assertAnimationProperty(animationDef.property, animationErrorReference),
+              type: animationType,
+              config: compileAnimationConfig(
+                animationType,
+                animationDef.config,
+                animationErrorReference,
+                animationWarningMetadata,
               ),
             }
-          } else if (animation.__typename === 'AnimationCompose') {
+          } else if (animationTypename === 'AnimationCompose') {
             const animationDef = animation as AnimationComposeDef
+            const animationErrorReference = `(animation: ${animationId}, subspace ${subspaceId})`
             map[animationId] = {
               alias: animationDef.alias,
               title: animationDef.title,
               description: animationDef.description,
               hide_short_ref: animationDef.hideShortRef,
               animationRunType: animationDef.runType,
-              compose_type: animationDef.composeType,
+              compose_type: assertAnimationComposeType(
+                animationDef.composeType,
+                animationErrorReference,
+              ),
               item_list: animationDef.items.map((item, index) => {
                 const innerAnimation = item()
-                if (!innerAnimation?.id)
-                  throw new Error(
-                    `Invalid animation index: ${index} (animation: ${innerAnimation.id}, subspace ${subspaceId})`,
-                  )
-                return { animation_id: innerAnimation.id }
+                const innerAnimationId = assertEntryId(
+                  innerAnimation?.id,
+                  'ANIMATION',
+                  `(animation item index: ${index}, animation: ${animationId}, subspace ${subspaceId})`,
+                )
+                return { animation_id: innerAnimationId }
               }),
             }
+          } else {
+            throw new Error(
+              `Invalid animation typename (animation: ${animationId}, subspace ${subspaceId}): ${String(
+                animationTypename,
+              )}`,
+            )
           }
           return map
         }, {}),

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@fugood/bricks-ctor",
-  "version": "2.25.0-beta.1",
+  "version": "2.25.0-beta.10",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun scripts/build.js"
   },
   "dependencies": {
-    "@fugood/bricks-cli": "^2.25.0-beta.1",
+    "@fugood/bricks-cli": "^2.25.0-beta.10",
     "@huggingface/gguf": "^0.3.2",
     "@iarna/toml": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.15.0",
@@ -25,5 +25,5 @@
   "peerDependencies": {
     "oxfmt": "^0.36.0"
   },
-  "gitHead": "775ccfb5dd8a2af732c936d16455049aa4e69085"
+  "gitHead": "7b909dc28862872743cf0459ff65d16af67721c6"
 }

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

@@ -41,12 +41,13 @@ const bounce: AnimationDef = {
     toValue: 1,
     friction: 7,
     tension: 40,
-    speed: 12,
-    bounciness: 8,
   },
 }
 ```
 
+Use one spring parameter family per config: `tension/friction`, `speed/bounciness`, or
+`stiffness/damping/mass`.
+
 ### Decay Animation
 Velocity-based deceleration animation.
 

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

@@ -20,16 +20,26 @@ When mobile devices or embedded systems lack hardware for local AI inference (LL
 
 ## Client Configuration
 
-In generator properties, configure Buttress settings:
+In generator properties, configure `buttressConnectionSettings`:
 
 | 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 |
+| `enabled` | Toggle Buttress offloading |
+| `autoDiscoverType` | `auto` (LAN auto-discovery, recommended) or `manual` (typed URL) |
+| `url` | Server URL (`manual` mode only — leave empty for `auto`) |
+| `fallbackType` | If Buttress is unreachable: `use-local` runs locally, `no-op` blocks the load |
+| `strategy` | Execution preference (see below) |
 
-### Strategy Options
+The launcher provides the access token automatically — there is **no user-facing access-token setting**. In `auto` mode the launcher discovers servers bound to the device's workspace and uses its workspace-scoped JWT; in `manual` mode it sends the same JWT only when the typed URL belongs to a server bound to the same workspace (verified against the server's `/buttress/info`).
+
+### `autoDiscoverType` options
+
+| Mode | When to use | What the device does |
+|------|-------------|----------------------|
+| `auto` | LAN deployment with a workspace-bound buttress-server | Listens for UDP announcements and picks the strongest server bound to its workspace; reconnects automatically when the workspace flips |
+| `manual` | Internet-reachable server, mixed networks, or a public/unbound server | Connects to the typed `url` directly; sends a token only when the server is bound to the same workspace |
+
+### Strategy options
 
 | Strategy | Description |
 |----------|-------------|
@@ -37,7 +47,11 @@ In generator properties, configure Buttress settings:
 | `prefer-buttress` | Use Buttress if available, fallback to local |
 | `prefer-best` | Auto-select based on capability comparison |
 
-## Generator Configuration Example
+## Generator Configuration Examples
+
+### Auto-discovery (recommended)
+
+Workspace-bound launcher + workspace-bound buttress-server on the same LAN. No URL needed — discovery picks the highest-scoring server that runs the requested backend.
 
 ```typescript
 import { makeId } from 'bricks-ctor'
@@ -53,7 +67,7 @@ const llmGenerator: GeneratorLLM = {
     contextSize: 8192,
     buttressConnectionSettings: {
       enabled: true,
-      url: 'http://192.168.1.100:2080',
+      autoDiscoverType: 'auto',
       fallbackType: 'use-local',
       strategy: 'prefer-best',
     },
@@ -63,6 +77,44 @@ const llmGenerator: GeneratorLLM = {
 }
 ```
 
+### Manual URL
+
+Use when the server isn't on the launcher's broadcast domain (cross-subnet, internet, behind a reverse proxy) or you want to point at a specific public/unbound server.
+
+```typescript
+buttressConnectionSettings: {
+  enabled: true,
+  autoDiscoverType: 'manual',
+  url: 'http://192.168.1.100:2080',
+  fallbackType: 'use-local',
+  strategy: 'prefer-best',
+}
+```
+
+> ⚠️ With `fallbackType: 'no-op'` the generator refuses to load locally if Buttress is unreachable. Use `'use-local'` whenever the device can also run the model standalone.
+
+## Integrating a discovered buttress-server
+
+The ctor-desktop "Local Devices" panel (and the `bricks buttress scan` CLI) can hand you a server's identity, workspace, and announced generator caps. When the user asks to integrate one:
+
+1. **Confirm workspace match.** The discovery message says whether the server's workspace matches this project's. If it doesn't, do NOT add the integration — instruct the user to run `bricks buttress unbind && bricks buttress bind` from this workspace's owner CLI on the server host. The launcher won't trust a cross-workspace server.
+
+2. **Map announced types to generator templates.** For each `generators[].type` in the announce, target the matching templateKey (create the generator if absent):
+
+   | Announced type | templateKey                  | Default model |
+   |----------------|------------------------------|---------------|
+   | `ggml-llm`     | `GENERATOR_LLM`              | `ggml-org/gemma-3-12b-it-qat-GGUF` (≥20 GB usable) or `ggml-org/gpt-oss-20b-GGUF` (~12 GB usable) |
+   | `mlx-llm`      | `GENERATOR_MLX_LLM`          | `mlx-community/Qwen3-4B-4bit` (or a larger 4-bit quant if `usableBytes` allows) |
+   | `ggml-stt`     | `GENERATOR_SPEECH_INFERENCE` | `BricksDisplay/whisper-ggml` (filename `ggml-small-q8_0.bin`) |
+
+   Pick a model that fits the announced `usableBytes`. Set `contextSize` to match.
+
+3. **Use the canonical auto-discovery config** from "Auto-discovery (recommended)" above. Don't switch to manual mode just because the server is on the LAN — auto mode picks the workspace-bound server automatically and rebinds when the device's workspace flips.
+
+### Real-device caveat
+
+Buttress LAN auto-discovery uses native UDP via `react-native-jsi-udp`. The iOS Simulator silently fails to bind UDP, so auto mode is a no-op there. With `fallbackType: 'use-local'` the generator falls back to local inference in the simulator — dev/test stays functional. **Validate the buttress path itself only when deploying to a real Foundation device; don't gate the build on simulator validation.**
+
 ## Server Setup
 
 ### Requirements
@@ -98,6 +150,43 @@ bricks-buttress --config ./config.toml
 |----------|-------------|
 | `HF_TOKEN` | Hugging Face token for model downloads |
 | `ENABLE_OPENAI_COMPAT_ENDPOINT` | Set to `1` for OpenAI-compatible API |
+| `BRICKS_BUTTRESS_STATE_DIR` | Override the workspace state directory (default `~/.bricks-cli/buttress`) |
+
+## Bind the Server to a Workspace
+
+To use `autoDiscoverType: 'auto'` — and to require workspace-scoped JWT auth — pair the buttress-server with a BRICKS workspace using the `bricks buttress` CLI commands. An unbound server stays in legacy public mode and accepts any LAN client.
+
+### One-time bind
+
+```bash
+# Log into the cloud bricks-server with the workspace owner's account
+bricks auth login
+
+# Pair the buttress-server running on this machine with the active workspace
+bricks buttress bind
+
+# Restart bricks-buttress so it picks up the new state.json
+```
+
+`bricks buttress bind` writes `~/.bricks-cli/buttress/state.json` containing the workspace id, the issuer's Ed25519 public key, and a stable `serverId` (defaults to `buttress-<machineId>`). Override location with `--state-dir` or `$BRICKS_BUTTRESS_STATE_DIR`. For headless setups, use `bricks buttress bind --print` to emit state.json to stdout.
+
+### Verify and manage
+
+```bash
+# Show local binding + workspace-side bound list
+bricks buttress status
+
+# Discover buttress-servers on the LAN (with version, auth state, generator caps)
+bricks buttress scan
+
+# Issue a long-lived workspace access token (CI / ctor agents that already hold a workspace token)
+bricks buttress issue-token --ttl 86400
+
+# Detach this server from the workspace
+bricks buttress unbind
+```
+
+After binding, launchers in the same workspace will auto-discover this server; manual-mode generators will only send their access token if the server's reported workspace matches their own.
 
 ## Server Configuration (TOML)
 

package/tools/preview-main.mjs

@@ -6,6 +6,12 @@ import { createServer } from 'http'
 import { parseArgs } from 'util'
 import * as TOON from '@toon-format/toon'
 
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on('error', (err) => {
+    if (err.code !== 'EPIPE') throw err
+  })
+}
+
 const { values } = parseArgs({
   args: process.argv,
   options: {
@@ -224,16 +230,23 @@ app.on('ready', () => {
     )
     if (takeScreenshotConfig) {
       const { delay, width, height, path } = takeScreenshotConfig
-      setTimeout(() => {
+      setTimeout(async () => {
+        let screenshotFailed = false
         console.log('Taking screenshot')
-        mainWindow.webContents.capturePage().then((image) => {
+        try {
+          const image = await mainWindow.webContents.capturePage()
           console.log('Writing screenshot to', path)
-          writeFile(path, image.resize({ width, height }).toJPEG(75))
+          await writeFile(path, image.resize({ width, height }).toJPEG(75))
+        } catch (err) {
+          screenshotFailed = true
+          console.error('Screenshot capture/write failed', err)
+        } finally {
           if (noKeepOpen) {
             console.log('Closing app')
-            app.quit()
+            if (screenshotFailed) app.exit(1)
+            else app.quit()
           }
-        })
+        }
       }, delay)
     }
   }

package/types/animation.ts

@@ -44,10 +44,21 @@ export interface AnimationTimingConfig {
 export interface AnimationSpringConfig {
   __type: 'AnimationSpringConfig'
   toValue: number // BRICKS Grid unit
-  friction: number
-  tension: number
-  speed: number
-  bounciness: number
+  // Use one spring parameter family: tension/friction, speed/bounciness,
+  // or stiffness/damping/mass.
+  friction?: number
+  tension?: number
+  speed?: number
+  bounciness?: number
+  stiffness?: number
+  damping?: number
+  mass?: number
+  velocity?: number
+  delay?: number
+  isInteraction?: boolean
+  overshootClamping?: boolean
+  restDisplacementThreshold?: number
+  restSpeedThreshold?: number
 }
 
 export interface AnimationDecayConfig {
@@ -62,7 +73,7 @@ export interface AnimationDef {
   __typename: 'Animation'
   id: string
   alias?: string
-  title: string
+  title?: string
   description?: string
   hideShortRef?: boolean
   runType?: 'once' | 'loop'

package/types/bricks/Image.ts

@@ -25,6 +25,10 @@ Default property:
   "templateType": "${}",
   "fadeDuration": 0,
   "blurBackgroundRadius": 8,
+  "imageFilterEnabled": false,
+  "imageFilterBlur": 0,
+  "imageFilterBlurMode": "clamp",
+  "imageFilterColorMatrix": [],
   "loadSystemIos": "auto",
   "loadSystemAndroid": "auto"
 }
@@ -50,6 +54,14 @@ Default property:
     enableBlurBackground?: boolean | DataLink
     /* The blur radius of the blur filter added to the image background */
     blurBackgroundRadius?: number | DataLink
+    /* Enable Skia image filters. When disabled, Image uses the normal platform image renderer. */
+    imageFilterEnabled?: boolean | DataLink
+    /* Blur amount for the Skia image filter. */
+    imageFilterBlur?: number | DataLink
+    /* Tile mode for the Skia blur image filter. */
+    imageFilterBlurMode?: 'clamp' | 'decal' | 'repeat' | 'mirror' | DataLink
+    /* Optional 4x5 color matrix for the Skia image filter. Provide 20 numbers. */
+    imageFilterColorMatrix?: Array<number | DataLink> | DataLink
     /* [iOS] The use priority of image loading system (Auto: sdwebimage, fallback to default if failed) */
     loadSystemIos?: 'auto' | 'sdwebimage' | 'default' | DataLink
     /* [Android] The use priority of image loading system (Auto: glide, fallback to fresco if failed) */

package/types/bricks/Sketch.ts

@@ -0,0 +1,254 @@
+/* Auto generated by build script
+ *
+ * Drawing canvas with undo/redo, import/export state, and image export
+ */
+import type { SwitchCondInnerStateCurrentCanvas, SwitchCondData, SwitchDef } from '../switch'
+import type { Data, DataLink } from '../data'
+import type { Animation, AnimationBasicEvents } from '../animation'
+import type {
+  Brick,
+  EventAction,
+  EventActionForItem,
+  ActionWithDataParams,
+  ActionWithParams,
+  Action,
+  EventProperty,
+} from '../common'
+import type { BrickBasicProperty, BrickBasicEvents, BrickBasicEventsForItem } from '../brick-base'
+import type { TemplateEventPropsMap } from '../../utils/event-props'
+
+/* Undo the last stroke */
+export type BrickSketchActionUndo = Action & {
+  __actionName: 'BRICK_SKETCH_UNDO'
+}
+
+/* Redo the last undone stroke */
+export type BrickSketchActionRedo = Action & {
+  __actionName: 'BRICK_SKETCH_REDO'
+}
+
+/* Clear all strokes from the canvas */
+export type BrickSketchActionClear = Action & {
+  __actionName: 'BRICK_SKETCH_CLEAR'
+}
+
+/* Set the active tool */
+export type BrickSketchActionSetTool = ActionWithParams & {
+  __actionName: 'BRICK_SKETCH_SET_TOOL'
+  params?: Array<{
+    input: 'tool'
+    value?: 'pen' | 'eraser' | DataLink | EventProperty
+    mapping?: string
+  }>
+}
+
+/* Set the stroke color */
+export type BrickSketchActionSetColor = ActionWithParams & {
+  __actionName: 'BRICK_SKETCH_SET_COLOR'
+  params?: Array<{
+    input: 'color'
+    value?: string | DataLink | EventProperty
+    mapping?: string
+  }>
+}
+
+/* Set the stroke width (px) */
+export type BrickSketchActionSetStrokeWidth = ActionWithParams & {
+  __actionName: 'BRICK_SKETCH_SET_STROKE_WIDTH'
+  params?: Array<{
+    input: 'strokeWidth'
+    value?: number | DataLink | EventProperty
+    mapping?: string
+  }>
+}
+
+/* Import sketch state (JSON string from a previous export) */
+export type BrickSketchActionImportState = ActionWithParams & {
+  __actionName: 'BRICK_SKETCH_IMPORT_STATE'
+  params?: Array<{
+    input: 'stateJson'
+    value?: string | DataLink | EventProperty
+    mapping?: string
+  }>
+}
+
+/* Export the current sketch state to the BRICK_SKETCH_STATE outlet */
+export type BrickSketchActionExportState = Action & {
+  __actionName: 'BRICK_SKETCH_EXPORT_STATE'
+}
+
+/* Export the canvas as an image (file URI emitted to BRICK_SKETCH_IMAGE_URI) */
+export type BrickSketchActionExportImage = ActionWithParams & {
+  __actionName: 'BRICK_SKETCH_EXPORT_IMAGE'
+  params?: Array<
+    | {
+        input: 'imageFormat'
+        value?: 'png' | 'jpeg' | DataLink | EventProperty
+        mapping?: string
+      }
+    | {
+        input: 'imageQuality'
+        value?: number | DataLink | EventProperty
+        mapping?: string
+      }
+  >
+}
+
+/* Add a stroke programmatically */
+export type BrickSketchActionAddStroke = ActionWithParams & {
+  __actionName: 'BRICK_SKETCH_ADD_STROKE'
+  params?: Array<
+    | {
+        input: 'strokePoints'
+        value?: any | EventProperty
+        mapping?: string
+      }
+    | {
+        input: 'strokeColor'
+        value?: string | DataLink | EventProperty
+        mapping?: string
+      }
+    | {
+        input: 'strokeWidth'
+        value?: number | DataLink | EventProperty
+        mapping?: string
+      }
+  >
+}
+
+interface BrickSketchDef {
+  /*
+Default property:
+{
+  "tool": "pen",
+  "strokeColor": "#000000",
+  "strokeWidth": 3,
+  "pressureSensitive": true,
+  "layoutType": "cover",
+  "scale": 1,
+  "mode": "pen",
+  "theme": "auto",
+  "backgroundPattern": "dot",
+  "hideToolbar": false,
+  "hideUndo": false,
+  "hideRedo": false,
+  "hidePencilTool": false,
+  "hideColorPicker": false,
+  "hideThickness": false,
+  "availableColors": [
+    "#000000",
+    "#ffffff",
+    "#e53935",
+    "#fb8c00",
+    "#fdd835",
+    "#43a047",
+    "#1e88e5",
+    "#8e24aa"
+  ]
+}
+  */
+  property?: BrickBasicProperty & {
+    /* Initial sketch state to load on mount (object or JSON string from a previous export). When `BRICK_SKETCH_STATE` outlet feeds the same value back via binding, the echo is detected and ignored to avoid an update loop. */
+    initialState?: string | DataLink | DataLink | {} | DataLink
+    /* Drawing tool */
+    tool?: 'pen' | 'eraser' | DataLink
+    /* Stroke color */
+    strokeColor?: string | DataLink
+    /* Stroke width (px) */
+    strokeWidth?: number | DataLink
+    /* Vary stroke width by pen pressure */
+    pressureSensitive?: boolean | DataLink
+    /* Canvas layout. `cover` fits the brick frame; `extend` lets the canvas grow with content */
+    layoutType?: 'cover' | 'extend' | DataLink
+    /* Canvas resolution scale (device-pixel multiplier) */
+    scale?: number | DataLink
+    /* Interaction mode. `pen` = drawing (scroll disabled), `scroll` = scroll/pan (drawing disabled) */
+    mode?: 'pen' | 'scroll' | DataLink
+    /* Toolbar/UI theme. `auto` follows the system color scheme; `light`/`dark` force the palette. */
+    theme?: 'auto' | 'light' | 'dark' | DataLink
+    /* Background color of the canvas */
+    backgroundColor?: string | DataLink
+    /* Background image URL (covers the canvas; rendered behind strokes) */
+    backgroundImage?: string | DataLink
+    /* Decorative background pattern when no background image is provided */
+    backgroundPattern?: 'dot' | 'grid' | 'none' | DataLink
+    /* Hide the entire built-in toolbar */
+    hideToolbar?: boolean | DataLink
+    /* Hide the undo button in the toolbar */
+    hideUndo?: boolean | DataLink
+    /* Hide the redo button in the toolbar */
+    hideRedo?: boolean | DataLink
+    /* Hide the pen/eraser tool toggle */
+    hidePencilTool?: boolean | DataLink
+    /* Hide the color picker */
+    hideColorPicker?: boolean | DataLink
+    /* Hide the stroke thickness slider */
+    hideThickness?: boolean | DataLink
+    /* Colors shown in the built-in color picker */
+    availableColors?: Array<string | DataLink> | DataLink
+  }
+  events?: BrickBasicEvents & {
+    /* A stroke was just committed (drawn or added programmatically) */
+    onStrokeEnd?: Array<EventAction<string & keyof TemplateEventPropsMap['Sketch']['onStrokeEnd']>>
+    /* The canvas was cleared */
+    onClear?: Array<EventAction>
+    /* Sketch state changed (any commit, undo, redo, clear, or import) */
+    onStateChange?: Array<EventAction>
+    /* Active tool changed */
+    onToolChange?: Array<
+      EventAction<string & keyof TemplateEventPropsMap['Sketch']['onToolChange']>
+    >
+    /* Image export finished */
+    onExportImage?: Array<
+      EventAction<string & keyof TemplateEventPropsMap['Sketch']['onExportImage']>
+    >
+  }
+  outlets?: {
+    /* Current sketch state (strokes, settings, undo/redo stacks) */
+    state?: () => Data<{
+      strokes?: any[]
+      undone?: any[]
+      settings?: { [key: string]: any }
+      [key: string]: any
+    }>
+    /* URI of the most recently exported image */
+    imageUri?: () => Data<string>
+    /* Most recently committed stroke (points, color, width) */
+    lastStroke?: () => Data<{
+      color?: string
+      width?: number
+      tool?: string
+      points?: any[]
+      [key: string]: any
+    }>
+  }
+  animation?: AnimationBasicEvents & {
+    onStrokeEnd?: Animation
+    onClear?: Animation
+    onStateChange?: Animation
+    onToolChange?: Animation
+    onExportImage?: Animation
+  }
+}
+
+/* Drawing canvas with undo/redo, import/export state, and image export */
+export type BrickSketch = Brick &
+  BrickSketchDef & {
+    templateKey: 'BRICK_SKETCH'
+    switches?: Array<
+      SwitchDef &
+        BrickSketchDef & {
+          conds?: Array<{
+            method: '==' | '!=' | '>' | '<' | '>=' | '<='
+            cond:
+              | SwitchCondInnerStateCurrentCanvas
+              | SwitchCondData
+              | {
+                  __typename: 'SwitchCondInnerStateOutlet'
+                  outlet: 'state' | 'imageUri' | 'lastStroke'
+                  value: any
+                }
+          }>
+        }
+    >
+  }

package/types/bricks/index.ts

@@ -19,3 +19,4 @@ export * from './Camera'
 export * from './WebRtcStream'
 export * from './GenerativeMedia'
 export * from './Maps'
+export * from './Sketch'

package/types/data.ts

@@ -18,7 +18,7 @@ export type Data<T = any> = DataDef & {
   __typename: 'Data'
   id: string
   alias?: string
-  title: string
+  title?: string
   description?: string
   hideShortRef?: boolean
   metadata?: {

package/types/generators/LlmGgml.ts

@@ -713,6 +713,7 @@ Default property:
       | {
           enabled?: boolean | DataLink
           url?: string | DataLink
+          autoDiscoverType?: 'manual' | 'auto' | DataLink
           fallbackType?: 'use-local' | 'no-op' | DataLink
           strategy?: 'prefer-local' | 'prefer-buttress' | 'prefer-best' | DataLink
         }

package/types/generators/LlmMlx.ts

@@ -158,6 +158,7 @@ Default property:
       | {
           enabled?: boolean | DataLink
           url?: string | DataLink
+          autoDiscoverType?: 'manual' | 'auto' | DataLink
           fallbackType?: 'use-local' | 'no-op' | DataLink
           strategy?: 'prefer-local' | 'prefer-buttress' | 'prefer-best' | DataLink
         }

package/types/generators/RealtimeTranscription.ts

@@ -174,6 +174,7 @@ Default property:
           isCapturing?: boolean
           data?: {
             result?: string
+            language?: string
             [key: string]: any
           }
           vadEvent?: {
@@ -215,6 +216,7 @@ Default property:
       isCapturing?: boolean
       data?: {
         result?: string
+        language?: string
         [key: string]: any
       }
       vadEvent?: {
@@ -238,6 +240,10 @@ Default property:
     }>
     /* Stabilized transcription text from completed slices */
     stabilizedText?: () => Data<string>
+    /* Latest detected language code (e.g. `en`, `zh`, `ja`) from any transcribe slice (best-effort, may flicker on short slices) */
+    detectedLanguage?: () => Data<string>
+    /* Detected language code of the most recently stabilized (finalized) slice */
+    stabilizedLanguage?: () => Data<string>
     /* Audio output file path (auto-generated when saving audio) */
     audioOutputPath?: () => Data<string>
     /* Available microphone devices (Web / Desktop only) */
@@ -269,6 +275,8 @@ export type GeneratorRealtimeTranscription = Generator &
                     | 'lastTranscribeEvent'
                     | 'lastVadEvent'
                     | 'stabilizedText'
+                    | 'detectedLanguage'
+                    | 'stabilizedLanguage'
                     | 'audioOutputPath'
                     | 'devices'
                   value: any

package/types/generators/SpeechToTextGgml.ts

@@ -323,6 +323,7 @@ Default property:
       | {
           enabled?: boolean | DataLink
           url?: string | DataLink
+          autoDiscoverType?: 'manual' | 'auto' | DataLink
           fallbackType?: 'use-local' | 'no-op' | DataLink
           strategy?: 'prefer-local' | 'prefer-buttress' | 'prefer-best' | DataLink
         }
@@ -358,9 +359,12 @@ Default property:
     transcribeProgress?: () => Data<number>
     /* Inference result */
     transcribeResult?: () => Data<string>
+    /* Detected language code of the latest transcription (e.g. `en`, `zh`, `ja`) */
+    detectedLanguage?: () => Data<string>
     /* Inference result details */
     transcribeDetails?: () => Data<{
       result?: string
+      language?: string
       segments?: Array<{
         start?: number
         end?: number
@@ -405,6 +409,7 @@ export type GeneratorSpeechInference = Generator &
                     | 'isTranscribing'
                     | 'transcribeProgress'
                     | 'transcribeResult'
+                    | 'detectedLanguage'
                     | 'transcribeDetails'
                     | 'recordedPath'
                   value: any

package/types/subspace.ts

@@ -7,7 +7,7 @@ import type { DataCalculation } from './data-calc'
 export type Subspace = {
   __typename: 'Subspace'
   id: string
-  title: string
+  title?: string
   description?: string
   hideShortRef?: boolean
   unused?: boolean

package/utils/__tests__/id.test.js

@@ -0,0 +1,58 @@
+import { makeId } from '../id'
+
+const UUID = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
+const UUID_ONLY_RE = new RegExp(`^${UUID}$`)
+
+describe('makeId', () => {
+  describe('type prefixes', () => {
+    const cases = [
+      ['animation', 'ANIMATION_'],
+      ['brick', 'BRICK_'],
+      ['dynamic-brick', 'DYNAMIC_BRICK_'],
+      ['canvas', 'CANVAS_'],
+      ['generator', 'GENERATOR_'],
+      ['data', 'PROPERTY_BANK_DATA_NODE_'],
+      ['switch', 'BRICK_STATE_GROUP_'],
+      ['property_bank_command', 'PROPERTY_BANK_COMMAND_NODE_'],
+      ['property_bank_calc', 'PROPERTY_BANK_COMMAND_MAP_'],
+      ['automation_map', 'AUTOMATION_MAP_'],
+      ['test', 'TEST_'],
+      ['test_case', 'TEST_CASE_'],
+      ['test_var', 'TEST_VAR_'],
+    ]
+
+    test.each(cases)('produces %p prefix', (type, prefix) => {
+      expect(makeId(type)).toMatch(new RegExp(`^${prefix}${UUID}$`))
+    })
+
+    test('returns unique random uuids across calls', () => {
+      expect(makeId('brick')).not.toBe(makeId('brick'))
+    })
+
+    test('unknown type falls through to an unprefixed uuid', () => {
+      expect(makeId('not-a-real-type')).toMatch(UUID_ONLY_RE)
+    })
+  })
+
+  describe('subspace', () => {
+    test('throws because subspace IDs must be fixed', () => {
+      expect(() => makeId('subspace')).toThrow(/subspace is not supported/)
+    })
+  })
+
+  describe('snapshotMode', () => {
+    test('produces sequential, deterministic uuids', () => {
+      const a = makeId('brick', { snapshotMode: true })
+      const b = makeId('brick', { snapshotMode: true })
+      expect(a).toMatch(/^BRICK_00000000-0000-0000-0000-\d{12}$/)
+      expect(b).toMatch(/^BRICK_00000000-0000-0000-0000-\d{12}$/)
+      expect(Number(b.slice(-12))).toBe(Number(a.slice(-12)) + 1)
+    })
+
+    test('snapshotMode false falls back to random uuid', () => {
+      const id = makeId('canvas', { snapshotMode: false })
+      expect(id).toMatch(new RegExp(`^CANVAS_${UUID}$`))
+      expect(id).not.toMatch(/CANVAS_00000000-0000-0000-0000-/)
+    })
+  })
+})

package/utils/data.ts

@@ -86,7 +86,7 @@ type SystemDataInfo = {
   name: SystemDataName
   id: string
   type: 'string' | 'number' | 'bool' | 'array' | 'object' | 'any'
-  title: string
+  title?: string
   description?: string
   schema?: object
   value?: any

package/utils/event-props.ts

@@ -141,6 +141,11 @@ export const templateEventPropsMap = {
       BRICK_MAPS_REGION_LONGITUDE_DELTA: 'number',
     },
   },
+  Sketch: {
+    onStrokeEnd: { BRICK_SKETCH_STROKE_COUNT: 'number' },
+    onToolChange: { BRICK_SKETCH_TOOL: 'string' },
+    onExportImage: { BRICK_SKETCH_IMAGE_URI: 'string' },
+  },
   Tick: {
     ticking: { GENERATOR_TICK_COUNTDOWN: 'number', GENERATOR_TICK_VALUE: 'any' },
     completed: { GENERATOR_TICK_COUNTDOWN: 'number', GENERATOR_TICK_VALUE: 'any' },
@@ -598,6 +603,7 @@ export const templateEventPropsMap = {
     onError: { GENERATOR_SPEECH_INFERENCE_ERROR: 'string' },
     onTranscribed: {
       GENERATOR_SPEECH_INFERENCE_TRANSCRIBE_RESULT: 'string',
+      GENERATOR_SPEECH_INFERENCE_TRANSCRIBE_LANGUAGE: 'string',
       GENERATOR_SPEECH_INFERENCE_TRANSCRIBE_START_TIME: 'number',
       GENERATOR_SPEECH_INFERENCE_TRANSCRIBE_END_TIME: 'number',
       GENERATOR_SPEECH_INFERENCE_TRANSCRIBE_TIME: 'number',
@@ -619,10 +625,11 @@ export const templateEventPropsMap = {
   RealtimeTranscription: {
     onTranscribe: {
       GENERATOR_REALTIME_TRANSCRIPTION_TRANSCRIBE_EVENT:
-        '{ type?: string sliceIndex?: number isCapturing?: boolean data?: { result?: string [key: string]: any } vadEvent?: { type?: string confidence?: number duration?: number sliceIndex?: number timestamp?: number [key: string]: any } [key: string]: any }',
+        '{ type?: string sliceIndex?: number isCapturing?: boolean data?: { result?: string language?: string [key: string]: any } vadEvent?: { type?: string confidence?: number duration?: number sliceIndex?: number timestamp?: number [key: string]: any } [key: string]: any }',
       GENERATOR_REALTIME_TRANSCRIPTION_TRANSCRIBE_TYPE: 'string',
       GENERATOR_REALTIME_TRANSCRIPTION_TRANSCRIBE_SLICE_INDEX: 'number',
       GENERATOR_REALTIME_TRANSCRIPTION_TRANSCRIBE_RESULT_TEXT: 'string',
+      GENERATOR_REALTIME_TRANSCRIPTION_TRANSCRIBE_LANGUAGE: 'string',
       GENERATOR_REALTIME_TRANSCRIPTION_TRANSCRIBE_IS_CAPTURING: 'boolean',
       GENERATOR_REALTIME_TRANSCRIPTION_VAD_EVENT:
         '{ type?: string confidence?: number duration?: number sliceIndex?: number timestamp?: number [key: string]: any }',
@@ -644,10 +651,13 @@ export const templateEventPropsMap = {
       GENERATOR_REALTIME_TRANSCRIPTION_STATS:
         '{ type?: string timestamp?: number data?: { [key: string]: any } [key: string]: any }',
     },
-    onStabilized: { GENERATOR_REALTIME_TRANSCRIPTION_STABILIZED_TEXT: 'string' },
+    onStabilized: {
+      GENERATOR_REALTIME_TRANSCRIPTION_STABILIZED_TEXT: 'string',
+      GENERATOR_REALTIME_TRANSCRIPTION_STABILIZED_LANGUAGE: 'string',
+    },
     onEnd: {
       GENERATOR_REALTIME_TRANSCRIPTION_END_RESULTS:
-        'Array<{ transcribeEvent?: { type?: string sliceIndex?: number isCapturing?: boolean data?: { result?: string [key: string]: any } vadEvent?: { type?: string confidence?: number duration?: number sliceIndex?: number timestamp?: number [key: string]: any } [key: string]: any } vadEvent?: { type?: string confidence?: number duration?: number sliceIndex?: number timestamp?: number [key: string]: any } [key: string]: any }>',
+        'Array<{ transcribeEvent?: { type?: string sliceIndex?: number isCapturing?: boolean data?: { result?: string language?: string [key: string]: any } vadEvent?: { type?: string confidence?: number duration?: number sliceIndex?: number timestamp?: number [key: string]: any } [key: string]: any } vadEvent?: { type?: string confidence?: number duration?: number sliceIndex?: number timestamp?: number [key: string]: any } [key: string]: any }>',
       GENERATOR_REALTIME_TRANSCRIPTION_END_AUDIO_OUTPUT_PATH: 'string',
     },
   },