@fugood/bricks-ctor 2.24.1 → 2.24.3

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.24.1",
+  "version": "2.24.3",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun scripts/build.js"
   },
   "dependencies": {
-    "@fugood/bricks-cli": "^2.24.1",
+    "@fugood/bricks-cli": "^2.24.3",
     "@huggingface/gguf": "^0.3.2",
     "@iarna/toml": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.15.0",
@@ -24,6 +24,5 @@
   },
   "peerDependencies": {
     "oxfmt": "^0.36.0"
-  },
-  "gitHead": "b424a8d24a5dc09ad69bf2242e021e6315379bf2"
+  }
 }

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)