openclacky 1.3.11 → 1.4.0

data/lib/clacky/media/volcengine.rb

@@ -0,0 +1,394 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "uri"
+require "base64"
+require_relative "base"
+
+module Clacky
+  module Media
+    # Volcengine Ark (ByteDance Doubao Seedance) video generation provider.
+    #
+    # Ark is NOT OpenAI-compatible for video. It uses an asynchronous task
+    # model with its own request envelope: submit a task to
+    # POST /api/v3/contents/generations/tasks, then poll
+    # GET /api/v3/contents/generations/tasks/{id} until it succeeds, fails,
+    # or expires. Unlike the blocking Veo path, we surface that async model
+    # end to end: #generate_video submits and returns the task id immediately,
+    # and #video_status polls a single time (downloading the MP4 once the task
+    # has succeeded). This keeps a slow (e.g. 4k) render from blocking the HTTP
+    # request past its timeout and dropping the task id.
+    #
+    # Routing: Generator sends any base_url under *.volces.com here. We
+    # derive the API root from the host so users can paste the standard
+    # base_url they use for Ark chat models (…/api/v3) and still get working
+    # video generation.
+    #
+    # Seedance content is multimodal: alongside the text prompt, callers may
+    # attach a first frame, a last frame, reference images (0-9), reference
+    # videos (0-3) and reference audios (0-3). Each media item may be a
+    # public http(s) URL, a data URL, a local file path (encoded to a data
+    # URL), or a { "b64_json" => ..., "mime_type" => ... } hash.
+    class Volcengine < Base
+      TASKS_PATH  = "/api/v3/contents/generations/tasks"
+      PROVIDER_ID = "volcengine"
+
+      # aspect_ratio -> Ark ratio. Ark also accepts more granular ratios and
+      # "adaptive"; when the caller passes one of those verbatim we forward it
+      # unchanged (see #resolve_ratio).
+      ASPECT_TO_RATIO = {
+        "landscape" => "16:9",
+        "portrait"  => "9:16",
+        "square"    => "1:1"
+      }.freeze
+
+      # Ratios Ark accepts directly. Anything else falls back to the
+      # aspect_ratio mapping / default.
+      ARK_RATIOS = %w[16:9 4:3 1:1 3:4 9:16 21:9 adaptive].freeze
+
+      DEFAULT_RATIO = "16:9"
+
+      # Explicit cost-control default: when the caller omits resolution we pin
+      # 720p rather than relying on Ark's server-side default (which could
+      # change and silently raise the user's bill).
+      DEFAULT_RESOLUTION = "720p"
+
+      # @param prompt [String] the video prompt (may be empty when driven
+      #   purely by reference media, but Ark still recommends text)
+      # @param aspect_ratio [String] "landscape"/"portrait"/"square", or an
+      #   Ark ratio string ("16:9", "9:16", "adaptive", ...)
+      # @param duration_seconds [Integer, nil] target duration; -1 lets the
+      #   model choose (Seedance 2.0 / 1.5 Pro only)
+      # @param first_frame [String, Hash, nil] first frame image
+      # @param last_frame [String, Hash, nil] last frame image
+      # @param reference_images [Array, String, Hash, nil] reference images
+      # @param reference_videos [Array, String, Hash, nil] reference videos
+      # @param reference_audios [Array, String, Hash, nil] reference audios
+      # @param resolution [String, nil] "480p"/"720p"/"1080p"/"4k"
+      # @param generate_audio [Boolean, nil] whether to synthesize audio
+      # @param watermark [Boolean, nil] whether to add a watermark
+      # @param seed [Integer, nil] random seed
+      def generate_video(prompt:, aspect_ratio: "landscape", duration_seconds: nil, output_dir: nil,
+                         image: nil, first_frame: nil, last_frame: nil,
+                         reference_images: nil, reference_videos: nil, reference_audios: nil,
+                         resolution: nil, generate_audio: nil, watermark: nil, seed: nil, **_kwargs)
+        # `image` is the legacy single first-frame field used across the media
+        # stack; treat it as first_frame when no explicit first_frame is given.
+        first_frame ||= image
+
+        content, build_err = build_content(
+          prompt: prompt,
+          first_frame: first_frame,
+          last_frame: last_frame,
+          reference_images: reference_images,
+          reference_videos: reference_videos,
+          reference_audios: reference_audios
+        )
+        if build_err
+          return video_error_response(
+            error: build_err, error_type: "invalid_argument",
+            provider: PROVIDER_ID, prompt: prompt, aspect_ratio: aspect_ratio
+          )
+        end
+
+        has_text  = prompt.to_s.strip != ""
+        has_media = content.length > (has_text ? 1 : 0)
+        if !has_text && !has_media
+          return video_error_response(
+            error: "A text prompt or at least one reference image/video is required",
+            error_type: "invalid_argument",
+            provider: PROVIDER_ID, prompt: prompt, aspect_ratio: aspect_ratio
+          )
+        end
+
+        if @api_key.to_s.empty?
+          return video_error_response(
+            error: "api_key not configured for video model '#{@model}'",
+            error_type: "auth_required",
+            provider: PROVIDER_ID, prompt: prompt, aspect_ratio: aspect_ratio
+          )
+        end
+
+        ratio   = resolve_ratio(aspect_ratio)
+        payload = { model: @model, content: content }
+        payload[:ratio]          = ratio unless ratio.nil?
+        payload[:duration]       = duration_seconds.to_i if duration_seconds
+        payload[:resolution]     = (resolution && !resolution.to_s.empty?) ? resolution.to_s : DEFAULT_RESOLUTION
+        payload[:generate_audio] = generate_audio unless generate_audio.nil?
+        payload[:watermark]      = watermark unless watermark.nil?
+        payload[:seed]           = seed.to_i if seed
+
+        begin
+          response = connection.post(TASKS_PATH) do |req|
+            req.headers["Content-Type"]  = "application/json"
+            req.headers["Authorization"] = "Bearer #{@api_key}"
+            req.body = JSON.generate(payload)
+          end
+        rescue Faraday::Error => e
+          return video_error_response(
+            error: "HTTP request failed: #{e.message}",
+            error_type: "network_error",
+            provider: PROVIDER_ID, prompt: prompt, aspect_ratio: aspect_ratio
+          )
+        end
+
+        body = parse_json(response.body)
+        unless body.is_a?(Hash)
+          return video_error_response(
+            error: "Invalid JSON response from upstream",
+            error_type: "invalid_response",
+            provider: PROVIDER_ID, prompt: prompt, aspect_ratio: aspect_ratio
+          )
+        end
+
+        # Ark reports submission errors via a nested "error" object.
+        if body["error"].is_a?(Hash)
+          err = body["error"]
+          return video_error_response(
+            error: "Upstream error #{err["code"]}: #{err["message"]}",
+            error_type: "api_error",
+            provider: PROVIDER_ID, prompt: prompt, aspect_ratio: aspect_ratio
+          )
+        end
+
+        unless response.success?
+          return video_error_response(
+            error: "Upstream #{response.status}: #{truncate(response.body, 500)}",
+            error_type: "api_error",
+            provider: PROVIDER_ID, prompt: prompt, aspect_ratio: aspect_ratio
+          )
+        end
+
+        task_id = body["id"]
+        if task_id.nil? || task_id.to_s.empty?
+          return video_error_response(
+            error: "Upstream did not return a task id",
+            error_type: "empty_response",
+            provider: PROVIDER_ID, prompt: prompt, aspect_ratio: aspect_ratio
+          )
+        end
+
+        # Submit only: return the task id immediately. The caller polls
+        # GET /api/media/video/status so a long (e.g. 4k) render never blocks
+        # the HTTP request past its timeout — which used to drop the task id
+        # and push the model into resubmitting, doubling the bill.
+        {
+          "success"      => true,
+          "status"       => "submitted",
+          "task_id"      => task_id,
+          "provider"     => PROVIDER_ID,
+          "model"        => @model,
+          "prompt"       => prompt,
+          "aspect_ratio" => aspect_ratio,
+          "ratio"        => ratio,
+          "duration_seconds" => (duration_seconds ? duration_seconds.to_i : nil)
+        }.compact
+      end
+
+      # Poll a previously submitted task once. On "succeeded" the MP4 is
+      # downloaded and a local path is returned; other states map to
+      # running / failed without blocking.
+      def video_status(task_id:, output_dir: nil)
+        if task_id.to_s.strip.empty?
+          return video_error_response(
+            error: "task_id is required", error_type: "invalid_argument",
+            provider: PROVIDER_ID
+          )
+        end
+
+        state, detail = fetch_task(task_id)
+        case state
+        when :running
+          { "success" => true, "status" => "running", "task_id" => task_id, "provider" => PROVIDER_ID, "model" => @model }
+        when :succeeded
+          local_path = save_image_from_url(detail, output_dir: output_dir || Dir.pwd, prefix: "vid", extension: "mp4")
+          if local_path.nil?
+            return {
+              "success" => false, "status" => "failed", "task_id" => task_id, "provider" => PROVIDER_ID,
+              "model" => @model, "error" => "Failed to download generated video from #{detail}",
+              "error_type" => "download_failed"
+            }
+          end
+          {
+            "success" => true, "status" => "succeeded", "video" => local_path,
+            "task_id" => task_id, "provider" => PROVIDER_ID, "model" => @model
+          }
+        else # :failed
+          {
+            "success" => false, "status" => "failed", "task_id" => task_id, "provider" => PROVIDER_ID,
+            "model" => @model, "error" => detail, "error_type" => "task_failed"
+          }
+        end
+      end
+
+      # Query a task once (no sleeping/looping). Returns one of:
+      #   [:running, nil]
+      #   [:succeeded, video_url]
+      #   [:failed, error_message]
+      private def fetch_task(task_id)
+        begin
+          resp = connection.get("#{TASKS_PATH}/#{task_id}") do |req|
+            req.headers["Authorization"] = "Bearer #{@api_key}"
+          end
+        rescue Faraday::Error => e
+          return [:failed, "Polling request failed: #{e.message}"]
+        end
+
+        task = parse_json(resp.body)
+        return [:failed, "Invalid polling response JSON"] unless task.is_a?(Hash)
+
+        case task["status"]
+        when "succeeded"
+          url = task.dig("content", "video_url")
+          return [:failed, "Task succeeded but returned no video_url"] if url.nil? || url.empty?
+          [:succeeded, url]
+        when "failed"
+          msg = task.dig("error", "message") || task["error"] || "Unknown error"
+          [:failed, "Task failed: #{msg}"]
+        when "cancelled", "canceled"
+          [:failed, "Task was cancelled"]
+        when "expired"
+          [:failed, "Task expired before completion"]
+        else # "queued" / "running"
+          [:running, nil]
+        end
+      end
+
+      # Build the Ark content[] array. Returns [content, nil] on success or
+      # [nil, error_message] when a media item can't be resolved.
+      private def build_content(prompt:, first_frame:, last_frame:, reference_images:, reference_videos:, reference_audios:)
+        has_frame     = !normalize_list(first_frame).empty? || !normalize_list(last_frame).empty?
+        has_reference = !normalize_list(reference_images).empty? ||
+                        !normalize_list(reference_videos).empty? ||
+                        !normalize_list(reference_audios).empty?
+        if has_frame && has_reference
+          return [nil, "first_frame/last_frame cannot be combined with reference_images/videos/audios. " \
+                       "Use first_frame (and optionally last_frame) for first/last-frame image-to-video, " \
+                       "OR use reference_* for multimodal / video editing / video extension — not both."]
+        end
+
+        content = []
+        content << { type: "text", text: prompt.to_s } unless prompt.to_s.strip.empty?
+
+        {
+          "first_frame"     => normalize_list(first_frame),
+          "last_frame"      => normalize_list(last_frame),
+          "reference_image" => normalize_list(reference_images)
+        }.each do |role, items|
+          items.each do |item|
+            url, err = to_media_url(item, kind: :image)
+            return [nil, err] if err
+            content << { type: "image_url", image_url: { url: url }, role: role }
+          end
+        end
+
+        normalize_list(reference_videos).each do |item|
+          url, err = to_media_url(item, kind: :video)
+          return [nil, err] if err
+          content << { type: "video_url", video_url: { url: url }, role: "reference_video" }
+        end
+
+        normalize_list(reference_audios).each do |item|
+          url, err = to_media_url(item, kind: :audio)
+          return [nil, err] if err
+          content << { type: "audio_url", audio_url: { url: url }, role: "reference_audio" }
+        end
+
+        [content, nil]
+      end
+
+      # Accept a single value or an array; drop nils/blanks.
+      private def normalize_list(value)
+        list = value.is_a?(Array) ? value : [value]
+        list.reject { |v| v.nil? || (v.is_a?(String) && v.strip.empty?) }
+      end
+
+      # Resolve one media item into a URL Ark accepts (http(s) URL or data
+      # URL). Accepts: an http(s)/data URL string, a local file path, or a
+      # { "b64_json" => ..., "mime_type" => ... } hash. Returns [url, nil] or
+      # [nil, error_message].
+      private def to_media_url(item, kind:)
+        if item.is_a?(Hash)
+          b64  = item["b64_json"] || item[:b64_json]
+          mime = (item["mime_type"] || item[:mime_type]).to_s
+          return [nil, "media hash is missing b64_json"] if b64.to_s.empty?
+          mime = default_mime(kind) if mime.empty?
+          return ["data:#{mime};base64,#{b64}", nil]
+        end
+
+        s = item.to_s.strip
+        return [nil, "empty media reference"] if s.empty?
+        return [s, nil] if s.start_with?("http://", "https://", "data:")
+
+        unless File.file?(s)
+          return [nil, "media reference is neither an existing file path, a URL, nor base64 data: #{s}"]
+        end
+        bytes = File.binread(s)
+        mime  = mime_for_path(s, kind)
+        ["data:#{mime};base64,#{Base64.strict_encode64(bytes)}", nil]
+      end
+
+      private def resolve_ratio(aspect_ratio)
+        s = aspect_ratio.to_s
+        return s if ARK_RATIOS.include?(s)
+        ASPECT_TO_RATIO[s] || DEFAULT_RATIO
+      end
+
+      private def default_mime(kind)
+        case kind
+        when :video then "video/mp4"
+        when :audio then "audio/mpeg"
+        else "image/png"
+        end
+      end
+
+      private def mime_for_path(path, kind)
+        case File.extname(path).downcase
+        when ".jpg", ".jpeg" then "image/jpeg"
+        when ".webp"         then "image/webp"
+        when ".gif"          then "image/gif"
+        when ".mp4"          then "video/mp4"
+        when ".mov"          then "video/quicktime"
+        when ".webm"         then "video/webm"
+        when ".mp3"          then "audio/mpeg"
+        when ".wav"          then "audio/wav"
+        when ".m4a"          then "audio/mp4"
+        else default_mime(kind)
+        end
+      end
+
+      private def connection
+        Faraday.new(url: endpoint_base) do |f|
+          f.options.timeout      = 240
+          f.options.open_timeout = 10
+        end
+      end
+
+      # Derive the API root (scheme + host) from the configured base_url,
+      # discarding any path the user pasted (e.g. /api/v3). The task path is
+      # appended by the request methods. Falls back to the Beijing host.
+      private def endpoint_base
+        uri = URI.parse(@base_url.to_s)
+        if uri.scheme && uri.host
+          "#{uri.scheme}://#{uri.host}"
+        else
+          "https://ark.cn-beijing.volces.com"
+        end
+      rescue URI::InvalidURIError
+        "https://ark.cn-beijing.volces.com"
+      end
+
+      private def parse_json(body)
+        JSON.parse(body)
+      rescue JSON::ParserError
+        nil
+      end
+
+      private def truncate(str, max)
+        s = str.to_s
+        s.length > max ? "#{s[0, max]}..." : s
+      end
+    end
+  end
+end

data/lib/clacky/server/http_server.rb

@@ -53,7 +53,7 @@ module Clacky
             # encode + downscale on every history replay (2-3s lag for sessions
             # with downgraded text-model images). The proxy lets the browser
             # lazy-load + cache the image, keeping the replay response tiny.
-            "/api/local-image?path=#{CGI.escape(path.to_s)}"
+            "/api/local-image?path=#{CGI.escape(path.to_s)}&v=#{File.mtime(path.to_s).to_i}"
           elsif name
             type.to_s == "image" ? "expired:#{name}" : "pdf:#{name}"
           end
@@ -463,6 +463,9 @@ module Clacky
           # with modalities:["image"]); end-to-end latency is commonly
           # 20-60s and can exceed 2 minutes for or-gpt-image-2 under load.
           300
+        elsif path == "/api/media/video/status"
+          # Single upstream task lookup; returns in well under a second.
+          30
         elsif path == "/api/media/video"
           # Video generation (Veo via the gateway) runs an async submit+poll
           # cycle that routinely takes 1-3 minutes and can approach the
@@ -572,6 +575,7 @@ module Clacky
         when ["GET",    "/api/local-image"]       then api_serve_local_image(req, res)
         when ["POST",   "/api/media/image"]       then api_media_image(req, res)
         when ["POST",   "/api/media/video"]       then api_media_video(req, res)
+        when ["GET",    "/api/media/video/status"] then api_media_video_status(req, res)
         when ["POST",   "/api/media/audio/speech"] then api_media_audio_speech(req, res)
         when ["POST",   "/api/media/audio/transcriptions"] then api_media_audio_transcriptions(req, res)
         when ["POST",   "/api/media/video/understand"]     then api_media_video_understand(req, res)
@@ -1539,7 +1543,16 @@ module Clacky
           aspect_ratio: aspect_ratio,
           duration_seconds: duration,
           output_dir: output_dir,
-          image: image
+          image: image,
+          first_frame: body["first_frame"],
+          last_frame: body["last_frame"],
+          reference_images: body["reference_images"],
+          reference_videos: body["reference_videos"],
+          reference_audios: body["reference_audios"],
+          resolution: body["resolution"],
+          generate_audio: body["generate_audio"],
+          watermark: body["watermark"],
+          seed: body["seed"]
         )
         if result["success"]
           log_media_usage(result, prompt: prompt, session_id: session_id)
@@ -1550,6 +1563,25 @@ module Clacky
         json_response(res, 500, { error: e.message })
       end
 
+      def api_media_video_status(req, res)
+        query   = URI.decode_www_form(req.query_string.to_s).to_h
+        task_id = query["task_id"].to_s
+        if task_id.strip.empty?
+          return json_response(res, 422, { error: "task_id is required" })
+        end
+
+        output_dir = query["output_dir"].to_s
+        output_dir = @agent_config.default_working_dir || Dir.pwd if output_dir.empty?
+
+        result = Clacky::Media::Generator.new(@agent_config).video_status(
+          task_id: task_id,
+          output_dir: output_dir
+        )
+        json_response(res, 200, result)
+      rescue StandardError => e
+        json_response(res, 500, { error: e.message })
+      end
+
       def api_media_audio_speech(req, res)
         body = parse_json_body(req)
         return json_response(res, 400, { error: "Invalid JSON" }) unless body
@@ -3730,6 +3762,20 @@ module Clacky
         file_size = File.size(path)
         mime = Utils::FileProcessor::MIME_TYPES[ext] || "application/octet-stream"
 
+        # ETag from mtime+size so an overwritten same-name file invalidates the
+        # browser cache. Use no-cache (revalidate every time) rather than
+        # max-age: unchanged files return 304 (no body), changed files return
+        # the new bytes.
+        stat = File.stat(path)
+        etag = %(W/"#{stat.mtime.to_i}-#{stat.size}")
+        res["Cache-Control"] = "private, no-cache"
+        res["ETag"] = etag
+        if req["If-None-Match"] == etag
+          res.status = 304
+          res.body = ""
+          return
+        end
+
         # Support HTTP Range requests for video seeking
         range_header = req["Range"]
         if range_header && range_header =~ /\Abytes=(\d*)-(\d*)\z/
@@ -3741,14 +3787,12 @@ module Clacky
           res["Content-Type"]  = mime
           res["Content-Range"] = "bytes #{start_byte}-#{end_byte}/#{file_size}"
           res["Accept-Ranges"] = "bytes"
-          res["Cache-Control"] = "private, max-age=3600"
           res["Content-Length"] = (end_byte - start_byte + 1).to_s
           IO.binread(path, end_byte - start_byte + 1, start_byte).then { |data| res.body = data }
         else
           res.status         = 200
           res["Content-Type"] = mime
           res["Accept-Ranges"] = "bytes"
-          res["Cache-Control"] = "private, max-age=3600"
           res.body = File.binread(path)
         end
       rescue => e

data/lib/clacky/tools/terminal.rb

@@ -607,9 +607,22 @@ module Clacky
           ""
         )
 
-        # Pass 1: anchored strip — the full wrapper echoed at the start,
-        # possibly spanning multiple real newlines.
-        text = text.sub(/\A\{.*?"\$__clacky_ec"\s*\n?/m, "")
+        # Pass 1: anchored strip — remove ONLY the wrapper's echoed head
+        # line (`{ USER_CMD`) at the very start of the buffer, and ONLY
+        # when a matching wrapper tail fingerprint (`}...; __clacky_ec=$?`)
+        # actually exists somewhere in the buffer. The guard is what keeps
+        # us from eating a real first line of user output that merely
+        # happens to start with `{` (e.g. JSON like `{"key": ...}`).
+        # We test the tail with a separate anchor-free `match?` (linear, no
+        # backtracking) rather than a lookahead, to avoid catastrophic
+        # regex backtracking on large `{`-prefixed output. We strip a
+        # single line (`[^\n]*`, not cross-line `.*?`): a multi-line command
+        # echoed in cooked mode puts the wrapper tail *after* the real
+        # output, so cross-line greed would swallow that output whole. The
+        # tail itself is removed by the fingerprint passes below.
+        if text.start_with?("{") && text.match?(/\}[^\n;]*; *__clacky_ec=\$\?/)
+          text = text.sub(/\A\{[^\n]*\n/, "")
+        end
 
         # Pass 2: token-aware global strip — remove any leftover wrapper
         # echo fragment, wherever it sits. Requires the session token so
@@ -629,9 +642,11 @@ module Clacky
           # 2b. Single-line shape: everything collapsed onto one line.
           # Strip from the wrapper's `}; __clacky_ec=$?` pivot (or the
           # opening `{` if still present on that line) through the end of
-          # the printf invocation (`"$__clacky_ec"`).
+          # the printf invocation (`"$__clacky_ec"`). The optional
+          # `[^\n;]*` between `}` and `;` absorbs a WSL `</dev/null`
+          # stdin redirect spliced onto the group.
           text = text.gsub(
-            /[^\n]*\}; *__clacky_ec=\$\?; *printf[^\n]*__CLACKY_DONE_#{token_re}_[^\n]*"\$__clacky_ec"[^\n]*\n?/,
+            /[^\n]*\}[^\n;]*; *__clacky_ec=\$\?; *printf[^\n]*__CLACKY_DONE_#{token_re}_[^\n]*"\$__clacky_ec"[^\n]*\n?/,
             ""
           )
 
@@ -653,9 +668,10 @@ module Clacky
         # private double-underscore var name that user code effectively
         # never emits — so we strip anything between them (non-greedy,
         # multiline-aware) to also handle width-wrap that inserted
-        # real \n breaks inside the echo.
+        # real \n breaks inside the echo. `[^\n;]*` between `}` and `;`
+        # absorbs a WSL `</dev/null` stdin redirect on the group.
         text = text.gsub(
-          /[^\n]*\}; *__clacky_ec=\$\?.*?"\$__clacky_ec"[^\n]*\n?/m,
+          /[^\n]*\}[^\n;]*; *__clacky_ec=\$\?.*?"\$__clacky_ec"[^\n]*\n?/m,
           ""
         )
 
@@ -663,7 +679,7 @@ module Clacky
         # truncation cut off everything after `__clacky_ec=$?`). Still a
         # reliable fingerprint thanks to the `__clacky_ec` var name.
         text = text.gsub(
-          /[^\n]*\}; *__clacky_ec=\$\?;?[^\n]*\n?/,
+          /[^\n]*\}[^\n;]*; *__clacky_ec=\$\?;?[^\n]*\n?/,
           ""
         )
 

data/lib/clacky/ui2/layout_manager.rb

@@ -402,6 +402,10 @@ module Clacky
           screen.show_cursor
           screen.flush
         end
+        # Restore cooked mode so the terminal is usable after exit, regardless
+        # of which exit path was taken (some call exit(0) and bypass the
+        # input_loop ensure). Idempotent; safe to call more than once.
+        screen.disable_raw_mode
       end
 
       # /clear: wipe output area + buffer, keep fixed area.

data/lib/clacky/ui2/screen_buffer.rb

@@ -118,14 +118,42 @@ module Clacky
         @height = TTY::Screen.height
       end
 
-      # Enable raw mode (disable line buffering)
+      # Enable raw mode (disable line buffering). The very first time it runs it
+      # snapshots the terminal's original settings (via `stty -g`) so the exact
+      # pre-clacky state can be restored on exit — `IO#cooked!` only applies a
+      # generic cooked profile and does not restore flow-control (IXON) and other
+      # bits, which on macOS leaves the shell in a broken input state.
       def enable_raw_mode
+        return unless $stdin.tty?
+
+        @original_stty ||= capture_stty
         $stdin.raw!
       end
 
-      # Disable raw mode
+      # Disable raw mode. Idempotent and tty-guarded so it can be safely called
+      # from any exit path. Restores the exact original terminal settings when a
+      # snapshot exists, then flushes pending input so stray bytes don't leak to
+      # the shell. Falls back to `IO#cooked!` when no snapshot is available.
       def disable_raw_mode
-        $stdin.cooked!
+        return unless $stdin.tty?
+
+        $stdin.cooked! unless @original_stty && restore_stty(@original_stty)
+        $stdin.ioflush
+      rescue IOError, Errno::ENOTTY
+        nil
+      end
+
+      private def capture_stty
+        out = Clacky::Utils::Encoding.cmd_to_utf8(`stty -g 2>/dev/null`).strip
+        out.empty? ? nil : out
+      rescue StandardError
+        nil
+      end
+
+      private def restore_stty(state)
+        system("stty", state, out: File::NULL, err: File::NULL)
+      rescue StandardError
+        false
       end
 
       # Read a single character without echo

data/lib/clacky/utils/file_processor.rb

@@ -604,8 +604,7 @@ module Clacky
 
         ext = File.extname(path).downcase
         if LOCAL_MEDIA_EXTENSIONS.include?(ext) && File.exist?(path)
-          encoded = CGI.escape(href)
-          "![#{alt}](/api/local-image?path=#{encoded})"
+          "![#{alt}](#{local_image_proxy_url(href, path)})"
         else
           _match
         end
@@ -622,8 +621,7 @@ module Clacky
 
         ext = File.extname(path).downcase
         if LOCAL_VIDEO_EXTENSIONS.include?(ext) && File.exist?(path)
-          encoded = CGI.escape(href)
-          "<video#{pre} src=\"/api/local-image?path=#{encoded}\"#{post}>"
+          "<video#{pre} src=\"#{local_image_proxy_url(href, path)}\"#{post}>"
         else
           _match
         end
@@ -640,8 +638,7 @@ module Clacky
 
         ext = File.extname(path).downcase
         if LOCAL_AUDIO_EXTENSIONS.include?(ext) && File.exist?(path)
-          encoded = CGI.escape(href)
-          "<audio#{pre} src=\"/api/local-image?path=#{encoded}\"#{post}>"
+          "<audio#{pre} src=\"#{local_image_proxy_url(href, path)}\"#{post}>"
         else
           _match
         end
@@ -658,8 +655,7 @@ module Clacky
         ext = File.extname(path).downcase
         if LOCAL_VIDEO_EXTENSIONS.include?(ext) || LOCAL_AUDIO_EXTENSIONS.include?(ext)
           if File.exist?(path)
-            encoded = CGI.escape(href)
-            "[#{text}](/api/local-image?path=#{encoded})"
+            "[#{text}](#{local_image_proxy_url(href, path)})"
           else
             _match
           end
@@ -670,6 +666,15 @@ module Clacky
 
       content
     end
+
+    # Build a proxy URL for a local media file, appending a version param
+    # derived from the file mtime so an overwritten same-name file produces a
+    # different URL and defeats the browser's in-memory image cache.
+    def self.local_image_proxy_url(href, path)
+      encoded = CGI.escape(href)
+      version = File.mtime(path).to_i
+      "/api/local-image?path=#{encoded}&v=#{version}"
+    end
   end
   end
 end