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

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 } : {}),
@@ -485,6 +658,7 @@ const compileAutomationTest = (
 
   return {
     id: testId,
+    alias: test.alias,
     title: test.title,
     hide_short_ref: test.hideShortRef,
     timeout: test.timeout,
@@ -538,8 +712,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 +763,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 +840,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 +1244,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 +1264,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 +1463,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 +1500,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
@@ -27,21 +27,40 @@ export const validateConfig = (config: ScriptConfig) => {
   if (Object.values(config.outputs).some((value) => value.some((id) => config.inputs[id]))) {
     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 +142,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.50",
   "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.50",
     "@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": "3614445cd0166e40634f69c6238299bb63f4f597"
 }

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.
 

package/skills/bricks-ctor/{rules → references}/architecture-patterns.md

@@ -26,10 +26,18 @@ The primary way to orchestrate multi-step flows. A single event can contain an a
 - Use `dataParams` + `mapping` to pass event data downstream
 - This is the "glue" that wires generators, state, and UI together
 
+Sequential `PROPERTY_BANK` / `PROPERTY_BANK_EXPRESSION` actions in one chain read the data values that existed when the chain started. If a later action needs to read what an earlier action wrote, set `waitAsync: true` on the earlier action.
+
 ### System Actions (Priority 3)
 Built-in commands for direct state and UI changes.
 - **PROPERTY_BANK**: set data value
 - **PROPERTY_BANK_EXPRESSION**: inline JS expression for simple compute
+  - The expression engine folds statements into a single expression: only expression
+    statements, simple `const`/`let` declarations, and a final return/expression are
+    supported — **no `if`/`for`/`while`/`switch`** (use ternaries). The same limit
+    applies inside a zero-arg IIFE body. Unsupported statements fail at runtime with
+    the error visible only in a DevTools session, so prefer ternary chains or move the
+    logic to a DataCalculationScript.
 - **CHANGE_CANVAS**: navigate to another canvas
 - **DYNAMIC_ANIMATION**: trigger animation
 - **ALERT / MESSAGE**: system feedback
@@ -67,3 +75,13 @@ Only actual data derivation maps to Data Calculation:
 
 ### Step 4: Wire with Event Action Chains
 Connect the pieces through events on generators and bricks.
+
+## Recipe: user-driven state machine (calculator, form wizard, picker)
+
+A brief like "state vars X, Y, Z; button A updates X from X+Y; button B resets" is a state machine. The shape:
+
+- Each state variable is its own `Data` entity. Displays read it via `linkData(() => data.dFoo)`.
+- Each button's `onPress` is an Event Action Chain. For every state var that changes, append one `PROPERTY_BANK_EXPRESSION` whose `expression` reads the current state and returns the new value.
+- Use `Data Calculation` only for reusable pure derivations referenced as inputs to those expressions.
+
+A 10-button calculator with 4 state vars is ~10 small chains of 1–4 inline expressions. If you find yourself writing a single auto-mode `DataCalculationScript` that consumes all state vars and emits all-new state through mirror `dFooResult` data — or pinging a `dLastInput` field to force an auto calc to re-run — the chain shape was the right answer.

package/skills/bricks-ctor/{rules → references}/automations.md

@@ -118,6 +118,16 @@ const testLoginFlow: AutomationTest = {
 | `match_screenshot`           | `[name, threshold?, maxRetry?]`                  | Screenshot compare   |
 | `delay`                      | `[subspace?, property?, defaultValue?]`          | Delay execution      |
 
+In project TypeScript source, pass entity getters for BRICKS entities:
+
+```typescript
+run: ['brick_press', () => mainSubspace, () => bricks.bSubmitButton]
+run: ['wait_until_canvas_change', () => mainSubspace, () => canvases.cDone, 5000]
+run: ['assert_property', () => mainSubspace, () => data.dStep, 'done']
+```
+
+The compiler resolves these getters to the current generated IDs.
+
 ### execute_action Params
 
 The `params` object in `execute_action` uses **runtime event property keys** from `event-props.ts`, NOT the action config `input` names from type definitions.
@@ -208,6 +218,7 @@ Automations work with Modules. Use Manual Run in Preview mode for module testing
 
 - **Automation map key**: Always use `'AUTOMATION_MAP_DEFAULT'` as the automation map ID (not `makeId()`). The preview test runner reads from `automationMap['AUTOMATION_MAP_DEFAULT']?.map`.
 - **Valid makeId types**: Use `'test'` for AutomationTest, `'test_case'` for TestCase, `'test_var'` for TestVariable. Do NOT use `'automation_test'` or `'automation_test_map'`.
+- **Entity references in run arrays**: Use getter references (`() => subspace`, `() => bricks.bButton`, `() => data.dValue`) in TypeScript source so compile resolves fresh IDs.
 - **handler in execute_action**: Pass the entity's `.id` string (e.g., `bricks.bInput.id`), not a getter function.
 
 ## Best Practices