Custom style instructions for the cleanup rewrite (#130)

* feat: custom style instructions appended to the cleanup rewrite

An Advanced-settings free-text field (e.g. "add some emojis where
appropriate sparingly", "always write in lowercase") whose contents are
appended to the cleanup instruction the dictation request's llm block
carries, so the server-side rewrite also applies the user's formatting
preferences. Empty or blank means the request is exactly what ships today.

The dictation API rejects the whole request over its 2048-character
instruction cap, so the appended text is capped at the real headroom the
base instruction and a bridging preamble leave
(CleanupInstruction.customStyleBudget, currently 352 characters) —
enforced in the Settings field (with a visible counter) and again at send
time, and derived from the actual lengths rather than restated.

Storage follows KeyTermsStore (read-only store, @AppStorage is the sole
writer, trimming on the read side); the transcriber reads it per request
via an injected closure like enhancedTranscripts, so an edit applies to
the very next dictation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gwjo9LJw6z5PDyNeZjHbhc

* fix: review findings on custom style instructions

- Measure the instruction budget in UTF-8 bytes everywhere (cap
  arithmetic, engine trim, Settings counter and truncation), derived
  from the one budget definition. The API's 2048 cap was measured
  against the live endpoint but its unit was not; bytes are the largest
  plausible unit, so conservative against all of them. Truncation drops
  whole Characters so a multi-scalar emoji is never split — one shared
  String.prefix(maxUTF8Bytes:) used by both enforcement points, plus an
  emoji regression test.
- Skip building the combined instruction when enhanced transcripts are
  off (the result was discarded); the over-cap log guard is unchanged.
- Hide the Settings counter while the section is disabled, and give it
  an accessibility label ("N of M characters used") instead of the raw
  "N/M" digits.
- Drop the transcriber-test assertions duplicating the equality check
  and CleanupInstructionTests' structure tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gwjo9LJw6z5PDyNeZjHbhc

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

AGENTS.md

@@ -410,7 +410,13 @@ response carries both `text` (verbatim) and
 
 The instruction is `CleanupInstruction.text`, the winner of a GEPA run of
 `evals/dictation-prompt/` (see its README), compressed to fit the cap. Two later searches
-failed to beat it — the most recent scored 0.9043 against its 0.9101 on a held-out split.
+failed to beat it — the most recent scored 0.9043 against its 0.9101 on a held-out split. When the
+user has entered **custom style instructions** (`CustomStyleStore`, read per request via the
+transcriber's injected `customStyle` closure), `CleanupInstruction.sendable(appending:)` appends
+them after the base text with a bridging preamble, trimmed to the headroom the API's 2048
+instruction cap leaves (`customStyleBudget`, measured in UTF-8 bytes — the cap's own unit is
+unmeasured, and bytes are the conservative bound); empty or blank sends the base instruction
+unchanged.
 
 Note what that does and does not establish. It is the best instruction the harness has
 produced, measured against other _text_ candidates on a _stand-in_ model; it has never been
@@ -617,6 +623,10 @@ Engine-side stores, all `UserDefaults`-backed value types with the same shape:
   **`DeveloperModeStore`** (`BlurtDeveloperMode`, off by default),
   **`EnhancedTranscriptsStore`** (`BlurtEnhancedTranscripts`, **on** by default — unset reads as
   enabled; gates the dictation request's `llm` cleanup-rewrite block, re-read at every request),
+  **`CustomStyleStore`** (`BlurtCustomStyle`, the user's custom style instructions appended to the
+  cleanup instruction via `CleanupInstruction.sendable(appending:)`, re-read at every request; empty
+  sends the base instruction unchanged, and its `characterLimit` re-exports the headroom — in UTF-8
+  bytes — the API's 2048 instruction cap leaves),
   **`OverlayOriginStore`** (the pill's dragged origin, x/y), **`LastUpdateCheckStore`**
   (`BlurtLastUpdateCheck`, the stamp throttling the automatic launch update check).
 - **`DefaultsKey`** (`Config/DefaultsKey.swift`) defines every key those stores write, one case each,

App/Blurt/Blurt/Wizard/SettingsWindowRoot.swift

@@ -67,15 +67,16 @@ private struct GeneralSettingsTab: View {
   }
 }
 
-/// The occasional stuff: the enhanced-transcripts switch, checking for an
-/// update, and the developer-mode log toggle. Kept out of General so the
-/// common pane stays short.
+/// The occasional stuff: the enhanced-transcripts switch, the custom style
+/// instructions, checking for an update, and the developer-mode log toggle.
+/// Kept out of General so the common pane stays short.
 private struct AdvancedSettingsTab: View {
   let updateModel: UpdateCheckModel
 
   var body: some View {
     SettingsPane {
       TranscriptionSection()
+      CustomStyleSection()
       UpdateSection(model: updateModel)
       DeveloperSection()
     }
@@ -113,6 +114,67 @@ private struct TranscriptionSection: View {
   }
 }
 
+/// The Custom Style section of the Settings window: free-text style
+/// instructions appended to the cleanup instruction on every dictation request
+/// (see `CleanupInstruction.sendable(appending:)` / `CustomStyleStore`), so the
+/// enhanced-transcript polish also applies the user's formatting preferences.
+/// Optional — empty means the request is exactly what ships today. Disabled
+/// while enhanced transcripts are off, since the instruction it extends is not
+/// sent at all then.
+private struct CustomStyleSection: View {
+  @AppStorage(EnhancedTranscriptsStore.defaultsKey)
+  private var enhancedTranscripts = EnhancedTranscriptsStore.defaultValue
+
+  /// `@AppStorage` is the only writer of this slot (the store exposes no
+  /// setter); trimming lives on the read side (`CustomStyleStore.instructions`)
+  /// for the reasons on `KeyTermsStepView.text`. The length cap is enforced
+  /// here, though: the dictation API rejects the whole request over its
+  /// instruction limit, so text past `characterLimit` must never be storable.
+  @AppStorage(CustomStyleStore.defaultsKey) private var text = ""
+
+  var body: some View {
+    Section {
+      TextField(
+        text: $text,
+        prompt: Text("e.g. add fitting emojis sparingly, or always write in lowercase"),
+        axis: .vertical
+      ) {
+        Text("Custom Style")
+      }
+      .labelsHidden()
+      .lineLimit(2...6)
+      .font(.body)
+      .disableAutocorrection(true)
+      .accessibilityIdentifier(UITestIdentifiers.customStyleField)
+      .onChange(of: text) {
+        if text.utf8.count > CustomStyleStore.characterLimit {
+          text = text.prefix(maxUTF8Bytes: CustomStyleStore.characterLimit)
+        }
+      }
+      .disabled(!enhancedTranscripts)
+    } header: {
+      Text("Custom Style")
+    } footer: {
+      HStack(alignment: .top) {
+        Text(
+          enhancedTranscripts
+            ? "Style preferences applied when polishing each dictation — casing, tone, emoji use."
+            : "Style preferences need enhanced transcripts turned on.")
+        if enhancedTranscripts {
+          Spacer()
+          // The API caps the combined instruction, so the room left is finite —
+          // show it rather than truncating silently at the limit. Counted in
+          // UTF-8 bytes, the unit the limit is enforced in.
+          Text("\(text.utf8.count)/\(CustomStyleStore.characterLimit)")
+            .monospacedDigit()
+            .accessibilityLabel(
+              "\(text.utf8.count) of \(CustomStyleStore.characterLimit) characters used")
+        }
+      }
+    }
+  }
+}
+
 /// The Updates section of the Settings window: the running version and a
 /// "Check for Updates" button that runs the check and reports the result in a
 /// modal (see `UpdateCheckModel`). The same check is reachable from the

App/Blurt/Shared/UITestIdentifiers.swift

@@ -64,6 +64,7 @@ enum UITestIdentifiers {
   static let soundPicker = "settings.sound.picker"
   static let developerToggle = "settings.developer.toggle"
   static let enhancedTranscriptsToggle = "settings.enhancedTranscripts.toggle"
+  static let customStyleField = "settings.customStyle.field"
   static let updateCheck = "settings.update.check"
 
   /// The dictation overlay pill (`OverlayView`).

BLURTENGINE.md

@@ -59,7 +59,7 @@ press() ──▶ MicCapture.start()            release() ──▶ MicCapture.s
 Key properties of the design, which your integration can rely on:
 
 - **One request per utterance, no streaming.** The dictation API returns the complete transcript — and its LLM-rewritten form — in the response body: no upload step, no job polling, no incremental deltas, no second request for the cleanup. `TranscriberProtocol.transcribe` is a single `async throws -> String`. UIs should show a "transcribing…" state and then the whole result; there is nothing to stream.
-- **Cleanup happens server-side, and it's optional.** The request's `llm` block asks the service to apply our own cleanup instruction (`CleanupInstruction.text` — delete disfluencies, change nothing else) to the verbatim transcript inside the same call. It is the only instruction on the request: the separate `config.prompt` field, which primes the _transcription_, is switched off at `TranscriptionPrompt.isEnabled` and omitted from every request. The block is gated by the **enhanced transcripts** setting (`EnhancedTranscriptsStore`, on by default): turned off, the config omits `llm` and the verbatim transcript is pasted as spoken. The engine pastes `llm_response`, falling back to the verbatim `text` when the best-effort rewrite failed (`llm_error`) — a degradation, never a user-facing error. There is no client-side LLM pass, no styling stage, and deliberately no hook for one.
+- **Cleanup happens server-side, and it's optional.** The request's `llm` block asks the service to apply our own cleanup instruction (`CleanupInstruction.text` — delete disfluencies, change nothing else) to the verbatim transcript inside the same call. It is the only instruction on the request: the separate `config.prompt` field, which primes the _transcription_, is switched off at `TranscriptionPrompt.isEnabled` and omitted from every request. The block is gated by the **enhanced transcripts** setting (`EnhancedTranscriptsStore`, on by default): turned off, the config omits `llm` and the verbatim transcript is pasted as spoken. The user's **custom style instructions** (`CustomStyleStore`, empty by default) are appended to that instruction via `CleanupInstruction.sendable(appending:)`, trimmed to the headroom the API's 2048 instruction cap leaves (measured in UTF-8 bytes, the conservative bound — the cap's own unit is unmeasured); blank means the base instruction goes out unchanged. The engine pastes `llm_response`, falling back to the verbatim `text` when the best-effort rewrite failed (`llm_error`) — a degradation, never a user-facing error. There is no client-side LLM pass, no styling stage, and deliberately no hook for one.
 - **Latency is pre-paid where possible.** `press()` fires a detached `warmUp()` at the transcriber (pre-opening the HTTPS connection while the user speaks, ~170 ms saved cold) and kicks off the cross-process accessibility read of the focused field without awaiting it — the read is then consumed at transcribe time with a bounded wait (`DictationSession.contextWaitBudget`, 500 ms), so an unresponsive frontmost app costs the transcript its priming, never a multi-second stall — and never delays the recording indicator. On the way out, `release()` flips the phase to `.transcribing` _before_ reading the recorded audio back, so a host's stop cue fires at key-up rather than after the disk read.
 - **A held trigger auto-releases.** `DictationSession` stops recording after `maxRecordingSeconds` (default `SyncSTTLimits.autoReleaseSeconds`, 115 s) so audio never exceeds what the endpoint accepts, and transcribes what it has. Clips shorter than `SyncSTTLimits.minPCMBytes` (~100 ms of audio — an accidental tap) are dropped as a silent no-op rather than sent to earn a 400.
 
@@ -133,7 +133,7 @@ func transcribe(pcm: Data, sampleRate: Int, context: TranscriptionContext?) asyn
 func warmUp() async   // optional; no-op default
 ```
 
-`AssemblyAITranscriber` is a stateless `Sendable` struct. One `POST https://dictation.assemblyai.com/transcribe` per utterance: the audio as raw S16LE PCM (the `pcm` blob, byte-for-byte) in the `audio` multipart part, plus a JSON `config` part (`sample_rate`, `channels`, the rendered `prompt` (nil today, so the field is omitted), and — while enhanced transcripts are enabled, the default — an `llm` block whose one `instruction` field carries `CleanupInstruction.text`), with the API key in `Authorization` (no model header — the service pins the STT model server-side). The response carries the verbatim `text` and the rewritten `llm_response`; the transcriber returns the rewrite and falls back to `text` when it is null (the rewrite is best-effort — `llm_error` is logged, never surfaced as a failure). Its initializer takes an `apiKeyProvider` closure (defaults to `APIKeyStore.current`), a `baseURL`, an `HTTPTransport` — inject a fake transport (see `Tests/BlurtEngineTests/Stubs/FakeHTTPTransport.swift`) to test against canned responses — and an `enhancedTranscripts` closure deciding, per request, whether the `llm` block is sent (nil, the default, reads `EnhancedTranscriptsStore`). `warmUp()` fires a throwaway GET at the host root to pre-pool the connection; it never throws and any failure just means the real request pays connection setup as before.
+`AssemblyAITranscriber` is a stateless `Sendable` struct. One `POST https://dictation.assemblyai.com/transcribe` per utterance: the audio as raw S16LE PCM (the `pcm` blob, byte-for-byte) in the `audio` multipart part, plus a JSON `config` part (`sample_rate`, `channels`, the rendered `prompt` (nil today, so the field is omitted), and — while enhanced transcripts are enabled, the default — an `llm` block whose one `instruction` field carries `CleanupInstruction.text`, with any custom style instructions appended — `CleanupInstruction.sendable(appending:)`), with the API key in `Authorization` (no model header — the service pins the STT model server-side). The response carries the verbatim `text` and the rewritten `llm_response`; the transcriber returns the rewrite and falls back to `text` when it is null (the rewrite is best-effort — `llm_error` is logged, never surfaced as a failure). Its initializer takes an `apiKeyProvider` closure (defaults to `APIKeyStore.current`), a `baseURL`, an `HTTPTransport` — inject a fake transport (see `Tests/BlurtEngineTests/Stubs/FakeHTTPTransport.swift`) to test against canned responses — an `enhancedTranscripts` closure deciding, per request, whether the `llm` block is sent (nil, the default, reads `EnhancedTranscriptsStore`), and a `customStyle` closure supplying the style instructions appended to the cleanup instruction (nil, the default, reads `CustomStyleStore`). `warmUp()` fires a throwaway GET at the host root to pre-pool the connection; it never throws and any failure just means the real request pays connection setup as before.
 
 The model's limits live in `SyncSTTLimits` (16 kHz sample rate, ~0.1 s–120 s audio, and the auto-release math — the sync STT model behind the dictation service) — the single source shared by the mic, the session, and the request so recorded and declared geometry can't drift.
 

Sources/BlurtEngine/Config/CustomStyleStore.swift

@@ -0,0 +1,41 @@
+import Foundation
+
+/// Storage for the user's custom style instructions — free text (e.g. "add some
+/// emojis where appropriate sparingly", "always write in lowercase") appended to
+/// the cleanup instruction so the dictation API's server-side rewrite also
+/// applies the user's formatting preferences (see
+/// `CleanupInstruction.sendable(appending:)`). Optional: unset or blank sends
+/// exactly the instruction that ships today. Inert while enhanced transcripts
+/// are off, since the `llm` block the instruction rides on is omitted entirely.
+/// `AssemblyAITranscriber` reads this at each request, so an edit applies to the
+/// very next dictation.
+///
+/// Read-only for the same reason as `KeyTermsStore`: the Settings field binds
+/// `@AppStorage` straight to `defaultsKey` and is the sole writer — a
+/// normalizing setter fights the text field — so trimming lives on the read
+/// side and a whitespace-only field still reads back as "no instructions".
+public struct CustomStyleStore {
+  /// `UserDefaults` key for the raw text the user typed. Public so the Settings
+  /// field can bind `@AppStorage` to it.
+  public static let defaultsKey = DefaultsKey.customStyle.rawValue
+
+  /// The most UTF-8 bytes the Settings field accepts —
+  /// `CleanupInstruction.customStyleBudget`, the real headroom the dictation
+  /// API's 2048 instruction cap leaves after the base instruction (see
+  /// `CleanupInstruction.characterCap` for why the unit is bytes).
+  /// Re-exported here (the field's counter and the engine's trim have to agree)
+  /// rather than restated, which is how the cap bug shipped once before.
+  public static let characterLimit = CleanupInstruction.customStyleBudget
+
+  private let defaults: UserDefaults
+
+  init(defaults: UserDefaults = .standard) {
+    self.defaults = defaults
+  }
+
+  /// The instructions to append, trimmed, or `nil` when unset or blank — blank
+  /// must mean "send the base instruction untouched", not an empty suffix.
+  var instructions: String? {
+    defaults.string(forKey: Self.defaultsKey).trimmedNonEmpty()
+  }
+}

Sources/BlurtEngine/Config/DefaultsKey.swift

@@ -25,6 +25,7 @@ enum DefaultsKey: String, CaseIterable {
   case keyTerms = "BlurtKeyTerms"
   case developerMode = "BlurtDeveloperMode"
   case enhancedTranscripts = "BlurtEnhancedTranscripts"
+  case customStyle = "BlurtCustomStyle"
   /// `OverlayOriginStore` persists a point, so it owns two keys rather than one.
   case overlayCustomOriginX = "BlurtOverlayCustomOriginX"
   case overlayCustomOriginY = "BlurtOverlayCustomOriginY"

Sources/BlurtEngine/STT/AssemblyAITranscriber.swift

@@ -26,6 +26,7 @@ public struct AssemblyAITranscriber: TranscriberProtocol {
   private let baseURL: URL
   private let transport: any HTTPTransport
   private let enhancedTranscriptsEnabled: @Sendable () -> Bool
+  private let customStyle: @Sendable () -> String?
 
   /// Idle timeout for the transcribe round trip — `URLRequest.timeoutInterval` is
   /// reset each time data moves, so this bounds *stalls*, not total elapsed time.
@@ -37,21 +38,25 @@ public struct AssemblyAITranscriber: TranscriberProtocol {
   private static let requestTimeoutSeconds: TimeInterval = 90
 
   /// `enhancedTranscripts` decides, per request, whether the config carries
-  /// the `llm` cleanup-rewrite block. Read at every `transcribe` so a settings
-  /// change applies to the next dictation without rebuilding the transcriber.
-  /// `nil` (the default) reads `EnhancedTranscriptsStore` — spelled as an
-  /// optional rather than a default closure because a public default argument
-  /// can't reference the store's internal `isEnabled`.
+  /// the `llm` cleanup-rewrite block; `customStyle` supplies the user's custom
+  /// style instructions appended to that block's cleanup instruction. Both are
+  /// read at every `transcribe` so a settings change applies to the next
+  /// dictation without rebuilding the transcriber. `nil` (the default) reads
+  /// the corresponding store — spelled as optionals rather than default
+  /// closures because a public default argument can't reference a store's
+  /// internal member.
   public init(
     apiKeyProvider: @escaping @Sendable () -> String? = { APIKeyStore.current },
     baseURL: URL = URL(staticString: "https://dictation.assemblyai.com"),
     transport: any HTTPTransport = URLSession.shared,
-    enhancedTranscripts: (@Sendable () -> Bool)? = nil
+    enhancedTranscripts: (@Sendable () -> Bool)? = nil,
+    customStyle: (@Sendable () -> String?)? = nil
   ) {
     self.apiKeyProvider = apiKeyProvider
     self.baseURL = baseURL
     self.transport = transport
     self.enhancedTranscriptsEnabled = enhancedTranscripts ?? { EnhancedTranscriptsStore().isEnabled }
+    self.customStyle = customStyle ?? { CustomStyleStore().instructions }
   }
 
   // MARK: - Dictation request
@@ -131,15 +136,15 @@ public struct AssemblyAITranscriber: TranscriberProtocol {
   /// `URLProtocol` mocks can't observe reliably for `upload(from:)`).
   func makeConfigData(sampleRate: Int, prompt: String?) throws -> Data {
     let enhanced = enhancedTranscriptsEnabled()
-    let instruction = CleanupInstruction.sendable
+    let instruction = enhanced ? CleanupInstruction.sendable(appending: customStyle()) : nil
     if enhanced, instruction == nil {
       // Unreachable while the tests run: `CleanupInstructionTests` asserts the length.
       // Logged rather than trusted because the failure it guards against is silent —
       // the request would 400 and every dictation would error, so a line naming the
       // real cause is worth the one comparison per request it costs.
       transcriberLog.error(
         """
-        cleanup instruction is \(CleanupInstruction.text.count, privacy: .public) characters, \
+        cleanup instruction is \(CleanupInstruction.text.utf8.count, privacy: .public) UTF-8 bytes, \
         over the \(CleanupInstruction.characterCap, privacy: .public) cap; \
         falling back to the service default
         """)