@fugood/bricks-ctor 2.25.0-beta.5 → 2.25.0-beta.51

package/compile/index.ts

@@ -6,10 +6,14 @@ import omit from 'lodash/omit'
 import { parse as parseAST } from 'acorn'
 import type { ExportNamedDeclaration, FunctionDeclaration } from 'acorn'
 import escodegen from 'escodegen'
-import { makeId } from '../utils/id'
+import { makeSeededId } from '../utils/id'
 import { generateCalulationMap } from './util'
 import { templateActionNameMap } from './action-name-map'
 import { templateEventPropsMap } from '../utils/event-props'
+import { sh } from '../tools/_shell'
+import { computeConfigChange, readBuildConfig } from './config-diff'
+import { appendEditRecord, editProvenance } from '../tools/_edits-log'
+import { isTruthyEnv } from '../tools/mcp-env'
 import type {
   Application,
   Data,
@@ -154,11 +158,13 @@ const basicAnimationEvents = ['show', 'standby', 'breatheStart']
 
 const compileAnimations = (
   templateKey: string,
-  animations: { [key: string]: Animation },
+  animations: { [key: string]: Animation | (() => Animation) },
   errorReference: string,
 ) =>
   Object.entries(animations).reduce((acc, [key, animation]) => {
-    const animationId = assertEntryId(animation?.id, 'ANIMATION', errorReference)
+    // Animation events accept either a direct Animation or a getter; unwrap.
+    const resolved = typeof animation === 'function' ? animation() : animation
+    const animationId = assertEntryId(resolved?.id, 'ANIMATION', errorReference)
     acc[convertEventKey(basicAnimationEvents.includes(key) ? 'BRICK' : templateKey, key)] =
       `ANIMATION#${animationId}`
     return acc
@@ -179,10 +185,17 @@ const compileEvents = (
 
       let handlerKey
       let handlerTemplateKey
-      if (handler === 'system' || typeof handler === 'string') {
-        if (handler.startsWith('SUBSPACE_')) handlerKey = handler
-        else handlerKey = handler.toUpperCase()
-        if (handlerKey === 'SYSTEM') handlerTemplateKey = 'SYSTEM'
+      if (typeof handler === 'string') {
+        // Only the literal 'system' handler is normalized to the SYSTEM template key.
+        // SubspaceID (SUBSPACE_*) and ItemBrickID handlers are kept verbatim: the runtime
+        // resolves them case-sensitively (see mapEventMapHandlersWithNewId), so uppercasing
+        // a mixed-case ItemBrickID would break handler-to-item event wiring.
+        if (handler === 'system') {
+          handlerKey = 'SYSTEM'
+          handlerTemplateKey = 'SYSTEM'
+        } else {
+          handlerKey = handler
+        }
       } else if (typeof handler === 'function') {
         let instance = handler()
         if (instance?.id) {
@@ -301,6 +314,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']) => ({
@@ -324,9 +493,12 @@ const preloadTypes = [
   'media-resource-audio',
   'media-resource-file',
   'lottie-file-uri',
+  'rive-file-uri',
   'ggml-model-asset',
   'gguf-model-asset',
   'binary-asset',
+  'mlx-model-asset',
+  'scene3d-objects',
 ]
 
 const compileKind = (kind: Data['kind']) => {
@@ -353,9 +525,10 @@ const compileKind = (kind: Data['kind']) => {
 }
 
 const compileRemoteUpdate = (remoteUpdate: Data['remoteUpdate']) => {
-  if (!remoteUpdate) return {}
-  if (remoteUpdate.type === 'auto') return { enable_remote_update: true }
+  if (!remoteUpdate) return { bank_type: 'none' }
+  if (remoteUpdate.type === 'auto') return { bank_type: 'create', enable_remote_update: true }
   return {
+    bank_type: remoteUpdate.type === 'device-specific' ? 'create-device-specific' : 'global',
     enable_remote_update: true,
     ...(remoteUpdate.type === 'device-specific' ? { use_remote_id_prefix: true } : {}),
     ...(remoteUpdate.type === 'global-data' ? { global_remote_update_prop: remoteUpdate.id } : {}),
@@ -411,7 +584,7 @@ function compileRunArray(run: unknown[]): unknown[] {
 /**
  * Compile typed TestCase to raw format (strips __typename)
  */
-const compileTestCase = (testCase: TestCase) => ({
+export const compileTestCase = (testCase: TestCase) => ({
   id: testCase.id,
   name: testCase.name,
   hide_short_ref: testCase.hideShortRef,
@@ -433,7 +606,10 @@ const compileTestCase = (testCase: TestCase) => ({
       variable: cond.variable,
       operator: cond.operator,
       value: cond.value,
-      jump_to: cond.jump_to,
+      // `jump_to` may be a getter (() => TestCase) for dynamic case ids (the project generator
+      // emits this form). Resolve it to its id like the `run` array does — otherwise the function
+      // is JSON-serialized to nothing and the conditional jump silently vanishes from the config.
+      jump_to: compileRunElement(cond.jump_to),
     }
   }),
 })
@@ -485,6 +661,7 @@ const compileAutomationTest = (
 
   return {
     id: testId,
+    alias: test.alias,
     title: test.title,
     hide_short_ref: test.hideShortRef,
     timeout: test.timeout,
@@ -538,8 +715,38 @@ const compileAutomation = (automationMap: AutomationMap) =>
     }),
   )
 
+// Record the minimal compiled-config delta this compile produced to the shared audit
+// log (`.bricks/edits.jsonl`), so editing files directly and running `bun compile`
+// leaves the same trail as the MCP source-editing tools. Maintained only in the
+// editing-tools context (`BRICKS_CTOR_ENABLE_EDITING_TOOLS`); the source-editing tools
+// turn it off for their verify compiles (see _verify.ts) so a tool edit records one
+// richer entry instead of an extra generic compile entry. Also silent when there is no
+// prior build to diff against (fresh projects, package tests, tooling outside a project).
+const recordConfigChange = async (previousConfig: unknown, config: unknown) => {
+  if (previousConfig == null) return
+  if (!isTruthyEnv(process.env.BRICKS_CTOR_ENABLE_EDITING_TOOLS)) return
+  // The baseline was parsed from JSON; `computeConfigChange` applies the same
+  // JSON-omitted-field rules lazily so compile avoids cloning the full config.
+  const change = computeConfigChange(previousConfig, config)
+  if (change.status !== 'ok') return
+  await appendEditRecord(process.cwd(), {
+    ts: new Date().toISOString(),
+    tool: 'compile',
+    provenance: editProvenance(),
+    outcome: 'ok',
+    summary:
+      change.opCount === 0
+        ? 'compile: no config change'
+        : `compile: ${change.opCount} config op(s)`,
+    configChange: change,
+  }).catch(() => undefined)
+}
+
 export const compile = async (app: Application) => {
   await new Promise((resolve) => setImmediate(resolve, 0))
+  // Snapshot the prior build artifact before the caller's compile.ts overwrites it, so
+  // the config change introduced by this compile can be recorded on return.
+  const previousConfig = await readBuildConfig(process.cwd())
   const timestamp = Date.now()
   // Pre-index subspace ids so the canvas-item validation below stays O(1).
   const subspaceIdSet = new Set(app.subspaces.map((s) => s.id))
@@ -559,7 +766,14 @@ export const compile = async (app: Application) => {
       // validation (root_canvas_id is required before the conditional
       // schema fix is published).
       if (subspace.module?.link) {
-        const placeholderCanvasId = makeId('canvas')
+        // Seed the placeholder id from the (stable) subspace id. `makeId('canvas')` would take
+        // the count-fallback branch (a process-global counter that is never reset), so the
+        // placeholder id depended on how many prior count-fallback ids had been minted — making
+        // it differ between recompiles and breaking compile's byte-stable-output contract
+        // (phantom config-change ops). `makeSeededId` keeps no global state, so identical source
+        // recompiles to an identical id. (`makeId('canvas', alias)` would instead throw
+        // "Duplicate makeId alias" on the second compile in a long-lived process.)
+        const placeholderCanvasId = makeSeededId('canvas', `${subspaceId}:module-placeholder`)
         subspaceMap[subspaceId] = {
           title: subspace.title,
           description: subspace.description,
@@ -629,39 +843,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
         }, {}),
@@ -1009,7 +1247,7 @@ export const compile = async (app: Application) => {
             ...compileRemoteUpdate(data.remoteUpdate),
             routing: data.routing,
             schema: data.schema,
-            type: data.type,
+            type: data.type === 'boolean' ? 'bool' : data.type,
             ...compileKind(data.kind),
             value: compileProperty(data.value, `(data: ${dataId}, subspace ${subspaceId})`),
             event_map: compileEvents('PROPERTY_BANK', data.events || {}, {
@@ -1029,6 +1267,7 @@ export const compile = async (app: Application) => {
           )
 
           const calc: any = {
+            alias: dataCalc.alias,
             title: dataCalc.title,
             description: dataCalc.description,
             hide_short_ref: dataCalc.hideShortRef,
@@ -1227,12 +1466,7 @@ export const compile = async (app: Application) => {
                 : null,
             }
 
-            Object.assign(
-              calc,
-              generateCalulationMap(calc.script_config, {
-                snapshotMode: process.env.BRICKS_SNAPSHOT_MODE === '1',
-              }),
-            )
+            Object.assign(calc, generateCalulationMap(calc.script_config, dataCalcId))
           }
           map[dataCalcId] = calc
           return map
@@ -1269,10 +1503,20 @@ export const compile = async (app: Application) => {
     automation_map: compiledAutomationMap || app.metadata?.TEMP_automation_map || {},
     update_timestamp: timestamp,
   }
+  await recordConfigChange(previousConfig, config)
   return config
 }
 
 export const checkConfig = async (configPath: string) => {
-  const { sh } = await import('../tools/_shell')
-  await sh`bricks app check-config ${configPath}`
+  // --validate-automation surfaces broken automation_map / test_map refs early,
+  // which catches agent-authored automations that reference deleted bricks.
+  await sh`bricks app check-config --validate-automation ${configPath}`
+  // Doctor adds semantic lint checks after structural validation. Warnings are
+  // surfaced in the compile log, but only errors fail by default. Older published
+  // bricks-cli builds lack `app doctor` — skip rather than fail the compile.
+  const doctor = await sh`bricks app doctor --validate-automation ${configPath}`.nothrow()
+  if (doctor.exitCode !== 0) {
+    if (/unknown command/i.test(doctor.stderr?.toString() ?? '')) return
+    throw new Error(`bricks app doctor failed with exit ${doctor.exitCode}`)
+  }
 }

package/compile/util.ts

@@ -1,4 +1,4 @@
-import { makeId } from '../utils/id'
+import { makeSeededId } from '../utils/id'
 
 type ScriptConfig = {
   title?: string
@@ -18,30 +18,54 @@ const errorMsg = 'Not allow duplicate set property id between inputs / outputs /
 export const validateConfig = (config: ScriptConfig) => {
   // Skip input/output overlap validation in manual mode (allows same data node in both)
   if (config.trigger_mode === 'manual') return
-  if (config.error && config.inputs[config.error]) {
+  // `inputs` is keyed by data-node id with the OBJECT_SET path as the *value*. The overlap
+  // check is "is this id also an input?" — a key-existence question — so test key presence,
+  // not the path's truthiness. An empty path ('' = OBJECT_SET's default "set whole object")
+  // is a legitimate input value that would otherwise slip the overlap guard.
+  const isInput = (id: string) => Object.prototype.hasOwnProperty.call(config.inputs, id)
+  if (config.error && isInput(config.error)) {
     throw new Error(`${errorMsg}. key: error`)
   }
-  if (config.output && config.inputs[config.output]) {
+  if (config.output && isInput(config.output)) {
     throw new Error(`${errorMsg}. key: output`)
   }
-  if (Object.values(config.outputs).some((value) => value.some((id) => config.inputs[id]))) {
+  if (Object.values(config.outputs).some((value) => value.some(isInput))) {
     throw new Error(`${errorMsg}. key: outputs`)
   }
+  // The same data-node id reused across the output-side targets (output / error / outputs)
+  // also collides: generateCalulationMap spreads their node objects last-wins, so the later
+  // one silently overwrites the earlier wiring (e.g. error == output drops the error change
+  // link). The checks above only compare against `inputs`, so guard the output-side pairs
+  // too. (The same id appearing in multiple `outputs` entries is a supported last-wins case
+  // and stays allowed.)
+  if (config.error && config.output && config.error === config.output) {
+    throw new Error(`${errorMsg}. key: error/output`)
+  }
+  const outputsIds = Object.values(config.outputs).flat()
+  if (config.output && outputsIds.includes(config.output)) {
+    throw new Error(`${errorMsg}. key: output/outputs`)
+  }
+  if (config.error && outputsIds.includes(config.error)) {
+    throw new Error(`${errorMsg}. key: error/outputs`)
+  }
 }
 
 const padding = 15
 const layerXInterval = 300
 const layerYInterval = 150
 
-export const generateCalulationMap = (config: ScriptConfig, opts?: { snapshotMode?: boolean }) => {
+// `calcId` (the owning script calc's stable id) seeds every derived command-node id, so an
+// unchanged calc recompiles to identical ids and editing one calc never shifts another's —
+// keeping the compiled config byte-stable for change detection. See makeSeededId in utils/id.
+export const generateCalulationMap = (config: ScriptConfig, calcId: string) => {
   validateConfig(config)
-  const sandboxId = makeId('property_bank_command', opts)
-  const sandboxErrorId = makeId('property_bank_command', opts)
-  const sandboxResultId = makeId('property_bank_command', opts)
+  const sandboxId = makeSeededId('property_bank_command', `${calcId}:sandbox-run`)
+  const sandboxErrorId = makeSeededId('property_bank_command', `${calcId}:sandbox-error`)
+  const sandboxResultId = makeSeededId('property_bank_command', `${calcId}:sandbox-result`)
 
   const inputs = Object.entries(config.inputs).reduce(
     (acc, [key, value], index) => {
-      const commandId = makeId('property_bank_command', opts)
+      const commandId = makeSeededId('property_bank_command', `${calcId}:input:${key}`)
       acc.map[key] = {
         type: 'data-node',
         properties: {},
@@ -123,7 +147,7 @@ export const generateCalulationMap = (config: ScriptConfig, opts?: { snapshotMod
   let y = 0
   const outputs = Object.entries(config.outputs).reduce(
     (acc, [key, pbList], index) => {
-      const commandId = makeId('property_bank_command', opts)
+      const commandId = makeSeededId('property_bank_command', `${calcId}:output:${key}`)
       acc.commandIdList.push(commandId)
       acc.map[commandId] = {
         type: 'command-node-object',

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@fugood/bricks-ctor",
-  "version": "2.25.0-beta.5",
+  "version": "2.25.0-beta.51",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun scripts/build.js"
   },
   "dependencies": {
-    "@fugood/bricks-cli": "^2.25.0-beta.5",
+    "@babel/generator": "7.28.5",
+    "@babel/parser": "7.28.5",
+    "@babel/traverse": "7.28.5",
+    "@babel/types": "7.28.5",
+    "@fugood/bricks-cli": "^2.25.0-beta.51",
     "@huggingface/gguf": "^0.3.2",
     "@iarna/toml": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.15.0",
@@ -25,5 +29,5 @@
   "peerDependencies": {
     "oxfmt": "^0.36.0"
   },
-  "gitHead": "ff0abf1f06694c6d71a1a14ac52c37f9a72d1ac3"
+  "gitHead": "9a6ddecabc4a2e11fc6ae9a256de730cd3d744ca"
 }

package/skills/bricks-ctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bricks-ctor
-description: Advanced BRICKS configuration knowledge. Covers Standby Transition, Automations (E2E testing), Data Calculation (JS sandbox libraries), Local Sync, Remote Data Bank, Media Flow, and Buttress (remote inference). Triggers on multi-device sync, cloud data, media assets, AI offloading, E2E testing, or canvas transitions.
+description: Advanced BRICKS configuration knowledge. Covers Standby Transition, Automations (E2E testing), Data Calculation (JS sandbox libraries), Local Sync, Remote Data Bank, Media Flow, Buttress (remote inference), and the verification toolchain (compile, harness-specific preview tool, on-device DevTools, definition-of-done gate). Triggers on multi-device sync, cloud data, media assets, AI offloading, E2E testing, canvas transitions, or verifying project work before declaring done.
 ---
 
 # BRICKS Ctor - Advanced Features
@@ -11,22 +11,28 @@ This skill covers advanced BRICKS features not in the main project instructions.
 
 | Rule | Description |
 |------|-------------|
-| [Architecture Patterns](rules/architecture-patterns.md) | **Read first** — decompose flows and select patterns |
-| [Animation](rules/animation.md) | Animation system for brick transforms and opacity |
-| [Standby Transition](rules/standby-transition.md) | Canvas enter/exit animations |
-| [Automations](rules/automations.md) | E2E testing and scheduled tasks |
-| [Data Calculation](rules/data-calculation.md) | JS sandbox libraries (25+ available) |
-| [Local Sync](rules/local-sync.md) | LAN device synchronization |
-| [Remote Data Bank](rules/remote-data-bank.md) | Cloud data sync and API access |
-| [Media Flow](rules/media-flow.md) | Media asset management |
-| [Buttress](rules/buttress.md) | Remote inference for AI generators |
+| [Architecture Patterns](references/architecture-patterns.md) | **Read first** — decompose flows and select patterns |
+| [Source-Editing Tools](references/source-editing-tools.md) | MCP tools for editing entries and data-calcs by AST (new/edit/remove, value grammar, verify) |
+| [Animation](references/animation.md) | Animation system for brick transforms and opacity |
+| [Standby Transition](references/standby-transition.md) | Canvas enter/exit animations |
+| [Automations](references/automations.md) | E2E testing and scheduled tasks |
+| [Data Calculation](references/data-calculation.md) | Wiring contract, trigger semantics, JS sandbox (25+ libraries) |
+| [Local Sync](references/local-sync.md) | LAN device synchronization |
+| [Remote Data Bank](references/remote-data-bank.md) | Cloud data sync and API access |
+| [Media Flow](references/media-flow.md) | Media asset management |
+| [Buttress](references/buttress.md) | Remote inference for AI generators |
+| [Verification Toolchain](references/verification-toolchain.md) | Definition of done, compile, preview tool selection, on-device DevTools, Path 1/2/3 decision rule |
+| [Simulator](references/simulator.md) | Path 1 fidelity — Simulator feature support, fallbacks (Camera/LLM/STT/Vector Store, Buttress disabled), when a green run is enough vs. Path 2 |
 
 ## Quick Reference
 
-- **Complex flows**: See [Architecture Patterns](rules/architecture-patterns.md) for decomposing multi-step workflows
-- **Multi-device**: See [Local Sync](rules/local-sync.md) for LAN coordination
-- **Cloud data**: See [Remote Data Bank](rules/remote-data-bank.md) for sync and API access
-- **Media assets**: See [Media Flow](rules/media-flow.md) for centralized asset management
-- **AI offloading**: See [Buttress](rules/buttress.md) for GPU server delegation
-- **E2E testing**: See [Automations](rules/automations.md) for test automation
-- **Enter animations**: See [Standby Transition](rules/standby-transition.md) for canvas transitions
+- **Complex flows**: See [Architecture Patterns](references/architecture-patterns.md) for decomposing multi-step workflows
+- **Editing entries/data-calcs**: See [Source-Editing Tools](references/source-editing-tools.md) — prefer the MCP editing tools over hand-editing `subspaces/**`
+- **Multi-device**: See [Local Sync](references/local-sync.md) for LAN coordination
+- **Cloud data**: See [Remote Data Bank](references/remote-data-bank.md) for sync and API access
+- **Media assets**: See [Media Flow](references/media-flow.md) for centralized asset management
+- **AI offloading**: See [Buttress](references/buttress.md) for GPU server delegation
+- **E2E testing**: See [Automations](references/automations.md) for test automation
+- **Enter animations**: See [Standby Transition](references/standby-transition.md) for canvas transitions
+- **Verification before done**: See [Verification Toolchain](references/verification-toolchain.md) for the definition-of-done gate and Path 1/2/3 decision rule
+- **Simulator fidelity**: See [Simulator](references/simulator.md) for what the Simulator fakes (Camera, AI generators, Buttress) and when to escalate to a real device

package/skills/bricks-ctor/{rules → references}/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.