@fugood/bricks-project 2.24.3 → 2.24.5

package/skills/bricks-ux/references/ux-critique.md

@@ -0,0 +1,256 @@
+# UX Critique
+
+Verification proves the flow *runs*. UX critique proves the flow is *usable*. Both are required before declaring done; neither substitutes for the other.
+
+UX critique runs in parallel with visual-design critique (`bricks-design/design-critique.md`). A Canvas can fail one and pass the other; both block ship.
+
+This file is tiered. The same UX problem (e.g., closure missing) is **CRITICAL** on a payment kiosk and **MEDIUM** on a museum signage loop. Critique fails ship when CRITICAL or HIGH items go unaddressed in their applicable tiers.
+
+## How to run the pass
+
+1. **Open the journey.** Walk every interaction step-by-step using `user-journey.md` as the spine.
+2. **For each Canvas / Brick group, classify by deployment risk** (table below). The classification determines which tier of checks apply.
+3. **Run the checks in the applicable tier(s).** CRITICAL items always run; HIGH applies broadly; MEDIUM and LOW depend on classification.
+4. **Fix every CRITICAL miss and every HIGH miss.** Surface MEDIUM and LOW misses in the trade-off note if not addressed.
+5. **Re-verify after fixes.** Don't accumulate fix debt.
+
+## Risk classification by deployment shape
+
+| Deployment shape | Risk profile | Tier weighting |
+|---|---|---|
+| Payment / identity capture / safety-critical | CRITICAL-dense — every transact discipline must pass | CRITICAL + HIGH + MEDIUM all apply |
+| Self-service interactive (ordering, check-in, configuration) | HIGH-dense — journey completeness, idle reset, recovery paths | CRITICAL + HIGH apply; MEDIUM where relevant |
+| Monitoring / dashboard / control room | HIGH-dense — alarm hierarchy, stale-data trust, calm/detect/demand | CRITICAL + HIGH apply for alarm states |
+| Browse / wayfinding / menu board | MEDIUM-dense — legibility, comparison clarity, sparse states | HIGH legibility, MEDIUM elsewhere |
+| Glanceable signage / dwell / ambient loop | LOW-dense — main checks are legibility and rhythm | HIGH legibility, LOW elsewhere |
+
+## CRITICAL — blocks ship
+
+Failure on any of these is sufficient grounds to declare the work mid-iteration.
+
+### CR-1. The user-journey spine is whole
+
+Every interaction must have all seven steps present (or deliberately compressed; see `user-journey.md` § "When the seven steps compress"). Most-common holes:
+
+- **Immediate feedback missing** (step 3). User taps, nothing visible, taps again.
+- **In-flight visibility missing** (step 4). Action triggered, screen frozen, user re-triggers.
+- **Recovery as dead-end** (step 6). Error Canvas with no path forward.
+- **Closure ambiguous or missing** (step 7). Success state transient or unclear.
+
+**Must Have:** every interaction has a designed and verified affordance, instruction, feedback, in-flight state, continuation, recovery, closure — or deliberate documented collapse.
+**Anti-Pattern:** journey skipping any step on the assumption "it's fast enough not to need".
+
+### CR-2. Transact has its intensification
+
+For payment / identity / safety-critical flows, the seven steps must be tightened (`user-journey.md` § "When the seven steps intensify"):
+
+- Confirmation step before commit.
+- In-flight visibility non-skippable.
+- Recovery categorised (declined / network / cancelled / timeout).
+- Closure with weight and hold time.
+
+**Must Have:** transact closure holds ≥ 5 seconds, success unmistakable, peripheral state visible.
+**Anti-Pattern:** "Process payment in one tap" with no confirmation; closure that auto-advances in < 2s.
+
+### CR-3. Monitoring has demand discipline
+
+For dashboards / monitor screens with alarm capability:
+
+- Calm / detect / demand are three distinct designed states.
+- Demand state stands out unambiguously; not a slight colour change.
+- Multiple concurrent demand states have priority ordering already designed.
+- Stale-data is visibly declared per source.
+- Color is never the only encoding of severity.
+
+**Must Have:** alarm-state preview captured and reviewed; squint-test passes (alarm visible from peripheral vision); monochrome preview still distinguishes severity tiers.
+**Anti-Pattern:** alarm styled identically to detect-state; "stale" indicator at 8pt in corner; severity by colour alone.
+
+### CR-4. Accessibility floors met for the audience
+
+The seven accessibility disciplines (`accessibility.md`) apply at deployment-relative floors. CRITICAL when the audience includes:
+
+- Reduced-vision users (contrast, scale, color-not-only).
+- Reduced-motor users (touch targets, no precise gestures, no time-pressure auto-cancels).
+- Sensitive-to-motion users (reduced-motion path available).
+- Multilingual audience (strings via Data; type scale accommodates longest translation).
+
+**Must Have:** contrast verified under deployment-actual lighting; touch targets verified with real-finger / real-hardware testing; severity / status encoded by shape + color + label.
+**Anti-Pattern:** WCAG-compliance-on-desktop-monitor as the audit (deployment is sunlit signage at 4m); time-pressure UI on a venue that includes slow / hesitant users.
+
+### CR-5. Idle reset is clean
+
+For self-service interactive deployments:
+
+- Idle timeout exists and is calibrated to the use pattern.
+- Idle reset clears flow state — no half-built order persists; no name on screen; no half-confirmed action.
+- Reset returns to a designed idle / attractor state, not to "whatever Canvas was loaded".
+
+**Must Have:** verified idle reset behaviour via Automation or live test; verified that no leaked state persists to next session.
+**Anti-Pattern:** idle = last interact Canvas; idle that requires operator to manually reset.
+
+## HIGH — must fix before launch
+
+### H-1. Affordance is unambiguous
+
+Every pressable Brick declares "press me" visually — contrast, weight, motion, or icon. Affordance vocabulary is consistent across the deployment.
+
+**Must Have:** pressable tiles visually distinct from non-pressable; squint test confirms which Bricks are interactive.
+**Anti-Pattern:** identical-looking tiles where some are pressable and some aren't; pressable Bricks with no visual distinction from background.
+
+### H-2. Press feedback at registration
+
+Every `on_press` produces a visible state change at the moment of registration — scale, opacity, color, or new Brick entry via Standby Transition. Not a fade-in.
+
+**Must Have:** Brick under press visibly responds within 100ms (effectively snap, not fade).
+**Anti-Pattern:** press registers, no visible change; press relies on Canvas-change-only feedback (user perceives lag).
+
+### H-3. Flow states designed, not skipped
+
+Idle / loading / empty / error / boot / maintenance (as applicable to the deployment) are designed states, each with verified preview.
+
+**Must Have:** every applicable state's preview captured and reviewed; failure modes per state checked against `flow-states.md`.
+**Anti-Pattern:** "empty state is fine, the list is always populated" without testing the empty case; error state in 8pt corner text; boot = loading spinner.
+
+### H-4. Hero continuity across journey Canvases
+
+For multi-Canvas flows, hero Bricks share ids across Canvases — chrome (logo, progress indicator, time, back action) carries via Truth #3 auto-tween.
+
+**Must Have:** primary chrome elements identifiable in the same screen positions across the flow's Canvases.
+**Anti-Pattern:** every Canvas remounts its full Brick set; user loses spatial mental model between steps.
+
+### H-5. Error recovery has a path
+
+Every error state offers retry, alternate method, abandon, or help — never a dead-end. Different error categories get distinguishable recovery treatments.
+
+**Must Have:** each error path verified end-to-end via Automation or live test.
+**Anti-Pattern:** "Error. Please try again." with no retry mechanism; generic recovery for all error types.
+
+### H-6. Stale-data trust
+
+For monitoring / live-data screens, every dynamic source has a visibly declared staleness state or a visible "last update" relative-time indicator.
+
+**Must Have:** staleness visible in peripheral vision; stale value distinguishable from current value.
+**Anti-Pattern:** dynamic value with no age indication; "last update" in 8pt absolute timestamp.
+
+### H-7. Predictable navigation
+
+Navigation affordances (back, next, home) sit consistently across Canvases. Idle returns to the same idle Canvas every time.
+
+**Must Have:** back / next affordance positions verified across Canvases; idle reset produces identical idle Canvas every time.
+**Anti-Pattern:** back button at top-left on Canvas 2, bottom-right on Canvas 3; idle rotates such that the "anchor" element moves.
+
+## MEDIUM — impacts polish; prioritize by user impact
+
+### M-1. Instruction matches user mental model
+
+Action instructions ("Scan your code", "Tap to start", "Pay now") match the user's likely understanding; jargon avoided; language locale-matched.
+
+**Must Have:** wording reviewed for the actual audience; jargon removed.
+**Anti-Pattern:** "Initiate authentication sequence" on a public kiosk; English-only instruction on a multilingual venue.
+
+### M-2. Continuation is non-surprising
+
+The Canvas the user lands on after an action matches their expectation. Big jumps in journey context happen only with explicit transition.
+
+**Must Have:** continuation Canvas reviewed for context preservation; hero continuity in place.
+**Anti-Pattern:** success on Canvas A jumps to Canvas D mid-flow; user loses context.
+
+### M-3. Closure proportional to stakes
+
+Success closure hold time and visual weight match the action's stakes. Routine completions get brief acknowledgement; transact completions get held visible.
+
+**Must Have:** closure hold time tuned to action stakes; auto-advance only after enough time for the user to read.
+**Anti-Pattern:** 1.5s closure for a transact flow; 8s closure for a "saved to favorites" toast.
+
+### M-4. Density rhythm in browse / dwell
+
+For browse / dwell deployments, content rotation has variation in density / framing / colour rhythm across Canvases or slides. Three identical-rhythm Canvases in a row is a tell. (Cross-reference: `bricks-design/design-critique.md` density-rhythm collapse.)
+
+**Must Have:** rhythm variation across the sequence; no three identical-archetype Canvases in a row.
+**Anti-Pattern:** ten Canvases that all read as "headline + bullet list".
+
+### M-5. Audio cues calibrated (when hardware allows)
+
+If the deployment uses audio, volume / timing / time-of-day awareness is intentional.
+
+**Must Have:** audio volume / scheduling reviewed; success / alarm cues distinguishable from ambient.
+**Anti-Pattern:** constant-volume cues regardless of time; audio-only confirmation (no visual pair).
+
+### M-6. Reduced-motion path available (if relevant)
+
+For deployments in clinical / safety / motion-sensitive contexts, a reduced-motion path exists.
+
+**Must Have:** `reduceMotion` Data flag wired where applicable; verified reduced-motion preview.
+**Anti-Pattern:** continuous-motion design with no reduction path for a clinical deployment.
+
+## LOW — context-dependent
+
+### L-1. Polish on idle / attractor presence
+
+For deployments where idle dominates: idle is *inviting*, not just *running*.
+
+**Must Have for high-traffic public deployments:** attractor sequence engages from peripheral vision.
+**Anti-Pattern:** logo-only idle on a deployment whose purpose is to invite interaction.
+
+### L-2. Maintenance state designed
+
+If the deployment has scheduled downtime, a maintenance Canvas exists and distinguishes itself from error.
+
+**Must Have for deployments with maintenance windows:** maintenance Canvas with return path.
+**Anti-Pattern:** maintenance = black screen.
+
+### L-3. Empty-state composition
+
+Empty states explain the absence and suggest what populates.
+
+**Must Have:** empty state designed rather than collapsed-whitespace.
+**Anti-Pattern:** "—" or blank where content would be.
+
+## Tier-by-tier checklist (running order)
+
+Use this when running the pass:
+
+**CRITICAL (always run):**
+
+- [ ] User-journey spine whole (CR-1)
+- [ ] Transact intensified if applicable (CR-2)
+- [ ] Monitoring demand discipline if applicable (CR-3)
+- [ ] Accessibility floors met (CR-4)
+- [ ] Idle reset clean if applicable (CR-5)
+
+**HIGH (always run except for glance / dwell loops):**
+
+- [ ] Affordance unambiguous (H-1)
+- [ ] Press feedback at registration (H-2)
+- [ ] Flow states designed (H-3)
+- [ ] Hero continuity across Canvases (H-4)
+- [ ] Error recovery has a path (H-5)
+- [ ] Stale-data trust if applicable (H-6)
+- [ ] Predictable navigation (H-7)
+
+**MEDIUM (run for interact / transact / browse):**
+
+- [ ] Instruction matches mental model (M-1)
+- [ ] Continuation non-surprising (M-2)
+- [ ] Closure proportional (M-3)
+- [ ] Density rhythm (M-4)
+- [ ] Audio cues calibrated (M-5)
+- [ ] Reduced-motion path (M-6)
+
+**LOW (run for public-facing / high-dwell):**
+
+- [ ] Idle / attractor polish (L-1)
+- [ ] Maintenance state (L-2)
+- [ ] Empty-state composition (L-3)
+
+## Definition of UX done
+
+A flow is UX-done when:
+
+1. The CRITICAL tier passes — zero unaddressed CRITICAL items.
+2. The HIGH tier passes — zero unaddressed HIGH items (or surfaced as accepted trade-off with rationale).
+3. Applicable MEDIUM / LOW items either pass or are surfaced.
+4. Every state (golden path + error categories + idle + empty if relevant) has been verified via preview screenshot or Automation, and reviewed.
+5. Accessibility floors are met at the deployment-relative threshold, not at a desktop default.
+
+If any item is unmet, the work is mid-iteration. Say so explicitly to the user; offer a precise list of what remains.

package/tools/_git-author.ts

@@ -15,7 +15,15 @@ async function hasGitIdentity(cwd: string): Promise<boolean> {
 // If no identity is configured (typical for non-tech users), CTOR becomes the
 // main author via per-command `-c user.name/-c user.email` overrides so the
 // user's git config is left untouched.
-export async function buildCommitArgs(cwd: string, messages: string[]): Promise<string[]> {
+//
+// `extraFlags` are inserted between `commit` and the `-m` args (e.g.
+// `['--no-verify']` to bypass pre-commit hooks for controlled cases like
+// committing merge-conflict markers).
+export async function buildCommitArgs(
+  cwd: string,
+  messages: string[],
+  extraFlags: string[] = [],
+): Promise<string[]> {
   const hasIdentity = await hasGitIdentity(cwd)
   const prefix = hasIdentity
     ? []
@@ -23,7 +31,7 @@ export async function buildCommitArgs(cwd: string, messages: string[]): Promise<
   const msgArgs: string[] = []
   for (const m of messages) msgArgs.push('-m', m)
   if (hasIdentity) msgArgs.push('-m', CTOR_COAUTHOR_TRAILER)
-  return [...prefix, 'commit', ...msgArgs]
+  return [...prefix, 'commit', ...extraFlags, ...msgArgs]
 }
 
 export { CTOR_NAME, CTOR_EMAIL, CTOR_COAUTHOR_TRAILER }

package/tools/_last-pushed-commit.ts

@@ -0,0 +1,28 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+
+// Local sync marker: the git commit hash that was on HEAD when we last
+// successfully pushed to the server (deploy or update-config) or pulled
+// from it. Stored at the `.bricks/` top level (gitignored explicitly) — it's
+// per-clone state, not a build artifact, so it doesn't belong under
+// `.bricks/build/`.
+//
+// Why this exists: server's `bricks_project_last_commit_id` can be an opaque
+// nanoid for content-only edits (config-editor saves), so it isn't a
+// reliable git anchor for `git checkout` during pull. The local marker is
+// always a real reachable commit hash from THIS clone.
+const REL_PATH = '.bricks/.last-pushed-commit'
+
+export async function readLastPushedCommit(cwd: string): Promise<string | null> {
+  try {
+    const content = await readFile(`${cwd}/${REL_PATH}`, 'utf8')
+    return content.trim() || null
+  } catch {
+    return null
+  }
+}
+
+export async function writeLastPushedCommit(cwd: string, commitId: string): Promise<void> {
+  if (!commitId) return
+  await mkdir(`${cwd}/.bricks`, { recursive: true })
+  await writeFile(`${cwd}/${REL_PATH}`, commitId)
+}

package/tools/_shell.ts

@@ -29,6 +29,7 @@ class Sh implements PromiseLike<ShResult> {
   private _cwd: string | undefined
   private _mode: Mode = 'default'
   private _throw = true
+  private _env: NodeJS.ProcessEnv | undefined
   private _promise: Promise<ShResult> | null = null
 
   constructor(private readonly args: string[]) {}
@@ -48,6 +49,11 @@ class Sh implements PromiseLike<ShResult> {
     return this
   }
 
+  env(extra: NodeJS.ProcessEnv): this {
+    this._env = { ...this._env, ...extra }
+    return this
+  }
+
   async text(): Promise<string> {
     // If no explicit quiet was requested, capture stdout/stderr without
     // forwarding them to the parent's streams (matches Bun's `.text()`).
@@ -79,7 +85,8 @@ class Sh implements PromiseLike<ShResult> {
           ? ['ignore', 'pipe', 'pipe']
           : ['inherit', 'pipe', 'pipe']
 
-    const proc = spawn(cmd, rest, { cwd: this._cwd, stdio })
+    const env = this._env ? { ...process.env, ...this._env } : undefined
+    const proc = spawn(cmd, rest, { cwd: this._cwd, stdio, env })
 
     const outChunks: Buffer[] = []
     const errChunks: Buffer[] = []

package/tools/deploy.ts

@@ -2,6 +2,11 @@ import { access, readFile, writeFile } from 'node:fs/promises'
 import { parseArgs } from 'util'
 import { sh } from './_shell'
 import { buildCommitArgs } from './_git-author'
+import { writeLastPushedCommit } from './_last-pushed-commit'
+
+if (!process.env.BRICKS_RELEASE_SIGN) {
+  process.env.BRICKS_RELEASE_SIGN = 'CTOR'
+}
 
 const cwd = process.cwd()
 
@@ -141,6 +146,10 @@ await writeFile(configPath, JSON.stringify(releaseConfig))
 
 const args = ['bricks', command, 'release', app.id, '-c', configPath, '--json']
 
+if (app.name) {
+  args.push('--name', app.name)
+}
+
 if (version) {
   args.push('--version', version)
 }
@@ -162,4 +171,10 @@ if (result.exitCode !== 0) {
 }
 
 const output = JSON.parse(result.stdout.toString())
+
+// Record the commit we just pushed from so a later pull can use it as the
+// merge base regardless of what the server stores in
+// bricks_project_last_commit_id.
+if (commitId) await writeLastPushedCommit(cwd, commitId)
+
 console.log(`${isModule ? 'Module' : 'App'} deployed: ${output.name}`)

package/tools/mcp-tools/compile.ts

@@ -3,22 +3,29 @@ import { readFile } from 'node:fs/promises'
 import { z } from 'zod'
 import { sh } from '../_shell'
 
+// Disable ANSI color codes from spawned tools so MCP text output stays readable
+// (the host renders raw text; escape sequences leak into the result otherwise).
+const noColorEnv = { FORCE_COLOR: '0', NO_COLOR: '1' }
+
 export function register(server: McpServer, projectDir: string) {
   const { dirname } = import.meta
 
   server.tool('compile', {}, async () => {
-    let log = ''
+    let log = 'Type checking & Compiling...\n'
     try {
-      log += 'Type checking & Compiling...'
-      log += await sh`bun compile`.cwd(projectDir).text()
-    } catch (err) {
-      log += `${err.stdout.toString()}\n${err.stderr.toString()}`
+      log += await sh`bun compile`.cwd(projectDir).env(noColorEnv).text()
+    } catch (err: any) {
+      const stdout = err.stdout?.toString() ?? ''
+      const stderr = err.stderr?.toString() ?? ''
+      log += [stdout, stderr].filter(Boolean).join('\n')
     }
     return {
       content: [{ type: 'text', text: log }],
     }
   })
 
+  if (process.env.BRICKS_CTOR_MCP_DISABLE_PREVIEW === '1') return
+
   server.tool(
     'preview',
     {
@@ -63,9 +70,12 @@ export function register(server: McpServer, projectDir: string) {
         if (testTitleLike) args.push('--test-title-like', testTitleLike)
         log = await sh`bunx --bun electron ${toolsDir}/preview-main.mjs ${args}`
           .cwd(projectDir)
+          .env(noColorEnv)
           .text()
-      } catch (err) {
-        log = `${err.stdout.toString()}\n${err.stderr.toString()}`
+      } catch (err: any) {
+        const stdout = err.stdout?.toString() ?? ''
+        const stderr = err.stderr?.toString() ?? ''
+        log = [stdout, stderr].filter(Boolean).join('\n')
         error = true
       }
       let screenshotBase64: string | null = null

package/tools/mcp-tools/media.ts

@@ -2,9 +2,12 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { z } from 'zod'
 import { sh } from '../_shell'
 
+// MCP results are rendered as raw text — disable ANSI colors from the child.
+const noColorEnv = { FORCE_COLOR: '0', NO_COLOR: '1' }
+
 const runBricks = async (projectDir: string, ...args: string[]) => {
   try {
-    return await sh`bunx bricks ${args}`.cwd(projectDir).text()
+    return await sh`bunx bricks ${args}`.cwd(projectDir).env(noColorEnv).text()
   } catch (err: any) {
     throw new Error(err.stderr?.toString() || err.message)
   }

package/tools/pull.ts

@@ -1,7 +1,31 @@
-import { readFile, writeFile } from 'node:fs/promises'
+import { readdir, readFile, unlink, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join, relative } from 'node:path'
 import { format } from 'oxfmt'
 import { sh } from './_shell'
 import { buildCommitArgs } from './_git-author'
+import { readLastPushedCommit, writeLastPushedCommit } from './_last-pushed-commit'
+
+// Directories whose .ts contents are entirely owned by the generator.
+// Anything under these dirs not present in the freshly pulled file list is an orphan.
+const ownedTsDirs = ['subspaces', 'automation-tests']
+
+async function walkTsFiles(dir: string, baseDir: string): Promise<string[]> {
+  if (!existsSync(dir)) return []
+  const result: string[] = []
+  const entries = await readdir(dir, { withFileTypes: true })
+  await Promise.all(
+    entries.map(async (entry) => {
+      const full = join(dir, entry.name)
+      if (entry.isDirectory()) {
+        result.push(...(await walkTsFiles(full, baseDir)))
+      } else if (entry.isFile() && entry.name.endsWith('.ts')) {
+        result.push(relative(baseDir, full))
+      }
+    }),
+  )
+  return result
+}
 
 const cwd = process.cwd()
 const args = process.argv.slice(2)
@@ -52,30 +76,40 @@ if (result.exitCode !== 0) {
   }
 }
 
-const { files, lastCommitId } = JSON.parse(result.stdout.toString())
+const { files, lastCommitId: serverLastCommitId } = JSON.parse(result.stdout.toString())
+
+// The locally-saved commit (recorded by deploy/update-config) is the
+// authoritative merge base for THIS clone — the server's value can be an
+// opaque nanoid (config-only updates) or point to a commit other clients
+// produced. Fall back to the server's value only if we have no local
+// record yet.
+const savedLocalCommitId = await readLastPushedCommit(cwd)
+const baseCommitId = savedLocalCommitId || serverLastCommitId
+
+const branchName = isModule
+  ? 'BRICKS_PROJECT_try-pull-module'
+  : 'BRICKS_PROJECT_try-pull-application'
 
-let useMain = false
 if (isGitRepo && !force) {
-  console.log(`Checking commit ${lastCommitId}...`)
-  const found = (await sh`cd ${cwd} && git rev-list -1 ${lastCommitId}`.nothrow().text())
+  console.log(`Checking commit ${baseCommitId}...`)
+  const found = (await sh`cd ${cwd} && git rev-list -1 ${baseCommitId}`.nothrow().text())
     .trim()
     .match(/^[\da-f]{40}$/)
 
-  const commitId = (await sh`cd ${cwd} && git rev-parse HEAD`.text()).trim()
+  const headCommitId = (await sh`cd ${cwd} && git rev-parse HEAD`.text()).trim()
 
-  if (commitId === lastCommitId) throw new Error('Commit not changed')
-
-  const branchName = isModule
-    ? 'BRICKS_PROJECT_try-pull-module'
-    : 'BRICKS_PROJECT_try-pull-application'
+  if (headCommitId === serverLastCommitId) throw new Error('Commit not changed')
 
   await sh`cd ${cwd} && git branch -D ${branchName}`.nothrow()
 
+  // When the base commit isn't reachable in this clone (server stored a
+  // nanoid, or the commit was pruned), fall back to forking from current
+  // HEAD. The downstream merge into main collapses both paths into the
+  // same result, just with different merge bases.
   if (found) {
-    await sh`cd ${cwd} && git checkout -b ${branchName} ${lastCommitId}`.nothrow()
+    await sh`cd ${cwd} && git checkout -b ${branchName} ${baseCommitId}`.nothrow()
   } else {
     await sh`cd ${cwd} && git checkout -b ${branchName}`
-    useMain = true
   }
 }
 
@@ -89,6 +123,23 @@ const oxfmtConfig = await readFile(`${cwd}/.oxfmtrc.json`, 'utf8')
     printWidth: 100,
   }))
 
+const expectedFiles = new Set(files.map((file: { name: string }) => file.name))
+
+// Remove orphan .ts files under generator-owned directories before writing.
+// File paths are produced by buildApplicationFiles and use forward slashes,
+// so normalise the walked paths the same way for comparison.
+const orphans: string[] = []
+await Promise.all(
+  ownedTsDirs.map(async (dir) => {
+    const existing = await walkTsFiles(join(cwd, dir), cwd)
+    for (const file of existing) {
+      const normalized = file.split(/[\\/]/).join('/')
+      if (!expectedFiles.has(normalized)) orphans.push(normalized)
+    }
+  }),
+)
+await Promise.all(orphans.map((name) => unlink(`${cwd}/${name}`)))
+
 await Promise.all(
   files.map(async (file: { name: string; input: string; formatable?: boolean }) => {
     let content = file.input
@@ -112,11 +163,35 @@ if (isGitRepo) {
     const commitArgs = await buildCommitArgs(cwd, [commitMsg])
     await sh`cd ${cwd} && git ${commitArgs}`
   }
-  if (!force && !useMain) {
-    await sh`cd ${cwd} && git merge main`
+  if (!force) {
+    // Land the pulled commits on main with a single 3-way merge using
+    // baseCommit as the merge base. The user doesn't have to manage a side
+    // branch, and conflicts (if any) land in the working tree on main where
+    // auto-compile surfaces them as typecheck errors to resolve in-place.
+    await sh`cd ${cwd} && git checkout main`
+    const mergeResult = await sh`cd ${cwd} && git merge ${branchName} --no-edit`.nothrow()
+    if (mergeResult.exitCode !== 0) {
+      // Conflict markers are in the working tree — commit them so the tree
+      // is clean for auto-compile to detect, leaving the resolution to the
+      // user. Pre-commit hooks would reject markers (lint/format fail on
+      // invalid syntax), so bypass them for this controlled case.
+      await sh`cd ${cwd} && git add .`
+      const conflictArgs = await buildCommitArgs(
+        cwd,
+        ['chore(project): merge with conflicts (resolve in main)'],
+        ['--no-verify'],
+      )
+      await sh`cd ${cwd} && git ${conflictArgs}`
+    }
+    // The try-pull branch served its purpose; delete it so `git branch`
+    // stays tidy. The next pull recreates it anyway (line 103).
+    await sh`cd ${cwd} && git branch -D ${branchName}`.nothrow()
   }
+  // Record the new sync point so a follow-up pull starts from the right base.
+  const newHead = (await sh`cd ${cwd} && git rev-parse HEAD`.nothrow().text()).trim()
+  if (newHead) await writeLastPushedCommit(cwd, newHead)
 }
 
 console.log(
-  `${isModule ? 'Module' : 'App'} project pulled: ${files.length} files${force ? ' (force)' : ''}`,
+  `${isModule ? 'Module' : 'App'} project pulled: ${files.length} files${orphans.length ? `, removed ${orphans.length} orphan .ts file${orphans.length === 1 ? '' : 's'}` : ''}${force ? ' (force)' : ''}`,
 )

package/tools/update-config.ts

@@ -2,6 +2,7 @@ import { readFile, writeFile } from 'node:fs/promises'
 import { parseArgs } from 'util'
 import { sh } from './_shell'
 import { buildCommitArgs } from './_git-author'
+import { writeLastPushedCommit } from './_last-pushed-commit'
 
 const cwd = process.cwd()
 
@@ -107,4 +108,11 @@ if (result.exitCode !== 0) {
 }
 
 const output = JSON.parse(result.stdout.toString())
+
+// Record the commit we just pushed from so a later pull can use it as the
+// merge base regardless of what the server stores in
+// bricks_project_last_commit_id (which may be an opaque nanoid for
+// content-only edits).
+if (commitId) await writeLastPushedCommit(cwd, commitId)
+
 console.log(`${isModule ? 'Module' : 'App'} config updated: ${output.target?.name || app.name}`)

package/types/animation.ts

@@ -104,8 +104,13 @@ export interface AnimationComposeDef {
 
 export type Animation = AnimationDef | AnimationComposeDef
 
+// Animation event handlers accept either a direct Animation or a getter that
+// returns one. The getter form is useful for lazy/forward references between
+// animations defined across files.
+export type AnimationOrGetter = Animation | (() => Animation)
+
 export interface AnimationBasicEvents {
-  showStart?: Animation
-  standby?: Animation
-  breatheStart?: Animation
+  showStart?: AnimationOrGetter
+  standby?: AnimationOrGetter
+  breatheStart?: AnimationOrGetter
 }

package/types/automation.ts

@@ -203,6 +203,7 @@ export type LocalSyncMode = 'main-only' | 'minor-only'
 export interface AutomationTest {
   __typename: 'AutomationTest'
   id: string
+  alias?: string
   title: string
   hideShortRef?: boolean
   timeout: number

package/types/brick-base.ts

@@ -1,7 +1,7 @@
 /* Auto generated by build script */
 import type { SwitchCondInnerStateCurrentCanvas, SwitchCondData, SwitchDef } from './switch'
 import type { Data, DataLink } from './data'
-import type { Animation, AnimationBasicEvents } from './animation'
+import type { Animation, AnimationBasicEvents, AnimationOrGetter } from './animation'
 import type {
   Brick,
   EventAction,