orizu 0.5.39 → 0.5.41

package/src/instruction-set-sync/index.ts

@@ -509,17 +509,25 @@ function removeObservedSyncLock(lockPath: string, observed: ObservedSyncLock): b
   return true
 }
 
-export function withSyncLock<T>(appRoot: string, operation: () => T): T {
+export interface SyncLockClaim { lockPath: string; metadata: string; deadline: number }
+
+export function startSyncLockClaim(appRoot: string): SyncLockClaim {
   mkdirSync(appRoot, { recursive: true })
-  const lockPath = join(appRoot, '.orizu.lock.json.lock')
-  const metadata = `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`
   const lockWaitMs = processTestMilliseconds(
     'ORIZU_TEST_SYNC_LOCK_WAIT_MS',
     100,
     SYNC_LOCK_WAIT_MS
   ) ?? SYNC_LOCK_WAIT_MS
-  const deadline = Date.now() + lockWaitMs
+  return {
+    lockPath: join(appRoot, '.orizu.lock.json.lock'),
+    metadata: `${JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() })}\n`,
+    deadline: Date.now() + lockWaitMs,
+  }
+}
 
+// One claim attempt: returns the release function, or how long to wait before
+// trying again. Waiting is the caller's job so it can be blocking or not.
+export function tryClaimSyncLock({ lockPath, metadata, deadline }: SyncLockClaim): (() => void) | number {
   while (true) {
     try {
       writeFileSync(lockPath, metadata, { encoding: 'utf8', flag: 'wx', mode: 0o600 })
@@ -540,17 +548,26 @@ export function withSyncLock<T>(appRoot: string, operation: () => T): T {
       if (Date.now() >= deadline) {
         throw new Error(`instruction_set_sync_lock_busy${busyPid === undefined ? '' : `:${busyPid}`}`)
       }
-      sleepSync(Math.min(SYNC_LOCK_RETRY_MS, Math.max(1, deadline - Date.now())))
+      return Math.min(SYNC_LOCK_RETRY_MS, Math.max(1, deadline - Date.now()))
     }
   }
 
-  const release = () => {
+  return () => {
     try {
       if (readFileSync(lockPath, 'utf8') === metadata) rmSync(lockPath)
     } catch (error) {
       if (!(isNodeError(error) && error.code === 'ENOENT')) throw error
     }
   }
+}
+
+export function withSyncLock<T>(appRoot: string, operation: () => T): T {
+  const claim = startSyncLockClaim(appRoot)
+  let release = tryClaimSyncLock(claim)
+  while (typeof release === 'number') {
+    sleepSync(release)
+    release = tryClaimSyncLock(claim)
+  }
   let result: T
   try {
     result = operation()
@@ -600,6 +617,16 @@ export interface SyncDiskOptions {
   platform?: NodeJS.Platform
 }
 
+export interface StagedSync {
+  appRoot: string
+  destination: string
+  wasPresent: boolean
+  /** Publishes the staged version; the caller must hold the folder lock. Returns warnings. */
+  publish: () => string[]
+  /** Removes the staged version if it was not published. Safe to call more than once. */
+  discard: () => void
+}
+
 export function syncPayloadToDisk(
   out: string,
   project: string,
@@ -607,6 +634,22 @@ export function syncPayloadToDisk(
   payload: SyncPayload,
   options: SyncDiskOptions = {}
 ): SyncDiskResult {
+  const staged = stageSyncPayload(out, project, plan, payload, options)
+  try {
+    const warnings = withSyncLock(staged.appRoot, staged.publish)
+    return { destination: staged.destination, wasPresent: staged.wasPresent, warnings }
+  } finally {
+    staged.discard()
+  }
+}
+
+export function stageSyncPayload(
+  out: string,
+  project: string,
+  plan: SyncRequestPlan,
+  payload: SyncPayload,
+  options: SyncDiskOptions = {}
+): StagedSync {
   const target = parseSyncTarget(options.target)
   const now = options.now ?? (() => new Date())
   const set = payload.instructionSet
@@ -717,9 +760,11 @@ export function syncPayloadToDisk(
     assertExistingVersionMatches(destination, componentHashes, manifestBytes, generatedBytes)
   }
 
-  let warnings: string[] = []
-  try {
-    withSyncLock(appRoot, () => {
+  return {
+    appRoot,
+    destination,
+    wasPresent,
+    publish: () => {
       holdForProcessTest('ORIZU_TEST_SYNC_HOLD_BEFORE_PUBLISH_MS')
       const currentLock = readLock(appRoot, project)
       holdForProcessTest('ORIZU_TEST_SYNC_HOLD_LOCK_MS')
@@ -786,8 +831,9 @@ export function syncPayloadToDisk(
           }
           stagedTemp = null
         }
-        warnings = emitManagedArtifacts(out, appRoot, currentLock, options.forceHelpers ?? false, target, journal)
+        const warnings = emitManagedArtifacts(out, appRoot, currentLock, options.forceHelpers ?? false, target, journal)
         journal.write(join(appRoot, 'orizu.lock.json'), serializeLock(currentLock))
+        return warnings
       } catch (error) {
         journal.rollback()
         currentLock.helpers = priorHelpers
@@ -802,9 +848,10 @@ export function syncPayloadToDisk(
         }
         throw error
       }
-    })
-  } finally {
-    if (stagedTemp) rmSync(stagedTemp, { recursive: true, force: true })
+    },
+    discard: () => {
+      if (stagedTemp) rmSync(stagedTemp, { recursive: true, force: true })
+      stagedTemp = null
+    },
   }
-  return { destination, wasPresent, warnings }
 }

package/src/instruction-set-update/index.ts

@@ -11,7 +11,7 @@ import {
   type InstructionSetLockV1,
 } from '../instruction-set-lock/index.js'
 import { assertOutputConfined, reconcileGeneratedIndex } from '../instruction-set-sync/helpers.js'
-import { profileSlug, recordResolvedPayloadInLock, syncPayloadToDisk, withSyncLock, type SyncPayload } from '../instruction-set-sync/index.js'
+import { profileSlug, recordResolvedPayloadInLock, syncPayloadToDisk, withSyncLock, type SyncDiskResult, type SyncPayload } from '../instruction-set-sync/index.js'
 import { verifyInstructionSetTree, verifyMaterializedVersionAgainstLock } from '../instruction-set-verify/index.js'
 
 export interface UpdateResolution {
@@ -222,7 +222,8 @@ export async function applyUpdate(
   project: string,
   plan: UpdatePlan,
   noSync: boolean,
-  now: () => Date = () => new Date()
+  now: () => Date = () => new Date(),
+  sync: (...args: Parameters<typeof syncPayloadToDisk>) => SyncDiskResult | Promise<SyncDiskResult> = syncPayloadToDisk
 ): Promise<UpdateResult> {
   const absent: string[] = []
   const warnings: string[] = []
@@ -271,7 +272,7 @@ export async function applyUpdate(
   let lock = plan.lock
   for (const resolution of plan.resolutions) {
     const set = resolution.payload.instructionSet
-    const result = syncPayloadToDisk(out, project, {
+    const result = await sync(out, project, {
       parsed: { set: set.slug, profile: resolution.profileIdentity },
       path: '',
       lock,

package/src/instruction-sets-cli.ts

@@ -1,9 +1,9 @@
 import { authedFetch } from './http.js'
 import { INSTRUCTION_SET_COMPONENT_KEY } from './instruction-set-lock/index.js'
 import { loadInstructionSetManifest, MAX_INSTRUCTION_SET_COMPONENT_BYTES, type InstructionSetManifest } from './instruction-set-manifest.js'
-import { sanitizeHumanInlineText, sanitizeTerminalText } from './json-response.js'
-import { parseSyncTarget, planSyncRequest, syncPayloadToDisk, type SyncPayload, type SyncTarget } from './instruction-set-sync/index.js'
-import { applyPrune, applyUpdate, lockedProfileIdentity, makeUpdatePlan, planPrune, PruneKeepUnresolvedError, readUpdateLock } from './instruction-set-update/index.js'
+import { responsePayload, sanitizeHumanInlineText, sanitizeTerminalText } from './json-response.js'
+import { parseSyncTarget, planSyncRequest, type SyncTarget } from './instruction-set-sync/index.js'
+import { applyPrune, planPrune, PruneKeepUnresolvedError } from './instruction-set-update/index.js'
 import { printVerifyReport, verifyInstructionSetTree } from './instruction-set-verify/index.js'
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
@@ -74,12 +74,8 @@ function lifecycleOptionValues(args: string[], command: 'update' | 'prune', flag
   return values
 }
 
-async function responsePayload(response: Response, action: string): Promise<Record<string, unknown>> {
-  const payload = await response.json().catch(() => ({})) as Record<string, unknown>
-  if (!response.ok) {
-    throw new Error(`${action} failed (${response.status}): ${typeof payload.error === 'string' ? payload.error : response.statusText}`)
-  }
-  return payload
+function printInterrupted(io: InstructionSetsCommandIo, message: string) {
+  io.print(io.json ? JSON.stringify({ error: message }) : message)
 }
 
 const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/u
@@ -340,23 +336,14 @@ export async function instructionSetsCommand(args: string[], io: InstructionSets
   const project = await io.resolveProjectSlug(projectOption)
   if (subcommand === 'update') {
     const output = lifecycleOptionValues(args, 'update', '--out')[0] ?? '.'
-    const lock = readUpdateLock(output, project)
-    const payloads: SyncPayload[] = []
-    for (const [setSlug, set] of Object.entries(lock.instructionSets)) {
-      const barePath = `/api/cli/instruction-sets/${encodeURIComponent(setSlug)}/sync?project=${encodeURIComponent(project)}`
-      payloads.push(await responsePayload(await authedFetch(barePath, { method: 'GET' }), 'Instruction sets update') as unknown as SyncPayload)
-      for (const profileSlugValue of Object.keys(set.profiles)) {
-        const identity = lockedProfileIdentity(output, setSlug, profileSlugValue)
-        const query = new URLSearchParams({ project, profile: identity })
-        const path = `/api/cli/instruction-sets/${encodeURIComponent(setSlug)}/sync?${query.toString()}`
-        payloads.push(await responsePayload(await authedFetch(path, { method: 'GET' }), 'Instruction sets update') as unknown as SyncPayload)
-      }
-    }
-    const plan = makeUpdatePlan(project, lock, payloads)
     const isApproved = args.includes('--yes')
-    const result = isApproved
-      ? await applyUpdate(output, project, plan, args.includes('--no-sync'))
-      : { absent: [], warnings: [] }
+    const { updateInstructionSets } = await import('./instruction-delivery.js')
+    const updated = await updateInstructionSets(output, project, isApproved, args.includes('--no-sync'))
+    if ('interrupted' in updated) {
+      printInterrupted(io, 'Instruction sets update interrupted; some sets may already be updated. Run orizu instructions update again, then orizu instructions verify.')
+      return updated.interrupted
+    }
+    const { plan, result } = updated
     if (io.json) io.print(JSON.stringify({ plan: plan.lines, applied: isApproved, absent: result.absent, warnings: result.warnings }))
     else {
       for (const line of plan.lines) io.print(line)
@@ -527,11 +514,16 @@ export async function instructionSetsCommand(args: string[], io: InstructionSets
     if (unknownOption) throw new Error(`instruction_set_sync_option_unknown:${unknownOption}`)
     const output = requiredOptionValue(args, subcommand, '--out') ?? '.'
     const plan = planSyncRequest(reference, requiredOptionValue(args, subcommand, '--version'), output, project)
-    const payload = await responsePayload(await authedFetch(plan.path, { method: 'GET' }), 'Instruction sets sync') as unknown as SyncPayload
-    const result = syncPayloadToDisk(output, project, plan, payload, {
+    const { syncInstructionSet } = await import('./instruction-delivery.js')
+    const delivered = await syncInstructionSet(output, project, plan, {
       forceHelpers: args.includes('--force-helpers'),
       target: syncTarget!,
     })
+    if ('interrupted' in delivered) {
+      printInterrupted(io, 'Instruction set sync interrupted; any unpublished staged version was removed. Run orizu instructions sync again.')
+      return delivered.interrupted
+    }
+    const { payload, result } = delivered
     if (io.json) io.print(JSON.stringify({ ...payload, warnings: result.warnings }))
     else {
       io.print(`Synced ${reference} to ${result.destination}`)

package/src/json-response.ts

@@ -35,3 +35,11 @@ export async function parseJsonResponse<T>(
     )
   }
 }
+
+export async function responsePayload(response: Response, action: string): Promise<Record<string, unknown>> {
+  const payload = await response.json().catch(() => ({})) as Record<string, unknown>
+  if (!response.ok) {
+    throw new Error(`${action} failed (${response.status}): ${typeof payload.error === 'string' ? payload.error : response.statusText}`)
+  }
+  return payload
+}

package/src/last-error-record.ts

@@ -1,16 +1,3 @@
-import { randomBytes } from 'crypto'
-import {
-  chmodSync,
-  closeSync,
-  fsyncSync,
-  mkdirSync,
-  openSync,
-  readFileSync,
-  renameSync,
-  rmSync,
-  statSync,
-  writeFileSync,
-} from 'fs'
 import { homedir } from 'os'
 import { join } from 'path'
 
@@ -235,7 +222,7 @@ function resolveHomeDir(): string | null {
   }
 }
 
-function isStringWithinCap(
+export function isStringWithinCap(
   value: unknown,
   maximumCharacters: number,
   wasTruncated: boolean
@@ -247,45 +234,12 @@ function isStringWithinCap(
     && value.endsWith(LAST_ERROR_TRUNCATION_MARKER)
 }
 
-function boundedServerBaseUrl(value: string | null | undefined): string | null {
+export function boundedServerBaseUrl(value: string | null | undefined): string | null {
   return value && Buffer.byteLength(value, 'utf8') <= LAST_ERROR_SERVER_BASE_URL_MAX_BYTES
     ? value
     : null
 }
 
-function isLastErrorRecord(value: unknown): value is LastErrorRecord {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return false
-  const record = value as Partial<LastErrorRecord>
-  if (record.version !== LAST_ERROR_RECORD_VERSION) return false
-  if (typeof record.recordedAt !== 'string' || !Number.isFinite(Date.parse(record.recordedAt))) return false
-  if (typeof record.cliVersion !== 'string' && record.cliVersion !== null) return false
-  if (record.code !== undefined && record.code !== null && (
-    typeof record.code !== 'string'
-    || Array.from(record.code).length > LAST_ERROR_CODE_MAX_CHARS
-  )) return false
-  if (record.serverBaseUrl !== undefined && typeof record.serverBaseUrl !== 'string' && record.serverBaseUrl !== null) return false
-  if (record.teamSlug !== undefined && typeof record.teamSlug !== 'string' && record.teamSlug !== null) return false
-  if (typeof record.argvTruncated !== 'boolean') return false
-  const argvTruncated = record.argvTruncated
-  if (record.command !== null && !isStringWithinCap(
-    record.command,
-    LAST_ERROR_ARG_MAX_CHARS,
-    argvTruncated
-  )) return false
-  if (!Array.isArray(record.argv) || record.argv.length > LAST_ERROR_MAX_ARGS) return false
-  if (!record.argv.every(argument => isStringWithinCap(
-    argument,
-    LAST_ERROR_ARG_MAX_CHARS,
-    argvTruncated
-  ))) return false
-  if (typeof record.messageTruncated !== 'boolean') return false
-  return isStringWithinCap(
-    record.message,
-    LAST_ERROR_MESSAGE_MAX_CHARS,
-    record.messageTruncated
-  )
-}
-
 export function buildLastErrorRecord(input: LastErrorRecordInput): LastErrorRecord {
   const context: ScrubContext = {
     homeDir: input.homeDir ?? null,
@@ -350,15 +304,12 @@ export function getLastErrorRecordPath(configDir?: string): string {
   return join(configDir ?? getConfigDir(), LAST_ERROR_FILENAME)
 }
 
-export function writeLastErrorRecord(
+export async function writeLastErrorRecord(
   input: LastErrorRecordInput,
   options: WriteLastErrorRecordOptions = {}
-): void {
+): Promise<void> {
   try {
     const configDirectory = options.configDir ?? getConfigDir()
-    mkdirSync(configDirectory, { recursive: true, mode: 0o700 })
-    chmodSync(configDirectory, 0o700)
-
     const record = buildLastErrorRecord({
       ...input,
       homeDir: input.homeDir === undefined ? resolveHomeDir() : input.homeDir,
@@ -371,44 +322,19 @@ export function writeLastErrorRecord(
     const serialized = serializeRecord(record)
     if (Buffer.byteLength(serialized, 'utf8') > LAST_ERROR_FILE_MAX_BYTES) return
 
-    const path = getLastErrorRecordPath(configDirectory)
-    const temporaryPath = join(
-      configDirectory,
-      `.${LAST_ERROR_FILENAME}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`
-    )
-
-    try {
-      const fileDescriptor = openSync(temporaryPath, 'wx', 0o600)
-      try {
-        writeFileSync(fileDescriptor, serialized, 'utf8')
-        fsyncSync(fileDescriptor)
-      } finally {
-        closeSync(fileDescriptor)
-      }
-      chmodSync(temporaryPath, 0o600)
-      renameSync(temporaryPath, path)
-      chmodSync(path, 0o600)
-    } finally {
-      rmSync(temporaryPath, { force: true })
-    }
+    const { publishLastErrorRecord } = await import('./last-error-workflow.js')
+    await publishLastErrorRecord(configDirectory, serialized)
   } catch {
-    // A diagnostic record is best effort and must never replace the original CLI failure.
+    // A diagnostic record is best effort and must never replace the original CLI failure,
+    // including when Effect cannot load (a packed CLI without its dependencies).
   }
 }
 
-export function readLastErrorRecord(configDir?: string): LastErrorRecord | null {
+export async function readLastErrorRecord(configDir?: string): Promise<LastErrorRecord | null> {
   try {
     const path = getLastErrorRecordPath(configDir)
-    if (statSync(path).size > LAST_ERROR_FILE_MAX_BYTES) return null
-    const record = JSON.parse(readFileSync(path, 'utf8')) as unknown
-    return isLastErrorRecord(record)
-      ? {
-          ...record,
-          code: record.code ?? null,
-          serverBaseUrl: boundedServerBaseUrl(record.serverBaseUrl),
-          teamSlug: record.teamSlug ?? null,
-        }
-      : null
+    const { loadLastErrorRecord } = await import('./last-error-workflow.js')
+    return await loadLastErrorRecord(path)
   } catch {
     return null
   }

package/src/last-error-workflow.ts

@@ -0,0 +1,121 @@
+import { randomBytes } from 'crypto'
+import {
+  chmodSync,
+  closeSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'fs'
+import { join } from 'path'
+import { Effect, Schema } from 'effect'
+
+import {
+  LAST_ERROR_ARG_MAX_CHARS,
+  LAST_ERROR_CODE_MAX_CHARS,
+  LAST_ERROR_FILE_MAX_BYTES,
+  LAST_ERROR_MAX_ARGS,
+  LAST_ERROR_MESSAGE_MAX_CHARS,
+} from './last-error-caps.js'
+import {
+  boundedServerBaseUrl,
+  isStringWithinCap,
+  LAST_ERROR_FILENAME,
+  LAST_ERROR_RECORD_VERSION,
+  type LastErrorRecord,
+} from './last-error-record.js'
+
+// ORI-2450: Effect owns the last-error file's publication and reading.
+// last-error-record.ts loads this module with a literal dynamic import, so the
+// npm CLI only loads Effect on a failure or a feedback read, and the source
+// bundle still includes it.
+
+class LastErrorFileFailure extends Error {
+  constructor(readonly operation: string) {
+    super(`Could not ${operation}`)
+  }
+}
+
+const file = <A>(operation: string, action: () => A) => Effect.try({
+  try: action,
+  catch: () => new LastErrorFileFailure(operation),
+})
+
+const NullableString = Schema.NullOr(Schema.String)
+
+const LastErrorRecordSchema = Schema.Struct({
+  version: Schema.Literal(LAST_ERROR_RECORD_VERSION),
+  recordedAt: Schema.String.check(Schema.makeFilter(value => Number.isFinite(Date.parse(value)))),
+  cliVersion: NullableString,
+  code: Schema.optionalKey(NullableString.check(Schema.makeFilter(value =>
+    value === null || Array.from(value).length <= LAST_ERROR_CODE_MAX_CHARS))),
+  serverBaseUrl: Schema.optionalKey(NullableString),
+  teamSlug: Schema.optionalKey(NullableString),
+  command: NullableString,
+  argv: Schema.Array(Schema.String),
+  argvTruncated: Schema.Boolean,
+  message: Schema.String,
+  messageTruncated: Schema.Boolean,
+}).check(Schema.makeFilter(record =>
+  (record.command === null || isStringWithinCap(record.command, LAST_ERROR_ARG_MAX_CHARS, record.argvTruncated))
+  && record.argv.length <= LAST_ERROR_MAX_ARGS
+  && record.argv.every(argument => isStringWithinCap(argument, LAST_ERROR_ARG_MAX_CHARS, record.argvTruncated))
+  && isStringWithinCap(record.message, LAST_ERROR_MESSAGE_MAX_CHARS, record.messageTruncated)))
+
+const publication = (configDirectory: string, serialized: string) => Effect.gen(function*() {
+  yield* file('create directory', () => mkdirSync(configDirectory, { recursive: true, mode: 0o700 }))
+  yield* file('protect directory', () => chmodSync(configDirectory, 0o700))
+  const path = join(configDirectory, LAST_ERROR_FILENAME)
+  // Write a private temporary file, then rename it over the record, so a
+  // reader never sees a half-written record and a failed write keeps the old one.
+  yield* Effect.acquireUseRelease(
+    Effect.sync(() => join(
+      configDirectory,
+      `.${LAST_ERROR_FILENAME}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`
+    )),
+    temporaryPath => Effect.gen(function*() {
+      yield* Effect.acquireUseRelease(
+        file('open temporary record', () => openSync(temporaryPath, 'wx', 0o600)),
+        descriptor => Effect.gen(function*() {
+          yield* file('write temporary record', () => writeFileSync(descriptor, serialized, 'utf8'))
+          yield* file('flush temporary record', () => fsyncSync(descriptor))
+        }),
+        descriptor => Effect.sync(() => closeSync(descriptor)),
+      )
+      yield* file('protect temporary record', () => chmodSync(temporaryPath, 0o600))
+      yield* file('publish record', () => renameSync(temporaryPath, path))
+      yield* file('protect published record', () => chmodSync(path, 0o600))
+    }),
+    temporaryPath => Effect.sync(() => rmSync(temporaryPath, { force: true })),
+  )
+})
+
+export function publishLastErrorRecord(configDirectory: string, serialized: string): Promise<void> {
+  return Effect.runPromise(publication(configDirectory, serialized))
+}
+
+const loading = (path: string) => Effect.gen(function*() {
+  const stat = yield* file('inspect record', () => statSync(path))
+  if (stat.size > LAST_ERROR_FILE_MAX_BYTES) return null
+  const text = yield* file('read record', () => readFileSync(path, 'utf8'))
+  const raw = yield* file('parse record', () => JSON.parse(text) as unknown)
+  const record = yield* Schema.decodeUnknownEffect(LastErrorRecordSchema)(raw)
+  // The Schema checks the known fields; the reader has always kept any others.
+  const admitted: LastErrorRecord = {
+    ...(raw as Record<string, unknown>),
+    ...record,
+    argv: [...record.argv],
+    code: record.code ?? null,
+    serverBaseUrl: boundedServerBaseUrl(record.serverBaseUrl),
+    teamSlug: record.teamSlug ?? null,
+  }
+  return admitted
+})
+
+export function loadLastErrorRecord(path: string): Promise<LastErrorRecord | null> {
+  return Effect.runPromise(loading(path).pipe(Effect.orElseSucceed(() => null)))
+}

package/src/preview-runtime.ts

@@ -112,8 +112,8 @@ interface PreviewPage {
   screenshot: (options: { path: string; fullPage: boolean }) => Promise<unknown>
   waitForTimeout: (timeout: number) => Promise<unknown>
   once?: (event: string, listener: () => void) => unknown
-  on?: (event: string, listener: () => void) => unknown
-  off?: (event: string, listener: () => void) => unknown
+  on?: (event: string, listener: (error: Error) => void) => unknown
+  off?: (event: string, listener: (error: Error) => void) => unknown
 }
 
 function isNodeError(error: unknown): error is NodeJS.ErrnoException {
@@ -256,19 +256,32 @@ export async function runLocalAppPreview(options: AppPreviewOptions): Promise<Ap
       headless: !options.headed,
       ...(chromiumExecutablePath ? { executablePath: chromiumExecutablePath } : {}),
     })
-    const page = await browser.newPage({ viewport: { width: 1440, height: 1000 } })
-
+    let page: PreviewPage | null = null
+    let handleRenderError: ((error: Error) => void) | undefined
+    let hasFinishedKeepingOpen = false
     try {
-      await page.goto(url, { waitUntil: 'networkidle' })
-      await page.waitForSelector('[data-orizu-preview-ready="true"]', { timeout: 15_000 })
+      page = await browser.newPage({ viewport: { width: 1440, height: 1000 } })
+      const renderError = new Promise<never>((_, reject) => {
+        handleRenderError = error => reject(new Error(`App preview render failed: ${error.message}`))
+        page?.on?.('pageerror', handleRenderError)
+      })
+      // Listen before navigation: React can fail before the ready marker mounts.
+      await Promise.race([
+        page.goto(url, { waitUntil: 'networkidle' }).then(() =>
+          page!.waitForSelector('[data-orizu-preview-ready="true"]', { timeout: 15_000 })
+        ),
+        renderError,
+      ])
       if (options.screenshotPath) {
         await page.screenshot({ path: options.screenshotPath, fullPage: true })
       }
       if (options.keepOpen) {
         await waitForPreviewClose(page, browser)
+        hasFinishedKeepingOpen = true
       }
     } finally {
-      if (!options.keepOpen) {
+      if (handleRenderError) page?.off?.('pageerror', handleRenderError)
+      if (!hasFinishedKeepingOpen) {
         await browser.close()
       }
     }
@@ -826,7 +839,8 @@ export default TextContent
 import React from 'react'
 function cn(...values) { return values.filter(Boolean).join(' ') }
 export function CodeBlock({ code, children, className, ...props }) {
-  return <pre {...props} className={cn('overflow-auto rounded-md border bg-muted p-3 font-mono text-xs', className)}><code>{children ?? code}</code></pre>
+  const codeText = Array.isArray(code) ? code.map(line => line.content).join('\\n') : code
+  return <pre {...props} className={cn('overflow-auto rounded-md border bg-muted p-3 font-mono text-xs', className)}><code>{children ?? codeText}</code></pre>
 }
 export default CodeBlock
 `
@@ -843,8 +857,24 @@ export default Prose
   const contentRendererSource = `
 import React from 'react'
 function cn(...values) { return values.filter(Boolean).join(' ') }
-export function ContentRenderer({ content, children, className, ...props }) {
-  return <div {...props} className={cn('whitespace-pre-wrap text-sm leading-relaxed', className)}>{children ?? content}</div>
+export function ContentRenderer({ contentType, content, maxHeight = '400px', customRenderer, className }) {
+  let renderedContent
+  switch (contentType) {
+    case 'image':
+      renderedContent = <div className="flex items-center justify-center p-2"><img src={content} alt="Content" width={800} height={600} className="max-w-full object-contain" style={{ maxHeight, height: 'auto', width: 'auto' }} /></div>
+      break
+    case 'video':
+      renderedContent = <div className="flex h-full justify-center p-2"><video src={content} controls className="max-h-full max-w-full" /></div>
+      break
+    case 'custom':
+      renderedContent = customRenderer ? customRenderer({ content }) : <p className="text-destructive">Custom renderer required for custom content type</p>
+      break
+    default:
+      renderedContent = <p>Invalid content type</p>
+  }
+  return maxHeight
+    ? <div className={cn('overflow-auto', className)} style={{ maxHeight }}>{renderedContent}</div>
+    : renderedContent
 }
 export default ContentRenderer
 `