@agent-native/core 0.90.5 → 0.90.7

package/corpus/core/src/server/core-routes-plugin.ts

@@ -8,6 +8,7 @@ import {
   setCookie,
   deleteCookie,
   getRequestURL,
+  getRequestIP,
 } from "h3";
 import type { H3Event } from "h3";
 import { readMultipartFormData } from "h3";
@@ -285,9 +286,16 @@ const BUILDER_WAITLIST_DEFAULT_USE_CASE = "builder_agent_background_coding";
 const BUILDER_WAITLIST_USE_CASES = new Set([
   BUILDER_WAITLIST_DEFAULT_USE_CASE,
   "design_publish_app",
+  "docs_build_online_waitlist",
 ]);
 const BUILDER_WAITLIST_FORM_TIMEOUT_MS = 8000;
 const BUILDER_WAITLIST_TEXT_LIMIT = 4000;
+const BUILDER_WAITLIST_RATE_LIMIT_WINDOW_MS = 60_000;
+const BUILDER_WAITLIST_RATE_LIMIT_MAX = 5;
+const builderWaitlistRateLimitHits = new Map<
+  string,
+  { count: number; resetAt: number }
+>();
 
 interface BuilderWaitlistFormTarget {
   formId: string;
@@ -295,6 +303,7 @@ interface BuilderWaitlistFormTarget {
 }
 
 export interface BuilderWaitlistBody {
+  email?: unknown;
   prompt?: unknown;
   orgName?: unknown;
   appUrl?: unknown;
@@ -332,6 +341,106 @@ function normalizeBuilderWaitlistUseCase(value: unknown): string {
     : BUILDER_WAITLIST_DEFAULT_USE_CASE;
 }
 
+function isValidWaitlistEmail(email: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+}
+
+export function isAnonymousWaitlistSessionEmail(email: string): boolean {
+  return email.startsWith("anon-") && email.endsWith("@agent-native.com");
+}
+
+export function resolveWaitlistEmail(
+  sessionEmail: string | undefined,
+  bodyEmail: unknown,
+): string | null {
+  const provided = cleanBuilderWaitlistText(bodyEmail, 320);
+  if (provided && isValidWaitlistEmail(provided)) return provided;
+  if (sessionEmail && !isAnonymousWaitlistSessionEmail(sessionEmail)) {
+    return sessionEmail;
+  }
+  return null;
+}
+
+function normalizeWaitlistRateLimitPart(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+function getBuilderWaitlistClientIp(event: H3Event): string | undefined {
+  const trusted =
+    getHeader(event, "x-nf-client-connection-ip") ??
+    getHeader(event, "cf-connecting-ip") ??
+    getHeader(event, "true-client-ip") ??
+    getHeader(event, "x-real-ip");
+  if (trusted && trusted.trim()) return trusted.trim();
+
+  const forwardedFor = getHeader(event, "x-forwarded-for");
+  const forwardedClientIp = forwardedFor?.split(",")[0]?.trim();
+  if (forwardedClientIp) return forwardedClientIp;
+
+  try {
+    return getRequestIP(event) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function getBuilderWaitlistRateLimitKeys(
+  event: H3Event,
+  email: string,
+): string[] {
+  const clientIp = getBuilderWaitlistClientIp(event);
+  return [
+    `email:${normalizeWaitlistRateLimitPart(email)}`,
+    `ip:${normalizeWaitlistRateLimitPart(clientIp ?? "unknown")}`,
+  ];
+}
+
+export function checkBuilderWaitlistRateLimit(
+  event: H3Event,
+  email: string,
+  now = Date.now(),
+): { ok: true } | { ok: false; retryAfterSeconds: number } {
+  const keys = getBuilderWaitlistRateLimitKeys(event, email);
+  let retryAfterMs = 0;
+
+  for (const key of keys) {
+    const entry = builderWaitlistRateLimitHits.get(key);
+    if (!entry) continue;
+    if (entry.resetAt <= now) {
+      builderWaitlistRateLimitHits.delete(key);
+      continue;
+    }
+    if (entry.count >= BUILDER_WAITLIST_RATE_LIMIT_MAX) {
+      retryAfterMs = Math.max(retryAfterMs, entry.resetAt - now);
+    }
+  }
+
+  if (retryAfterMs > 0) {
+    return {
+      ok: false,
+      retryAfterSeconds: Math.max(1, Math.ceil(retryAfterMs / 1000)),
+    };
+  }
+
+  for (const key of keys) {
+    const entry = builderWaitlistRateLimitHits.get(key);
+    if (!entry || entry.resetAt <= now) {
+      builderWaitlistRateLimitHits.set(key, {
+        count: 1,
+        resetAt: now + BUILDER_WAITLIST_RATE_LIMIT_WINDOW_MS,
+      });
+    } else {
+      entry.count += 1;
+    }
+  }
+
+  return { ok: true };
+}
+
+export function resetBuilderWaitlistRateLimitForTests() {
+  builderWaitlistRateLimitHits.clear();
+}
+
 function normalizeHttpOrigin(value: string): string | null {
   try {
     const url = new URL(value);
@@ -1869,15 +1978,35 @@ export function createCoreRoutesPlugin(
             return { error: "Method not allowed" };
           }
           const session = await getSession(event).catch(() => null);
-          if (!session?.email) {
-            setResponseStatus(event, 401);
-            return { error: "Authentication required" };
-          }
           const body = ((await readBody(event).catch(() => ({}))) ??
             {}) as BuilderWaitlistBody;
+          const waitlistEmail = resolveWaitlistEmail(
+            session?.email,
+            body.email,
+          );
+          if (!waitlistEmail) {
+            setResponseStatus(event, 400);
+            return { error: "Valid email required" };
+          }
+          const waitlistRateLimit = checkBuilderWaitlistRateLimit(
+            event,
+            waitlistEmail,
+          );
+          if (!waitlistRateLimit.ok) {
+            setResponseStatus(event, 429);
+            setResponseHeader(
+              event,
+              "Retry-After",
+              String(waitlistRateLimit.retryAfterSeconds),
+            );
+            return {
+              error:
+                "Too many waitlist requests. Please try again in a minute.",
+            };
+          }
           const waitlistPayload = buildBuilderWaitlistFormPayload(
             event,
-            session.email,
+            waitlistEmail,
             body,
           );
           const waitlistSource = waitlistPayload.data.source;
@@ -1886,14 +2015,14 @@ export function createCoreRoutesPlugin(
           try {
             formSubmission = await submitBuilderWaitlistForm(
               event,
-              session.email,
+              waitlistEmail,
               body,
             );
           } catch (err) {
             await trackBuilderLifecycle(
               event,
               "builder branch waitlist form failed",
-              session.email,
+              waitlistEmail,
               {
                 reason:
                   err instanceof Error ? err.message : "unknown_waitlist_error",
@@ -1911,7 +2040,7 @@ export function createCoreRoutesPlugin(
           await trackBuilderLifecycle(
             event,
             "builder branch waitlist joined",
-            session.email,
+            waitlistEmail,
             {
               formId: formSubmission.formId ?? null,
               formSubmitted: formSubmission.submitted,

package/corpus/templates/clips/changelog/2026-07-07-faster-local-whisper-dictation-start.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-07
+---
+
+Dictation starts faster when using Local Whisper after the first press.

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

@@ -124,7 +124,7 @@ pub(crate) mod macos {
     use std::ffi::c_void;
     use std::mem::size_of;
     use std::ptr::NonNull;
-    use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+    use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, Ordering};
     use std::sync::{Arc, Mutex, OnceLock};
 
     use block2::{RcBlock, StackBlock};
@@ -134,7 +134,7 @@ pub(crate) mod macos {
         kAudioOutputUnitProperty_CurrentDevice, kAudioUnitScope_Global, AudioUnitSetProperty,
     };
     use objc2_avf_audio::{
-        AVAudioEngine, AVAudioPCMBuffer, AVAudioTime,
+        AVAudioEngine, AVAudioInputNode, AVAudioPCMBuffer, AVAudioTime,
         AVAudioVoiceProcessingOtherAudioDuckingConfiguration,
         AVAudioVoiceProcessingOtherAudioDuckingLevel,
     };
@@ -211,6 +211,51 @@ pub(crate) mod macos {
     // inner pointers across threads — the session is moved through a Mutex.
     unsafe impl Send for SpeechSession {}
 
+    #[derive(Clone, PartialEq, Eq)]
+    struct RawMicDeviceKey {
+        id: Option<String>,
+        label: Option<String>,
+    }
+
+    impl RawMicDeviceKey {
+        fn from_selection(device_id: Option<&str>, device_label: Option<&str>) -> Self {
+            Self {
+                id: device_id
+                    .map(str::trim)
+                    .filter(|value| !value.is_empty())
+                    .map(ToOwned::to_owned),
+                label: device_label
+                    .map(str::trim)
+                    .filter(|value| !value.is_empty())
+                    .map(ToOwned::to_owned),
+            }
+        }
+    }
+
+    #[derive(Clone)]
+    struct RawMicTapTarget {
+        app: AppHandle,
+        on_samples: Arc<dyn Fn(&[f32]) + Send + Sync>,
+        level_tick: Arc<AtomicU32>,
+    }
+
+    struct WarmedRawMicEngine {
+        engine: Retained<AVAudioEngine>,
+        input_node: Retained<AVAudioInputNode>,
+        device_key: RawMicDeviceKey,
+        target: Arc<Mutex<Option<RawMicTapTarget>>>,
+    }
+
+    // SAFETY: Same argument as `SpeechSession` / `RawMicCapture`: AVAudioEngine
+    // and AVAudioInputNode are refcounted ObjC objects that we move through
+    // Mutex ownership, without sharing Rust references across threads.
+    unsafe impl Send for WarmedRawMicEngine {}
+
+    struct RawMicWarmCache {
+        device_key: RawMicDeviceKey,
+        target: Arc<Mutex<Option<RawMicTapTarget>>>,
+    }
+
     /// Process-global session slot. We only allow one dictation at a time —
     /// starting a new one while another is in flight cancels the old one
     /// first.
@@ -219,6 +264,11 @@ pub(crate) mod macos {
         SLOT.get_or_init(|| Mutex::new(None))
     }
 
+    fn warmed_raw_mic_engine_slot() -> &'static Mutex<Option<WarmedRawMicEngine>> {
+        static SLOT: OnceLock<Mutex<Option<WarmedRawMicEngine>>> = OnceLock::new();
+        SLOT.get_or_init(|| Mutex::new(None))
+    }
+
     /// Bumped at the start of every `native_speech_start_impl` call. The
     /// auto-restart thread captures the value at decision time and skips the
     /// restart if a newer session has since been requested.
@@ -574,6 +624,160 @@ pub(crate) mod macos {
         Ok(())
     }
 
+    fn enable_voice_processing(input_node: &AVAudioInputNode) {
+        if let Err(err) = unsafe { input_node.setVoiceProcessingEnabled_error(true) } {
+            eprintln!(
+                "[whisper-mic] voice processing enable failed: {} — continuing without AEC",
+                ns_error_message(&err)
+            );
+        }
+    }
+
+    fn disable_voice_processing_ducking(input_node: &AVAudioInputNode) {
+        // Disable other-audio ducking so the separately-captured system audio
+        // isn't dropped to near-silent while the mic VPIO runs.
+        unsafe {
+            let responds: bool = objc2::msg_send![
+                input_node,
+                respondsToSelector: objc2::sel!(setVoiceProcessingOtherAudioDuckingConfiguration:)
+            ];
+            if responds {
+                input_node.setVoiceProcessingOtherAudioDuckingConfiguration(
+                    AVAudioVoiceProcessingOtherAudioDuckingConfiguration {
+                        enableAdvancedDucking: objc2::runtime::Bool::NO,
+                        duckingLevel: AVAudioVoiceProcessingOtherAudioDuckingLevel::Min,
+                    },
+                );
+            }
+        }
+    }
+
+    fn take_warmed_raw_mic_engine(device_key: &RawMicDeviceKey) -> Option<WarmedRawMicEngine> {
+        let mut slot = warmed_raw_mic_engine_slot().lock().ok()?;
+        let should_reuse = slot
+            .as_ref()
+            .map(|cached| &cached.device_key == device_key)
+            .unwrap_or(false);
+        if should_reuse {
+            slot.take()
+        } else {
+            // A selected mic changed while the engine was warm. Drop the stale
+            // engine so the next start configures the requested device.
+            if let Some(stale) = slot.take() {
+                discard_warmed_raw_mic_engine(stale);
+            }
+            None
+        }
+    }
+
+    fn store_warmed_raw_mic_engine(engine: WarmedRawMicEngine) {
+        if let Ok(mut slot) = warmed_raw_mic_engine_slot().lock() {
+            if let Some(previous) = slot.replace(engine) {
+                discard_warmed_raw_mic_engine(previous);
+            }
+        }
+    }
+
+    fn clear_warmed_raw_mic_engine() {
+        if let Ok(mut slot) = warmed_raw_mic_engine_slot().lock() {
+            if let Some(engine) = slot.take() {
+                discard_warmed_raw_mic_engine(engine);
+            }
+        }
+    }
+
+    fn discard_warmed_raw_mic_engine(engine: WarmedRawMicEngine) {
+        let WarmedRawMicEngine {
+            engine,
+            input_node,
+            device_key: _,
+            target,
+        } = engine;
+        if let Ok(mut current) = target.lock() {
+            *current = None;
+        }
+        unsafe {
+            if engine.isRunning() {
+                engine.stop();
+            }
+        }
+        let _ = objc2::exception::catch(std::panic::AssertUnwindSafe(|| unsafe {
+            input_node.removeTapOnBus(0);
+        }));
+    }
+
+    fn install_reusable_raw_mic_tap(
+        input_node: &AVAudioInputNode,
+        target: Arc<Mutex<Option<RawMicTapTarget>>>,
+    ) -> Result<(), String> {
+        let target_for_tap = target.clone();
+        let tap_block = StackBlock::new(
+            move |buffer: std::ptr::NonNull<AVAudioPCMBuffer>,
+                  _when: std::ptr::NonNull<AVAudioTime>| {
+                let Some(target) = target_for_tap
+                    .try_lock()
+                    .ok()
+                    .and_then(|guard| guard.as_ref().cloned())
+                else {
+                    return;
+                };
+                let buf = unsafe { buffer.as_ref() };
+                let mono = mono_mix_pcm(buf);
+                if !mono.is_empty() {
+                    (target.on_samples)(&mono);
+                }
+                let n = target.level_tick.fetch_add(1, Ordering::Relaxed);
+                if n % 2 == 0 {
+                    let level = peak_level_for_pcm(buf);
+                    let _ = target.app.emit(
+                        "voice:audio-level",
+                        AudioLevelPayload {
+                            level,
+                            source: "mic",
+                        },
+                    );
+                }
+            },
+        )
+        .copy();
+        let block_ptr: *mut block2::Block<
+            dyn Fn(std::ptr::NonNull<AVAudioPCMBuffer>, std::ptr::NonNull<AVAudioTime>) + 'static,
+        > = (&*tap_block) as *const _ as *mut _;
+        objc2::exception::catch(std::panic::AssertUnwindSafe(|| unsafe {
+            input_node.installTapOnBus_bufferSize_format_block(
+                0, 1024,
+                None, // use hardware's current format — avoids SCO↔A2DP stale-format race
+                block_ptr,
+            );
+        }))
+        .map_err(|e| format!("installTapOnBus threw: {e:?}"))
+    }
+
+    fn build_warmed_raw_mic_engine(
+        mic_device_id: Option<&str>,
+        mic_device_label: Option<&str>,
+        device_key: RawMicDeviceKey,
+    ) -> Result<WarmedRawMicEngine, String> {
+        let engine: Retained<AVAudioEngine> = unsafe { AVAudioEngine::new() };
+        configure_engine_input_device(&engine, mic_device_id, mic_device_label)?;
+        let input_node: Retained<AVAudioInputNode> = unsafe { engine.inputNode() };
+        enable_voice_processing(&input_node);
+        // Finalize input format negotiation once. Dictation-owned Whisper starts
+        // can then reuse this stopped VPIO engine instead of paying the
+        // per-press VoiceProcessingIO setup cost.
+        objc2::exception::catch(std::panic::AssertUnwindSafe(|| unsafe { engine.prepare() }))
+            .map_err(|e| format!("AVAudioEngine prepare threw: {e:?}"))?;
+        let target = Arc::new(Mutex::new(None));
+        install_reusable_raw_mic_tap(&input_node, target.clone())?;
+        disable_voice_processing_ducking(&input_node);
+        Ok(WarmedRawMicEngine {
+            engine,
+            input_node,
+            device_key,
+            target,
+        })
+    }
+
     /// Tear down whatever session is currently running. Called from `start`
     /// to guarantee a fresh slate, and from `cancel` / `stop` for explicit
     /// teardown.
@@ -983,12 +1187,13 @@ pub(crate) mod macos {
         Ok(())
     }
 
-    /// Handle for a running raw mic capture. `stop()` removes the tap and stops
-    /// the engine.
+    /// Handle for a running raw mic capture. `stop()` either tears down the tap
+    /// or parks a dictation-owned VPIO engine for the next press.
     pub(crate) struct RawMicCapture {
         engine: Retained<AVAudioEngine>,
-        input_node: Retained<objc2_avf_audio::AVAudioInputNode>,
+        input_node: Retained<AVAudioInputNode>,
         sample_rate: f64,
+        warm_cache: Option<RawMicWarmCache>,
     }
 
     // SAFETY: same argument as `SpeechSession` — refcounted ObjC objects that
@@ -1003,15 +1208,103 @@ pub(crate) mod macos {
         }
 
         pub(crate) fn stop(self) {
+            let RawMicCapture {
+                engine,
+                input_node,
+                sample_rate: _,
+                warm_cache,
+            } = self;
+            if let Some(cache) = warm_cache {
+                unsafe {
+                    if engine.isRunning() {
+                        engine.stop();
+                    }
+                }
+                if let Ok(mut target) = cache.target.lock() {
+                    *target = None;
+                }
+                store_warmed_raw_mic_engine(WarmedRawMicEngine {
+                    engine,
+                    input_node,
+                    device_key: cache.device_key,
+                    target: cache.target,
+                });
+                return;
+            }
             unsafe {
-                self.input_node.removeTapOnBus(0);
-                if self.engine.isRunning() {
-                    self.engine.stop();
+                input_node.removeTapOnBus(0);
+                if engine.isRunning() {
+                    engine.stop();
                 }
             }
         }
     }
 
+    fn start_warmed_raw_mic_capture(
+        app: AppHandle,
+        mic_device_id: Option<String>,
+        mic_device_label: Option<String>,
+        on_samples: Arc<dyn Fn(&[f32]) + Send + Sync>,
+    ) -> Result<RawMicCapture, String> {
+        let device_key =
+            RawMicDeviceKey::from_selection(mic_device_id.as_deref(), mic_device_label.as_deref());
+        let warmed = match take_warmed_raw_mic_engine(&device_key) {
+            Some(warmed) => warmed,
+            None => build_warmed_raw_mic_engine(
+                mic_device_id.as_deref(),
+                mic_device_label.as_deref(),
+                device_key.clone(),
+            )?,
+        };
+        if let Ok(mut target) = warmed.target.lock() {
+            *target = Some(RawMicTapTarget {
+                app: app.clone(),
+                on_samples,
+                level_tick: Arc::new(AtomicU32::new(0)),
+            });
+        } else {
+            return Err("warmed mic target lock poisoned".into());
+        }
+
+        let start_result = objc2::exception::catch(std::panic::AssertUnwindSafe(|| unsafe {
+            warmed.engine.startAndReturnError()
+        }))
+        .map_err(|e| format!("AVAudioEngine start threw: {e:?}"))
+        .and_then(|r| {
+            r.map_err(|e| format!("AVAudioEngine start failed: {}", ns_error_message(&e)))
+        });
+        if let Err(msg) = start_result {
+            if let Ok(mut target) = warmed.target.lock() {
+                *target = None;
+            }
+            return Err(msg);
+        }
+
+        // Read the format only after the engine has started — at this point the
+        // engine has committed to its I/O configuration and the sample rate
+        // matches what the tap will actually deliver.
+        let format = unsafe { warmed.input_node.outputFormatForBus(0) };
+        let sample_rate = unsafe { format.sampleRate() };
+        eprintln!(
+            "[whisper-mic] reused warm VPIO tap format: {} Hz, {} ch",
+            sample_rate as u32,
+            unsafe { format.channelCount() }
+        );
+
+        let WarmedRawMicEngine {
+            engine,
+            input_node,
+            device_key,
+            target,
+        } = warmed;
+        Ok(RawMicCapture {
+            engine,
+            input_node,
+            sample_rate,
+            warm_cache: Some(RawMicWarmCache { device_key, target }),
+        })
+    }
+
     /// Start mic capture and forward a mono mix of every available channel to
     /// `on_samples`. Recording transcription can disable VPIO so the tap does
     /// not precondition the shared mic before ScreenCaptureKit opens it.
@@ -1020,23 +1313,24 @@ pub(crate) mod macos {
         mic_device_id: Option<String>,
         mic_device_label: Option<String>,
         voice_processing: bool,
+        reuse_voice_processing_engine: bool,
         on_samples: Arc<dyn Fn(&[f32]) + Send + Sync>,
     ) -> Result<RawMicCapture, String> {
+        if voice_processing && reuse_voice_processing_engine {
+            return start_warmed_raw_mic_capture(app, mic_device_id, mic_device_label, on_samples);
+        }
+        clear_warmed_raw_mic_engine();
+
         let engine: Retained<AVAudioEngine> = unsafe { AVAudioEngine::new() };
         configure_engine_input_device(
             &engine,
             mic_device_id.as_deref(),
             mic_device_label.as_deref(),
         )?;
-        let input_node: Retained<objc2_avf_audio::AVAudioInputNode> = unsafe { engine.inputNode() };
+        let input_node: Retained<AVAudioInputNode> = unsafe { engine.inputNode() };
 
         if voice_processing {
-            if let Err(err) = unsafe { input_node.setVoiceProcessingEnabled_error(true) } {
-                eprintln!(
-                    "[whisper-mic] voice processing enable failed: {} — continuing without AEC",
-                    ns_error_message(&err)
-                );
-            }
+            enable_voice_processing(&input_node);
         } else {
             eprintln!("[whisper-mic] voice processing disabled for shared mic capture");
         }
@@ -1102,28 +1396,14 @@ pub(crate) mod macos {
         );
 
         if voice_processing {
-            // Disable other-audio ducking so the separately-captured system audio
-            // isn't dropped to near-silent while the mic VPIO runs.
-            unsafe {
-                let responds: bool = objc2::msg_send![
-                    &*input_node,
-                    respondsToSelector: objc2::sel!(setVoiceProcessingOtherAudioDuckingConfiguration:)
-                ];
-                if responds {
-                    input_node.setVoiceProcessingOtherAudioDuckingConfiguration(
-                        AVAudioVoiceProcessingOtherAudioDuckingConfiguration {
-                            enableAdvancedDucking: objc2::runtime::Bool::NO,
-                            duckingLevel: AVAudioVoiceProcessingOtherAudioDuckingLevel::Min,
-                        },
-                    );
-                }
-            }
+            disable_voice_processing_ducking(&input_node);
         }
 
         Ok(RawMicCapture {
             engine,
             input_node,
             sample_rate,
+            warm_cache: None,
         })
     }
 

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

@@ -656,11 +656,13 @@ mod macos {
             session_start,
         );
         let mic_for_cb = mic_stream.clone();
+        let reuse_voice_processing_engine = owner == SessionOwner::Dictation && !capture_system;
         let mic_cap = start_raw_mic_capture(
             app.clone(),
             mic_device_id,
             mic_device_label,
             voice_processing,
+            reuse_voice_processing_engine,
             Arc::new(move |s: &[f32]| mic_for_cb.push(s)),
         )
         .map_err(|e| {

package/corpus/templates/design/.agents/skills/design-generation/SKILL.md

@@ -643,6 +643,15 @@ regeneration is slow, expensive, and regresses unrelated parts.
   `data-screen`, or `#` anchors (see Multi-screen prototypes & navigation).
 - Never hardcode colors — always reference CSS custom properties (no raw
   `text-white` / `bg-black` / hex literals in markup).
+- Never define or rely on a CSS custom property starting with `--agent-native-`
+  in generated design content. That prefix (plus `--design-editor-`) is
+  reserved for editor-internal state (selection chrome, editor-chrome scale
+  compensation, clipboard/surface tokens) — the editor strips any property
+  under those prefixes before persisting a cross-screen style capture
+  (`isEditorInternalCssVar` in `app/pages/DesignEditor.tsx`), so a design that
+  defines its own theming under that namespace would silently lose those
+  values on a cross-screen move. Use `--color-*`, `--font-*`, or another
+  design-owned prefix for tokens/tweaks instead.
 - Never use the v3 `bg-gradient-to-*` classes — use v4 `bg-linear-to-*`.
 - Never use `<script>` blocks with raw DOM manipulation — use Alpine.js directives
 - Never inline `onclick="..."` handlers — use `@click`