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

package/compile/__tests__/util.test.js

@@ -0,0 +1,317 @@
+import { generateCalulationMap, validateConfig } from '../util'
+
+const baseConfig = (overrides = {}) => ({
+  inputs: {},
+  enable_async: false,
+  disabled_triggers: {},
+  output: null,
+  outputs: {},
+  error: null,
+  code: 'return inputs',
+  ...overrides,
+})
+
+const SANDBOX_PREFIX = 'PROPERTY_BANK_COMMAND_NODE_'
+
+const sandboxNodeIds = (map) =>
+  Object.entries(map)
+    .filter(([id, node]) => id.startsWith(SANDBOX_PREFIX) && node.type === 'command-node-sandbox')
+    .map(([id, node]) => ({ id, command: node.properties.command }))
+
+const findSandboxIds = (map) => {
+  const sandbox = sandboxNodeIds(map)
+  return {
+    run: sandbox.find((s) => s.command === 'SANDBOX_RUN_JAVASCRIPT')?.id,
+    error: sandbox.find((s) => s.command === 'SANDBOX_GET_ERROR')?.id,
+    result: sandbox.find((s) => s.command === 'SANDBOX_GET_RETURN_VALUE')?.id,
+  }
+}
+
+describe('validateConfig', () => {
+  test('returns without throwing for a clean config', () => {
+    expect(() => validateConfig(baseConfig({ inputs: { a: 'foo' } }))).not.toThrow()
+  })
+
+  test('skips overlap checks in manual trigger mode', () => {
+    const config = baseConfig({
+      trigger_mode: 'manual',
+      inputs: { a: 'foo' },
+      output: 'a',
+      error: 'a',
+      outputs: { x: ['a'] },
+    })
+    expect(() => validateConfig(config)).not.toThrow()
+  })
+
+  test('throws when error key collides with an input id', () => {
+    const config = baseConfig({ inputs: { a: 'foo' }, error: 'a' })
+    expect(() => validateConfig(config)).toThrow(/key: error/)
+  })
+
+  test('throws when output key collides with an input id', () => {
+    const config = baseConfig({ inputs: { a: 'foo' }, output: 'a' })
+    expect(() => validateConfig(config)).toThrow(/key: output/)
+  })
+
+  test('throws when any outputs entry references an input id', () => {
+    const config = baseConfig({
+      inputs: { a: 'foo', b: 'bar' },
+      outputs: { x: ['c', 'b'] },
+    })
+    expect(() => validateConfig(config)).toThrow(/key: outputs/)
+  })
+
+  test('does not throw when error/output are falsy and inputs are empty', () => {
+    expect(() => validateConfig(baseConfig())).not.toThrow()
+  })
+
+  test('throws when error and output target the same id', () => {
+    const config = baseConfig({ output: 'shared', error: 'shared' })
+    expect(() => validateConfig(config)).toThrow(/key: error\/output/)
+  })
+
+  test('throws when output collides with an outputs target id', () => {
+    const config = baseConfig({ output: 'shared', outputs: { x: ['shared'] } })
+    expect(() => validateConfig(config)).toThrow(/key: output\/outputs/)
+  })
+
+  test('throws when error collides with an outputs target id', () => {
+    const config = baseConfig({ error: 'shared', outputs: { x: ['shared'] } })
+    expect(() => validateConfig(config)).toThrow(/key: error\/outputs/)
+  })
+
+  // The same id reused across *different* outputs entries is a supported last-wins case
+  // (see generateCalulationMap test below) and must stay allowed.
+  test('allows the same id across multiple outputs entries', () => {
+    const config = baseConfig({ outputs: { first: ['pb1'], second: ['pb1'] } })
+    expect(() => validateConfig(config)).not.toThrow()
+  })
+})
+
+// generateCalulationMap now seeds command ids from the owning calc id; tests that don't
+// assert id values share one fixed id (ids stay deterministic with no global state).
+const CALC_ID = 'PROPERTY_BANK_COMMAND_MAP_00000000-0000-4000-8000-000000000000'
+const genMap = (config, calcId = CALC_ID) => generateCalulationMap(config, calcId)
+
+describe('generateCalulationMap', () => {
+  test('produces only the three sandbox nodes for an empty config', () => {
+    const result = genMap(baseConfig())
+
+    expect(Object.keys(result.map)).toHaveLength(3)
+    const { run, error, result: returnValue } = findSandboxIds(result.map)
+
+    expect(result.map[run].in.inputs).toEqual([])
+    expect(result.map[error].out.result).toEqual([])
+    expect(result.map[returnValue].out.result).toEqual([])
+    expect(Object.keys(result.editor_info)).toHaveLength(3)
+  })
+
+  test('chains multiple inputs through OBJECT_SET commands', () => {
+    const result = genMap(baseConfig({ inputs: { a: 'foo.bar', b: 'baz' } }))
+
+    const { run } = findSandboxIds(result.map)
+
+    // Each input gets a data-node + an OBJECT_SET command-node.
+    expect(result.map.a.type).toBe('data-node')
+    expect(result.map.b.type).toBe('data-node')
+
+    const aCommandId = result.map.a.out.value[0].id
+    const bCommandId = result.map.b.out.value[0].id
+    expect(aCommandId).not.toBe(bCommandId)
+
+    const aCmd = result.map[aCommandId]
+    const bCmd = result.map[bCommandId]
+    expect(aCmd.properties.command).toBe('OBJECT_SET')
+    expect(aCmd.properties.args.path).toBe('foo.bar')
+    expect(bCmd.properties.command).toBe('OBJECT_SET')
+    expect(bCmd.properties.args.path).toBe('baz')
+
+    // First command has no upstream obj; second command's obj input is the first command.
+    expect(aCmd.in.obj).toBeNull()
+    expect(bCmd.in.obj).toEqual([{ id: aCommandId, port: 'result' }])
+    // First command forwards its result to the second command's `obj` input.
+    expect(aCmd.out.result).toEqual([{ id: bCommandId, port: 'obj' }])
+    // The last command feeds the SANDBOX_RUN_JAVASCRIPT `inputs` port.
+    expect(bCmd.out.result).toEqual([{ id: run, port: 'inputs' }])
+    expect(result.map[run].in.inputs).toEqual([{ id: bCommandId, port: 'result' }])
+  })
+
+  test('builds OBJECT_GET commands and target data-nodes for outputs', () => {
+    const result = genMap(baseConfig({ outputs: { resultPath: ['pb1', 'pb2'] } }))
+
+    const { result: returnValue } = findSandboxIds(result.map)
+
+    // Both target property-bank nodes are created as data-nodes.
+    expect(result.map.pb1.type).toBe('data-node')
+    expect(result.map.pb2.type).toBe('data-node')
+
+    // The SANDBOX_GET_RETURN_VALUE forwards to the OBJECT_GET command for the output entry.
+    const objectGetRefs = result.map[returnValue].out.result
+    expect(objectGetRefs).toHaveLength(1)
+    const getCommandId = objectGetRefs[0].id
+    expect(objectGetRefs[0].port).toBe('obj')
+
+    const getCmd = result.map[getCommandId]
+    expect(getCmd.type).toBe('command-node-object')
+    expect(getCmd.properties.command).toBe('OBJECT_GET')
+    expect(getCmd.properties.args.path).toBe('resultPath')
+    expect(getCmd.in.obj).toEqual([{ id: returnValue, port: 'result' }])
+
+    // OBJECT_GET feeds both target data-nodes' `change` ports.
+    expect(getCmd.out.result).toEqual([
+      { id: 'pb1', port: 'change' },
+      { id: 'pb2', port: 'change' },
+    ])
+    // Target data-nodes consume the OBJECT_GET result via their `change` port.
+    expect(result.map.pb1.in.change).toEqual([{ id: getCommandId, port: 'result' }])
+    expect(result.map.pb2.in.change).toEqual([{ id: getCommandId, port: 'result' }])
+
+    // Without input usage their `out.value` defaults to null.
+    expect(result.map.pb1.out.value).toBeNull()
+    expect(result.map.pb2.out.value).toBeNull()
+  })
+
+  // Manual mode is the only mode that lets an output target reuse an input id
+  // (see validateConfig tests). When that happens, generateCalulationMap must
+  // keep the input-side `out.value` so the data-node remains a usable input.
+  test.each([
+    ['outputs', { outputs: { result: ['shared'] } }],
+    ['output', { output: 'shared' }],
+    ['error', { error: 'shared' }],
+  ])('preserves input out.value when %s target reuses an input id', (_, overrides) => {
+    const result = genMap(
+      baseConfig({ trigger_mode: 'manual', inputs: { shared: 'foo' }, ...overrides }),
+    )
+    expect(Array.isArray(result.map.shared.out.value)).toBe(true)
+    expect(result.map[result.map.shared.out.value[0].id].properties.command).toBe('OBJECT_SET')
+  })
+
+  test('also rewires in.change to OBJECT_GET when an outputs target reuses an input id', () => {
+    const result = genMap(
+      baseConfig({
+        trigger_mode: 'manual',
+        inputs: { shared: 'foo' },
+        outputs: { result: ['shared'] },
+      }),
+    )
+    expect(result.map.shared.in.change).toHaveLength(1)
+    expect(result.map[result.map.shared.in.change[0].id].properties.command).toBe('OBJECT_GET')
+  })
+
+  test('preserves out.value when the same pb appears in multiple outputs entries', () => {
+    // Two outputs entries both target `pb1`. The reduce visits each entry in turn
+    // and must preserve the accumulated `out.value` from the first iteration via
+    // `acc.map[pb]` rather than wiping it on the second.
+    const result = genMap(baseConfig({ outputs: { first: ['pb1'], second: ['pb1'] } }))
+    expect(result.map.pb1.type).toBe('data-node')
+    // Without an input, out.value remains null after both passes.
+    expect(result.map.pb1.out.value).toBeNull()
+    // The latest OBJECT_GET wins as the change source — each iteration overwrites
+    // `in.change`, so we end up pointing at the second outputs entry's command.
+    expect(result.map.pb1.in.change).toHaveLength(1)
+  })
+
+  test('wires the error data-node when error is configured', () => {
+    const result = genMap(baseConfig({ error: 'errNode' }))
+
+    const { error } = findSandboxIds(result.map)
+    // SANDBOX_GET_ERROR now broadcasts to the error data-node's `change` port.
+    expect(result.map[error].out.result).toEqual([{ id: 'errNode', port: 'change' }])
+    expect(result.map.errNode.type).toBe('data-node')
+    expect(result.map.errNode.in.change).toEqual([{ id: error, port: 'result' }])
+    // No upstream input → out.value falls back to null.
+    expect(result.map.errNode.out.value).toBeNull()
+    // editor_info contains the new node.
+    expect(result.editor_info.errNode).toBeDefined()
+  })
+
+  test('wires the output data-node when output is configured', () => {
+    const result = genMap(baseConfig({ output: 'outNode' }))
+
+    const { result: returnValue } = findSandboxIds(result.map)
+    expect(result.map[returnValue].out.result).toEqual([{ id: 'outNode', port: 'change' }])
+    expect(result.map.outNode.type).toBe('data-node')
+    expect(result.map.outNode.in.change).toEqual([{ id: returnValue, port: 'result' }])
+    expect(result.editor_info.outNode).toBeDefined()
+  })
+
+  test('manual trigger mode sets disable_trigger_command on input value ports', () => {
+    const result = genMap(
+      baseConfig({
+        trigger_mode: 'manual',
+        inputs: { a: 'foo', b: 'bar' },
+      }),
+    )
+    const aCmdId = result.map.a.out.value[0].id
+    const bCmdId = result.map.b.out.value[0].id
+    expect(result.map[aCmdId].in.value[0].disable_trigger_command).toBe(true)
+    expect(result.map[bCmdId].in.value[0].disable_trigger_command).toBe(true)
+  })
+
+  test('auto trigger mode honours per-key disabled_triggers', () => {
+    const result = genMap(
+      baseConfig({
+        inputs: { a: 'foo', b: 'bar' },
+        disabled_triggers: { a: true, b: false },
+      }),
+    )
+    const aCmdId = result.map.a.out.value[0].id
+    const bCmdId = result.map.b.out.value[0].id
+    expect(result.map[aCmdId].in.value[0].disable_trigger_command).toBe(true)
+    // Falsy disabled_triggers entry → property is not set (or set to undefined).
+    expect(result.map[bCmdId].in.value[0].disable_trigger_command).toBeUndefined()
+  })
+
+  test('auto trigger mode without disabled_triggers leaves disable_trigger_command undefined', () => {
+    const result = genMap(baseConfig({ inputs: { a: 'foo' } }))
+    const aCmdId = result.map.a.out.value[0].id
+    expect(result.map[aCmdId].in.value[0].disable_trigger_command).toBeUndefined()
+  })
+
+  test('derives command ids deterministically from the calc id (stable across compiles)', () => {
+    const config = baseConfig({ inputs: { a: 'foo' }, outputs: { out: ['pb1'] } })
+    const first = generateCalulationMap(config, CALC_ID)
+    const second = generateCalulationMap(config, CALC_ID)
+    // Same calc id + same config must yield byte-identical ids, so recompiling unchanged
+    // source produces no spurious property_bank_calc_map diff.
+    expect(Object.keys(second.map)).toEqual(Object.keys(first.map))
+
+    const uuid = '[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}'
+    sandboxNodeIds(first.map).forEach(({ id }) => {
+      expect(id).toMatch(new RegExp(`^PROPERTY_BANK_COMMAND_NODE_${uuid}$`))
+    })
+  })
+
+  test('seeds command ids per calc so different calcs never collide (edit isolation)', () => {
+    const config = baseConfig({ inputs: { a: 'foo' } })
+    const a = generateCalulationMap(
+      config,
+      'PROPERTY_BANK_COMMAND_MAP_aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa',
+    )
+    const b = generateCalulationMap(
+      config,
+      'PROPERTY_BANK_COMMAND_MAP_bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb',
+    )
+    expect(findSandboxIds(a.map).run).not.toBe(findSandboxIds(b.map).run)
+  })
+
+  test('validateConfig errors propagate out of generateCalulationMap', () => {
+    expect(() => genMap(baseConfig({ inputs: { a: 'foo' }, error: 'a' }))).toThrow(/key: error/)
+  })
+
+  test('SANDBOX_GET_RETURN_VALUE broadcasts to both output target and outputs commands', () => {
+    const result = genMap(
+      baseConfig({
+        output: 'outNode',
+        outputs: { foo: ['pb1'] },
+      }),
+    )
+    const { result: returnValue } = findSandboxIds(result.map)
+    const refs = result.map[returnValue].out.result
+    // First entry is the output data-node's `change` port; remainder are OBJECT_GET ids.
+    expect(refs[0]).toEqual({ id: 'outNode', port: 'change' })
+    expect(refs).toHaveLength(2)
+    expect(refs[1].port).toBe('obj')
+    expect(result.map[refs[1].id].properties.command).toBe('OBJECT_GET')
+  })
+})

package/compile/action-name-map.ts

@@ -350,6 +350,63 @@ export const templateActionNameMap = {
       strokeWidth: 'BRICK_SKETCH_STROKE_WIDTH',
     },
   },
+  BRICK_SCENE_3D: {
+    BRICK_SCENE_3D_ADD_OBJECT: {
+      objectId: 'BRICK_SCENE_3D_OBJECT_ID',
+      objectType: 'BRICK_SCENE_3D_OBJECT_TYPE',
+      objectUrl: 'BRICK_SCENE_3D_OBJECT_URL',
+      objectMd5: 'BRICK_SCENE_3D_OBJECT_MD5',
+      objectPosition: 'BRICK_SCENE_3D_OBJECT_POSITION',
+      objectRotation: 'BRICK_SCENE_3D_OBJECT_ROTATION',
+      objectScale: 'BRICK_SCENE_3D_OBJECT_SCALE',
+      objectColor: 'BRICK_SCENE_3D_OBJECT_COLOR',
+    },
+    BRICK_SCENE_3D_REMOVE_OBJECT: {
+      objectId: 'BRICK_SCENE_3D_OBJECT_ID',
+    },
+    BRICK_SCENE_3D_UPDATE_OBJECT: {
+      objectId: 'BRICK_SCENE_3D_OBJECT_ID',
+      objectPosition: 'BRICK_SCENE_3D_OBJECT_POSITION',
+      objectRotation: 'BRICK_SCENE_3D_OBJECT_ROTATION',
+      objectScale: 'BRICK_SCENE_3D_OBJECT_SCALE',
+      objectVisible: 'BRICK_SCENE_3D_OBJECT_VISIBLE',
+      objectColor: 'BRICK_SCENE_3D_OBJECT_COLOR',
+      objectNodes: 'BRICK_SCENE_3D_OBJECT_NODES',
+    },
+    BRICK_SCENE_3D_SET_CAMERA: {
+      cameraPosition: 'BRICK_SCENE_3D_CAMERA_POSITION',
+      cameraTarget: 'BRICK_SCENE_3D_CAMERA_TARGET',
+      cameraFov: 'BRICK_SCENE_3D_CAMERA_FOV',
+      cameraAnimateMs: 'BRICK_SCENE_3D_CAMERA_ANIMATE_MS',
+    },
+    BRICK_SCENE_3D_LOOK_AT: {
+      objectId: 'BRICK_SCENE_3D_OBJECT_ID',
+    },
+    BRICK_SCENE_3D_PLAY_ANIMATION: {
+      objectId: 'BRICK_SCENE_3D_OBJECT_ID',
+      animationName: 'BRICK_SCENE_3D_ANIMATION_NAME',
+      animationLoop: 'BRICK_SCENE_3D_ANIMATION_LOOP',
+      animationSpeed: 'BRICK_SCENE_3D_ANIMATION_SPEED',
+    },
+    BRICK_SCENE_3D_STOP_ANIMATION: {
+      objectId: 'BRICK_SCENE_3D_OBJECT_ID',
+      animationName: 'BRICK_SCENE_3D_ANIMATION_NAME',
+    },
+    BRICK_SCENE_3D_SET_BACKGROUND: {
+      backgroundColor: 'BRICK_SCENE_3D_BACKGROUND_COLOR',
+      backgroundHdrUrl: 'BRICK_SCENE_3D_BACKGROUND_HDR_URL',
+      backgroundMd5: 'BRICK_SCENE_3D_BACKGROUND_MD5',
+    },
+    BRICK_SCENE_3D_SET_CONTROLS: {
+      controlsEnabled: 'BRICK_SCENE_3D_CONTROLS_ENABLED',
+      controlsAutoRotate: 'BRICK_SCENE_3D_CONTROLS_AUTO_ROTATE',
+      controlsAutoRotateSpeed: 'BRICK_SCENE_3D_CONTROLS_AUTO_ROTATE_SPEED',
+    },
+    BRICK_SCENE_3D_SCREENSHOT: {
+      screenshotFormat: 'BRICK_SCENE_3D_SCREENSHOT_FORMAT',
+      screenshotQuality: 'BRICK_SCENE_3D_SCREENSHOT_QUALITY',
+    },
+  },
 
   GENERATOR_FILE: {
     GENERATOR_FILE_READ_CONTENT: {
@@ -782,6 +839,11 @@ export const templateActionNameMap = {
       seed: 'GENERATOR_LLM_SEED',
       typicalP: 'GENERATOR_LLM_TYPICAL_P',
       ignoreEos: 'GENERATOR_LLM_IGNORE_EOS',
+      mtpSpeculativeDecoding: 'GENERATOR_LLM_MTP_SPECULATIVE_DECODING',
+      mtpDraftTokens: 'GENERATOR_LLM_MTP_DRAFT_TOKENS',
+      mtpDraftMinTokens: 'GENERATOR_LLM_MTP_DRAFT_MIN_TOKENS',
+      mtpDraftMinProbability: 'GENERATOR_LLM_MTP_DRAFT_MIN_PROBABILITY',
+      mtpDraftSplitProbability: 'GENERATOR_LLM_MTP_DRAFT_SPLIT_PROBABILITY',
       functionCallEnabled: 'GENERATOR_LLM_FUNCTION_CALL_ENABLED',
       functionCallSchema: 'GENERATOR_LLM_FUNCTION_CALL_SCHEMA',
     },
@@ -894,10 +956,12 @@ export const templateActionNameMap = {
     GENERATOR_APPLE_STT_TRANSCRIBE_FILE: {
       fileUrl: 'GENERATOR_APPLE_STT_FILE_URL',
       language: 'GENERATOR_APPLE_STT_LANGUAGE',
+      contextualStrings: 'GENERATOR_APPLE_STT_CONTEXTUAL_STRINGS',
     },
     GENERATOR_APPLE_STT_TRANSCRIBE_DATA: {
       data: 'GENERATOR_APPLE_STT_DATA',
       language: 'GENERATOR_APPLE_STT_LANGUAGE',
+      contextualStrings: 'GENERATOR_APPLE_STT_CONTEXTUAL_STRINGS',
     },
   },
   GENERATOR_APPLE_TTS: {

package/compile/config-diff.ts

@@ -0,0 +1,155 @@
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+
+// The compiled config artifact written by `bun compile` (see the generated
+// project's `compile.ts`; bricks-project-generator/index.js:762).
+export const BUILD_CONFIG_RELATIVE = '.bricks/build/application-config.json'
+
+// `compile()` derives these top-level fields from `Date.now()`
+// (compile/index.ts `title: \`${app.name}(${timestamp})\`` and `update_timestamp`),
+// so they differ on every run regardless of source. Excluded from the comparison —
+// only the *top-level* keys are dropped, so nested subspace/brick `title`s still diff.
+const VOLATILE_TOP_LEVEL_FIELDS = ['title', 'update_timestamp']
+
+// A minimal, path-keyed config change (Option A): a generic patch, not coupled to
+// bricks-config-editor's action vocabulary. `path` is an array of object keys /
+// array indices, ready for the editor's `setYValueAtPath` (or a delete) so applying
+// the patch is a single Yjs `'local'` transaction == one undo/redo entry.
+export type ConfigPatchOp =
+  | { op: 'set'; path: Array<string | number>; value: unknown }
+  | { op: 'unset'; path: Array<string | number> }
+
+export type ConfigChange =
+  | { status: 'ok'; ops: ConfigPatchOp[]; opCount: number }
+  | { status: 'no_baseline' }
+  | { status: 'unavailable' }
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+const isJsonDroppedValue = (value: unknown) =>
+  value === undefined || typeof value === 'function' || typeof value === 'symbol'
+
+const toJsonComparableScalar = (value: unknown) => {
+  if (typeof value === 'number' && !Number.isFinite(value)) return null
+  return value
+}
+
+const toJsonCompatibleValue = (value: unknown): unknown => {
+  if (isJsonDroppedValue(value)) return undefined
+  if (Array.isArray(value)) {
+    return value.map((item) => (isJsonDroppedValue(item) ? null : toJsonCompatibleValue(item)))
+  }
+  if (isRecord(value)) {
+    return Object.entries(value).reduce((acc, [key, item]) => {
+      if (!isJsonDroppedValue(item)) acc[key] = toJsonCompatibleValue(item)
+      return acc
+    }, {})
+  }
+  return toJsonComparableScalar(value)
+}
+
+const hasJsonObjectKey = (value: Record<string, unknown>, key: string) =>
+  Object.prototype.hasOwnProperty.call(value, key) && !isJsonDroppedValue(value[key])
+
+const getJsonArrayItem = (value: unknown[], index: number) => {
+  const item = value[index]
+  return isJsonDroppedValue(item) ? null : item
+}
+
+const deepEqual = (a: unknown, b: unknown): boolean => {
+  a = toJsonComparableScalar(a)
+  b = toJsonComparableScalar(b)
+  if (a === b) return true
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false
+    for (let index = 0; index < a.length; index += 1) {
+      if (!deepEqual(getJsonArrayItem(a, index), getJsonArrayItem(b, index))) return false
+    }
+    return true
+  }
+  if (isRecord(a) && isRecord(b)) {
+    let comparableAKeys = 0
+    for (const key of Object.keys(a)) {
+      if (isJsonDroppedValue(a[key])) continue
+      comparableAKeys += 1
+      if (!hasJsonObjectKey(b, key) || !deepEqual(a[key], b[key])) return false
+    }
+
+    let comparableBKeys = 0
+    for (const key of Object.keys(b)) {
+      if (!isJsonDroppedValue(b[key])) comparableBKeys += 1
+    }
+    return comparableAKeys === comparableBKeys
+  }
+  return false
+}
+
+const normalizeConfig = (config: unknown) => {
+  if (!isRecord(config)) return config
+  const normalized = { ...config }
+  for (const field of VOLATILE_TOP_LEVEL_FIELDS) delete normalized[field]
+  return normalized
+}
+
+// Objects recurse key-wise; equal-length arrays recurse element-wise; everything else
+// (scalars, type changes, length-changed arrays) emits one whole-value `set` at that
+// path. The editor's `applyJsonDiffToYType` minimizes the actual Yjs ops downstream,
+// so a whole-array `set` on insert/remove still yields a minimal CRDT mutation.
+const diffInto = (
+  before: unknown,
+  after: unknown,
+  currentPath: Array<string | number>,
+  ops: ConfigPatchOp[],
+) => {
+  if (deepEqual(before, after)) return
+
+  if (isRecord(before) && isRecord(after)) {
+    const keys = new Set([...Object.keys(before), ...Object.keys(after)])
+    for (const key of keys) {
+      const beforeHasKey = hasJsonObjectKey(before, key)
+      const afterHasKey = hasJsonObjectKey(after, key)
+      if (!beforeHasKey && !afterHasKey) continue
+
+      const nextPath = [...currentPath, key]
+      if (!afterHasKey) ops.push({ op: 'unset', path: nextPath })
+      else if (!beforeHasKey) {
+        ops.push({ op: 'set', path: nextPath, value: toJsonCompatibleValue(after[key]) })
+      } else diffInto(before[key], after[key], nextPath, ops)
+    }
+    return
+  }
+
+  if (Array.isArray(before) && Array.isArray(after) && before.length === after.length) {
+    for (let index = 0; index < after.length; index += 1) {
+      diffInto(
+        getJsonArrayItem(before, index),
+        getJsonArrayItem(after, index),
+        [...currentPath, index],
+        ops,
+      )
+    }
+    return
+  }
+
+  ops.push({ op: 'set', path: currentPath, value: toJsonCompatibleValue(after) })
+}
+
+// Diff two compiled configs. `before == null` means there was no prior build to compare
+// (first compile); `after == null` means the fresh artifact could not be read.
+export const computeConfigChange = (before: unknown, after: unknown): ConfigChange => {
+  if (before == null) return { status: 'no_baseline' }
+  if (after == null) return { status: 'unavailable' }
+  const ops: ConfigPatchOp[] = []
+  diffInto(normalizeConfig(before), normalizeConfig(after), [], ops)
+  return { status: 'ok', ops, opCount: ops.length }
+}
+
+// Read the last-compiled config artifact. Returns null when it is absent or unreadable.
+export const readBuildConfig = async (projectDir: string): Promise<unknown> => {
+  try {
+    return JSON.parse(await readFile(path.join(projectDir, BUILD_CONFIG_RELATIVE), 'utf8'))
+  } catch {
+    return null
+  }
+}