@agent-native/core 0.114.12 → 0.114.13

package/corpus/README.md

@@ -30,4 +30,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 - core files: 1519
 - toolkit files: 137
-- template files: 6178
+- template files: 6185

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @agent-native/core
 
+## 0.114.13
+
+### Patch Changes
+
+- 7112c17: Add portable transactional multi-key application-state compare-and-set operations, including atomic D1 batch support and missing-key creation for race-safe UI workflows.
+
 ## 0.114.12
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.114.12",
+  "version": "0.114.13",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {

package/corpus/core/src/application-state/index.ts

@@ -5,8 +5,10 @@ export {
   appStatePut,
   appStateDelete,
   appStateCompareAndSet,
+  appStateCompareAndSetMany,
   appStateList,
   appStateDeleteByPrefix,
+  type AppStateCompareAndSetOperation,
 } from "./store.js";
 
 // Emitter (for SSE wiring)
@@ -35,6 +37,7 @@ export {
   writeAppState,
   deleteAppState,
   compareAndSetAppState,
+  compareAndSetManyAppState,
   listAppState,
   deleteAppStateByPrefix,
   readAppStateForCurrentTab,

package/corpus/core/src/application-state/script-helpers.ts

@@ -18,8 +18,10 @@ import {
   appStatePut,
   appStateDelete,
   appStateCompareAndSet,
+  appStateCompareAndSetMany,
   appStateList,
   appStateDeleteByPrefix,
+  type AppStateCompareAndSetOperation,
 } from "./store.js";
 
 /**
@@ -74,7 +76,7 @@ export async function deleteAppState(key: string): Promise<boolean> {
 
 export async function compareAndSetAppState(
   key: string,
-  expectedValue: Record<string, unknown>,
+  expectedValue: Record<string, unknown> | null,
   nextValue: Record<string, unknown> | null,
 ): Promise<boolean> {
   const sessionId = await resolveSessionId();
@@ -83,6 +85,15 @@ export async function compareAndSetAppState(
   });
 }
 
+export async function compareAndSetManyAppState(
+  operations: readonly AppStateCompareAndSetOperation[],
+): Promise<boolean> {
+  const sessionId = await resolveSessionId();
+  return appStateCompareAndSetMany(sessionId, operations, {
+    requestSource: "agent",
+  });
+}
+
 export async function listAppState(
   prefix: string,
 ): Promise<Array<{ key: string; value: Record<string, unknown> }>> {

package/corpus/core/src/application-state/store.ts

@@ -1,9 +1,11 @@
 import {
   getDbExec,
+  getDialect,
   isLocalDatabase,
   isConnectionError,
   isPostgres,
   intType,
+  type DbExec,
 } from "../db/client.js";
 import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
 import { widenIntColumnsToBigInt } from "../db/widen-columns.js";
@@ -194,39 +196,238 @@ export async function appStateDelete(
 export async function appStateCompareAndSet(
   sessionId: string,
   key: string,
-  expectedValue: Record<string, unknown>,
+  expectedValue: Record<string, unknown> | null,
   nextValue: Record<string, unknown> | null,
   options?: StoreWriteOptions,
 ): Promise<boolean> {
   await ensureTable();
   const client = getDbExec();
+  const changed = await executeAppStateCompareAndSet(
+    client,
+    sessionId,
+    key,
+    expectedValue,
+    nextValue,
+  );
+  if (changed) {
+    if (nextValue === null) {
+      emitAppStateDelete(key, options?.requestSource, sessionId);
+    } else {
+      emitAppStateChange(key, options?.requestSource, sessionId);
+    }
+  }
+  return changed;
+}
+
+export interface AppStateCompareAndSetOperation {
+  key: string;
+  expectedValue: Record<string, unknown> | null;
+  nextValue: Record<string, unknown> | null;
+}
+
+const APP_STATE_CAS_MISMATCH = Symbol("app-state-cas-mismatch");
+
+async function executeAppStateCompareAndSet(
+  client: DbExec,
+  sessionId: string,
+  key: string,
+  expectedValue: Record<string, unknown> | null,
+  nextValue: Record<string, unknown> | null,
+): Promise<boolean> {
+  const statement = buildAppStateCompareAndSetStatement(
+    sessionId,
+    key,
+    expectedValue,
+    nextValue,
+  );
+  const result = await client.execute(statement);
+  return result.rowsAffected > 0;
+}
+
+function buildAppStateCompareAndSetStatement(
+  sessionId: string,
+  key: string,
+  expectedValue: Record<string, unknown> | null,
+  nextValue: Record<string, unknown> | null,
+): { sql: string; args: unknown[] } {
+  if (expectedValue === null) {
+    if (nextValue === null) {
+      throw new Error(
+        "Application state CAS cannot replace absence with absence.",
+      );
+    }
+    const next = serializeAppStateValue(key, nextValue);
+    return {
+      sql: isPostgres()
+        ? `INSERT INTO application_state (session_id, key, value, updated_at) SELECT ?, ?, ?, ? WHERE NOT EXISTS (SELECT 1 FROM application_state WHERE session_id = ? AND key = ?) ON CONFLICT (session_id, key) DO NOTHING`
+        : `INSERT OR IGNORE INTO application_state (session_id, key, value, updated_at) SELECT ?, ?, ?, ? WHERE NOT EXISTS (SELECT 1 FROM application_state WHERE session_id = ? AND key = ?)`,
+      args: [sessionId, key, next, Date.now(), sessionId, key],
+    };
+  }
+
   const expected = JSON.stringify(expectedValue);
   if (nextValue === null) {
-    const result = await client.execute({
+    return {
       sql: `DELETE FROM application_state WHERE session_id = ? AND key = ? AND value = ?`,
       args: [sessionId, key, expected],
-    });
-    const changed = result.rowsAffected > 0;
-    if (changed) emitAppStateDelete(key, options?.requestSource, sessionId);
-    return changed;
+    };
   }
 
-  const next = JSON.stringify(nextValue);
+  const next = serializeAppStateValue(key, nextValue);
+  return {
+    sql: `UPDATE application_state SET value = ?, updated_at = ? WHERE session_id = ? AND key = ? AND value = ?`,
+    args: [next, Date.now(), sessionId, key, expected],
+  };
+}
+
+function buildD1CompareAndSetGuard(
+  sessionId: string,
+  guardKey: string,
+  operation: AppStateCompareAndSetOperation,
+): { sql: string; args: unknown[] } {
+  const expected = operation.expectedValue;
+  const condition =
+    expected === null
+      ? "NOT EXISTS (SELECT 1 FROM application_state WHERE session_id = ? AND key = ?)"
+      : "EXISTS (SELECT 1 FROM application_state WHERE session_id = ? AND key = ? AND value = ?)";
+  return {
+    sql: `INSERT INTO application_state (session_id, key, value, updated_at) SELECT ?, ?, '{}', ? WHERE NOT (${condition})`,
+    args:
+      expected === null
+        ? [sessionId, guardKey, Date.now(), sessionId, operation.key]
+        : [
+            sessionId,
+            guardKey,
+            Date.now(),
+            sessionId,
+            operation.key,
+            JSON.stringify(expected),
+          ],
+  };
+}
+
+function isD1CompareAndSetMismatch(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /unique constraint failed:\s*application_state\.session_id,\s*application_state\.key/i.test(
+    message,
+  );
+}
+
+function serializeAppStateValue(
+  key: string,
+  value: Record<string, unknown>,
+): string {
+  const serialized = JSON.stringify(value);
   if (
     !isLocalDatabase() &&
-    Buffer.byteLength(next, "utf8") > MAX_HOSTED_APP_STATE_VALUE_BYTES
+    Buffer.byteLength(serialized, "utf8") > MAX_HOSTED_APP_STATE_VALUE_BYTES
   ) {
     throw new Error(
       `application_state value "${key}" is too large for hosted SQL storage. Store large files, base64, or blobs in file storage and write only a URL or handle.`,
     );
   }
-  const result = await client.execute({
-    sql: `UPDATE application_state SET value = ?, updated_at = ? WHERE session_id = ? AND key = ? AND value = ?`,
-    args: [next, Date.now(), sessionId, key, expected],
-  });
-  const changed = result.rowsAffected > 0;
-  if (changed) emitAppStateChange(key, options?.requestSource, sessionId);
-  return changed;
+  return serialized;
+}
+
+export async function appStateCompareAndSetMany(
+  sessionId: string,
+  operations: readonly AppStateCompareAndSetOperation[],
+  options?: StoreWriteOptions,
+): Promise<boolean> {
+  if (operations.length === 0) return true;
+  const keys = new Set(operations.map(({ key }) => key));
+  if (keys.size !== operations.length) {
+    throw new Error("Application state multi-key CAS requires unique keys.");
+  }
+  for (const { key, nextValue } of operations) {
+    if (nextValue) serializeAppStateValue(key, nextValue);
+  }
+  const orderedOperations = [...operations].sort((a, b) =>
+    a.key.localeCompare(b.key),
+  );
+
+  await ensureTable();
+  const client = getDbExec();
+  if (getDialect() === "d1") {
+    if (!client.atomicBatch) {
+      throw new Error(
+        "D1 application-state CAS requires atomic batch support.",
+      );
+    }
+    const guardKey = `__agent_native_cas_guard__:${Date.now()}:${Math.random().toString(36).slice(2)}`;
+    const guardInsert = {
+      sql: `INSERT INTO application_state (session_id, key, value, updated_at) VALUES (?, ?, '{}', ?)`,
+      args: [sessionId, guardKey, Date.now()],
+    };
+    const guards = orderedOperations.map((operation) =>
+      buildD1CompareAndSetGuard(sessionId, guardKey, operation),
+    );
+    const mutations = orderedOperations.map((operation) =>
+      buildAppStateCompareAndSetStatement(
+        sessionId,
+        operation.key,
+        operation.expectedValue,
+        operation.nextValue,
+      ),
+    );
+    let results;
+    try {
+      results = await client.atomicBatch([
+        guardInsert,
+        ...guards,
+        ...mutations,
+        {
+          sql: `DELETE FROM application_state WHERE session_id = ? AND key = ?`,
+          args: [sessionId, guardKey],
+        },
+      ]);
+    } catch (error) {
+      if (isD1CompareAndSetMismatch(error)) return false;
+      throw error;
+    }
+    const mutationResults = results.slice(
+      1 + guards.length,
+      1 + guards.length + mutations.length,
+    );
+    if (
+      mutationResults.length !== mutations.length ||
+      mutationResults.some((result) => result.rowsAffected !== 1)
+    ) {
+      throw new Error(
+        "D1 application-state CAS completed without applying every mutation.",
+      );
+    }
+  } else {
+    if (!client.transaction) {
+      throw new Error("Application state multi-key CAS requires transactions.");
+    }
+    try {
+      await client.transaction(async (tx) => {
+        for (const operation of orderedOperations) {
+          const changed = await executeAppStateCompareAndSet(
+            tx,
+            sessionId,
+            operation.key,
+            operation.expectedValue,
+            operation.nextValue,
+          );
+          if (!changed) throw APP_STATE_CAS_MISMATCH;
+        }
+      });
+    } catch (error) {
+      if (error === APP_STATE_CAS_MISMATCH) return false;
+      throw error;
+    }
+  }
+
+  for (const { key, nextValue } of operations) {
+    if (nextValue === null) {
+      emitAppStateDelete(key, options?.requestSource, sessionId);
+    } else {
+      emitAppStateChange(key, options?.requestSource, sessionId);
+    }
+  }
+  return true;
 }
 
 export async function appStateList(

package/corpus/core/src/db/client.ts

@@ -29,6 +29,9 @@ export interface DbExec {
     sql: string | { sql: string; args?: unknown[] },
   ): Promise<{ rows: any[]; rowsAffected: number }>;
   transaction?<T>(fn: (tx: DbExec) => Promise<T>): Promise<T>;
+  atomicBatch?(
+    statements: readonly (string | { sql: string; args?: unknown[] })[],
+  ): Promise<Array<{ rows: any[]; rowsAffected: number }>>;
   /**
    * Release the underlying connection/pool held by this exec.
    * Only non-singleton execs created via `createDbExec()` (e.g. the migration
@@ -1100,7 +1103,17 @@ async function createDbExecInternal(
     };
     return {
       execute,
-      transaction: explicitTransaction(execute),
+      async atomicBatch(statements) {
+        const prepared = statements.map((statement) => {
+          if (typeof statement === "string") return d1.prepare(statement);
+          return d1.prepare(statement.sql).bind(...(statement.args ?? []));
+        });
+        const results = await d1.batch(prepared);
+        return results.map((result: any) => ({
+          rows: result.results || [],
+          rowsAffected: result.meta?.changes ?? 0,
+        }));
+      },
     };
   }
 
@@ -1558,6 +1571,10 @@ export function getDbExec(): DbExec {
       // After init, swap to a sanitizing wrapper around the real client
       const wrapper: DbExec = {
         execute: (s) => _exec!.execute(sanitize(s)),
+        atomicBatch: _exec!.atomicBatch
+          ? (statements) =>
+              _exec!.atomicBatch!(statements.map((s) => sanitize(s)))
+          : undefined,
         transaction: _exec!.transaction
           ? (fn) =>
               _exec!.transaction!((tx) =>
@@ -1582,6 +1599,10 @@ export function getDbExec(): DbExec {
       }
       const wrapper: DbExec = {
         execute: (s) => _exec!.execute(sanitize(s)),
+        atomicBatch: _exec!.atomicBatch
+          ? (statements) =>
+              _exec!.atomicBatch!(statements.map((s) => sanitize(s)))
+          : undefined,
         transaction: _exec!.transaction
           ? (innerFn) =>
               _exec!.transaction!((tx) =>
@@ -1601,8 +1622,30 @@ export function getDbExec(): DbExec {
           }),
         );
       }
+      if (_exec!.atomicBatch) {
+        throw new Error(
+          "This database supports atomic batches, not interactive transactions.",
+        );
+      }
       return explicitTransaction(wrapper.execute)(fn);
     },
+    async atomicBatch(statements) {
+      if (!_initPromise) _initPromise = initClient();
+      try {
+        await _initPromise;
+      } catch (err) {
+        _initPromise = undefined;
+        _exec = undefined;
+        throw err;
+      }
+      if (!_exec!.atomicBatch) {
+        throw new Error("This database does not support atomic batches.");
+      }
+      const batch = (items: typeof statements) =>
+        _exec!.atomicBatch!(items.map((item) => sanitize(item)));
+      Object.assign(proxy, { atomicBatch: batch });
+      return batch(statements);
+    },
   };
   return proxy;
 }

package/corpus/templates/clips/changelog/2026-07-21-live-dictation-text-now-appears-above-the-desktop-recording-.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-21
+---
+
+Live dictation text now appears above the desktop recording pill.

package/corpus/templates/clips/desktop/src/lib/voice-dictation.ts

@@ -1445,6 +1445,9 @@ export function installDesktopVoiceDictation(
         // the tail because Web Speech only marks a segment as `isFinal`
         // after a confidence-threshold pass.
         next.browserTranscript = (finalSoFar + interim).trim();
+        emit("voice:dictation-preview", {
+          text: next.browserTranscript,
+        }).catch(() => {});
       };
       recognition.onerror = (ev) => {
         if (ev.error !== "no-speech" && ev.error !== "aborted") {
@@ -2038,15 +2041,16 @@ export function installDesktopVoiceDictation(
 
   // Native (SFSpeechRecognizer) event subscriptions. These are always
   // installed — the events only fire when the Rust side has an active
-  // session, so subscribing on non-native sessions is harmless. The
-  // flow-bar listens to `voice:partial-transcript` independently so we
-  // don't re-emit it here.
+  // session, so subscribing on non-native sessions is harmless.
   onPartialTranscript(({ text }) => {
     const current = session;
     if (!current || (current.kind !== "native" && current.kind !== "whisper"))
       return;
     if (current.cancelled || current.stopping) return;
     setInterimTranscript(current, text);
+    emit("voice:dictation-preview", {
+      text: current.browserTranscript,
+    }).catch(() => {});
   })
     .then((u) => unlistens.push(u))
     .catch(() => {});
@@ -2065,6 +2069,13 @@ export function installDesktopVoiceDictation(
     if (!current) return;
     if (current.cancelled) return;
     appendFinalTranscript(current, text);
+    const supersededLingeringSession =
+      current === lingeringSession && session !== null && session !== current;
+    if (!supersededLingeringSession) {
+      emit("voice:dictation-preview", {
+        text: current.browserTranscript,
+      }).catch(() => {});
+    }
     if (current === lingeringSession) {
       current.onNativeFinalize?.();
     }

package/corpus/templates/clips/desktop/src/overlays/flow-bar.tsx

@@ -16,6 +16,7 @@ type FlowState = "idle" | "recording" | "processing" | "complete" | "error";
  * Events:
  *   - `voice:state-change` { state: "idle"|"recording"|"processing"|"complete"|"error" }
  *   - `voice:audio-level` { level: number } (0-1) for waveform visualization
+ *   - `voice:dictation-preview` { text: string }
  */
 export function FlowBar() {
   // Default to "recording" not "idle" — there's a race between the Rust
@@ -23,6 +24,8 @@ export function FlowBar() {
   // "idle" caused the bar to flash an "EN" language pill that never went
   // away if the start event was missed.
   const [state, setState] = useState<FlowState>("recording");
+  const [transcript, setTranscript] = useState("");
+  const transcriptRef = useRef<HTMLDivElement | null>(null);
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
   const levelRef = useRef(0);
   const rafRef = useRef<number | null>(null);
@@ -48,6 +51,7 @@ export function FlowBar() {
     trackListen(
       listen<{ state: FlowState }>("voice:state-change", (ev) => {
         setState(ev.payload.state);
+        if (ev.payload.state === "recording") setTranscript("");
       }),
     );
 
@@ -57,6 +61,12 @@ export function FlowBar() {
       }),
     );
 
+    trackListen(
+      listen<{ text: string }>("voice:dictation-preview", (ev) => {
+        setTranscript(ev.payload.text.trim());
+      }),
+    );
+
     return () => {
       stopped = true;
       unlistens.forEach((u) => {
@@ -70,6 +80,11 @@ export function FlowBar() {
     };
   }, []);
 
+  useEffect(() => {
+    const preview = transcriptRef.current;
+    if (preview) preview.scrollTop = preview.scrollHeight;
+  }, [transcript]);
+
   // Waveform canvas rendering loop — only runs during the "recording" state.
   useEffect(() => {
     if (state !== "recording") {
@@ -151,6 +166,16 @@ export function FlowBar() {
 
   return (
     <div className="flow-bar-root">
+      {transcript ? (
+        <div
+          ref={transcriptRef}
+          className="flow-bar-transcript-preview"
+          aria-live="polite"
+        >
+          {transcript}
+        </div>
+      ) : null}
+
       {/* Pill is ALWAYS mounted — when state goes idle we fade the
           opacity to 0 (see CSS) instead of removing it from the DOM.
           Inner content keeps its last frame rendered during the fade

package/corpus/templates/clips/desktop/src/styles.css

@@ -4905,13 +4905,33 @@ body[data-clips-route="recording-pill"] #root {
   position: fixed;
   inset: var(--overlay-shadow-gutter);
   display: flex;
+  flex-direction: column;
   align-items: center;
   justify-content: flex-end;
+  gap: 6px;
   padding-bottom: 8px;
   background: transparent;
   pointer-events: none;
 }
 
+.flow-bar-transcript-preview {
+  max-width: 560px;
+  max-height: 90px;
+  padding: 5px 10px;
+  overflow: hidden;
+  border: 1px solid rgba(255, 255, 255, 0.06);
+  border-radius: 10px;
+  background: rgba(18, 18, 20, 0.92);
+  color: rgba(255, 255, 255, 0.9);
+  font-size: 12px;
+  font-weight: 500;
+  line-height: 18px;
+  text-align: center;
+  word-break: break-word;
+  backdrop-filter: blur(20px);
+  -webkit-backdrop-filter: blur(20px);
+}
+
 .flow-bar {
   display: flex;
   align-items: center;

package/corpus/templates/clips/desktop/src-tauri/src/clips/mod.rs

@@ -1506,10 +1506,9 @@ pub async fn show_flow_bar(app: AppHandle) -> Result<(), String> {
 
     let (mx, my, mw, mh) = tray_monitor_physical_rect(&app);
     let scale = overlay_scale_factor(&app);
-    // Compact Wispr-style pill window: just enough transparent canvas for
-    // the bottom-centered waveform bar and its shadow gutter.
-    let content_w: u32 = (160.0 * scale).round() as u32;
-    let content_h: u32 = (56.0 * scale).round() as u32;
+    // Wide + tall enough for a 5-line transcript preview above the pill.
+    let content_w: u32 = (640.0 * scale).round() as u32;
+    let content_h: u32 = (160.0 * scale).round() as u32;
     let bottom_margin: i32 = (14.0 * scale).round() as i32;
     let gutter = overlay_shadow_gutter_physical(&app);
     let w: u32 = content_w + gutter * 2;

package/corpus/templates/clips/desktop/src-tauri/src/native_screen/custom_capture.rs

@@ -2465,8 +2465,15 @@ impl LiveAudioMixer {
     }
 
     /// Emit mixed sample buffers covering `out_pos..safe_end` in
-    /// `MIX_CHUNK_FRAMES` chunks: sum system + mic per frame, clamp, wrap as
-    /// LPCM `CMSampleBuffer`s with contiguous PTS.
+    /// `MIX_CHUNK_FRAMES` chunks: average system + mic per frame, clamp, wrap
+    /// as LPCM `CMSampleBuffer`s with contiguous PTS.
+    ///
+    /// Each source is weighted at 0.5 before summing so that two full-scale
+    /// signals (which occurs when a USB audio interface with software monitoring
+    /// routes the mic back through system audio) can never exceed ±1.0 and
+    /// hard-clip. The standard SCK pipeline applies the same 0.5×L + 0.5×R
+    /// pan-downmix for the same reason; loudnorm restores the target loudness
+    /// in post-processing.
     fn drain_ready(
         &mut self,
         flush: bool,
@@ -2488,8 +2495,8 @@ impl LiveAudioMixer {
                 let frame = a + f as i64;
                 let (sl, sr) = self.system.sample_at(frame);
                 let (ml, mr) = self.mic.sample_at(frame);
-                interleaved[f * 2] = (sl + ml).clamp(-1.0, 1.0);
-                interleaved[f * 2 + 1] = (sr + mr).clamp(-1.0, 1.0);
+                interleaved[f * 2] = (sl * 0.5 + ml * 0.5).clamp(-1.0, 1.0);
+                interleaved[f * 2 + 1] = (sr * 0.5 + mr * 0.5).clamp(-1.0, 1.0);
             }
             emitted.push(self.build_sample_buffer(&interleaved, a)?);
             a = b;

package/corpus/templates/design/AGENTS.md

@@ -288,11 +288,15 @@ ladder.
   `view-screen`; not rendered as canvas overlays).
 - `design-reprompt-pending:<designId>:<fileId>` is the client-captured source
   selection, instruction, base hash, and authoritative current request id for
-  a scoped regenerate request.
+  a scoped regenerate request. The frontend starts requests through the
+  compare-and-set `begin-node-rewrite-request` action and must not overwrite a
+  `resolving` acceptance reservation.
 - `design-reprompt-proposal:<designId>:<fileId>:<repromptId>` is one
   request-specific preview-only subtree proposal. Candidate payloads have a
-  256 KiB aggregate serialized limit. Resolution and cancellation use atomic
-  compare-and-set cleanup so an older request cannot erase a newer one.
+  256 KiB aggregate serialized limit. Proposal publication, resolution, and
+  cancellation use atomic multi-key compare-and-set transitions. Acceptance
+  reserves its matching pending request before writing design content, so a
+  newer request and an older acceptance cannot both win.
   `view-screen` lists only proposals paired to the current pending request as
   `pendingCandidateReviews`.
 - `show-design-questions` opens focused pre-generation questions in the main