lato_cms 3.0.13 → 3.1.1

data/app/controllers/lato_cms/pages_controller.rb

@@ -9,10 +9,6 @@ module LatoCms
       translations link_translation_action unlink_translation_action
     ].freeze
 
-    # Field types whose value lives in Active Storage attachments instead of
-    # `value`, so `required` must be checked against the attached files.
-    ATTACHMENT_FIELD_TYPES = %w[file image video gallery].freeze
-
     before_action { active_sidebar(:lato_cms_pages) }
     before_action :authenticate_lato_cms_admin, only: ADMIN_ONLY_ACTIONS
 
@@ -30,6 +26,20 @@ module LatoCms
       )
     end
 
+    def sitemap_export_action
+      @operation = Lato::Operation.generate(
+        'LatoCms::ExportSitemapCsvJob',
+        { lato_spaces_group_id: @session.get(:spaces_group_id) },
+        @session.user_id
+      )
+
+      if @operation.start
+        redirect_to lato.operation_path(@operation)
+      else
+        redirect_to lato_cms.pages_path, alert: t('lato_cms.sitemap_export_failed')
+      end
+    end
+
     def show
       @page = query_pages.find(params[:id])
       @page.fields.load
@@ -143,15 +153,37 @@ module LatoCms
       @page = query_pages.find(params[:id])
       source = @page.translations.find_by(id: params[:source_page_id])
       template_component_id = params[:template_component_id].to_s
+      translate = ActiveModel::Type::Boolean.new.cast(params[:translate]) && LatoCms.config.llm_configured?
 
-      respond_to do |format|
-        if source && clone_component_fields(source, @page, template_component_id)
-          format.html { redirect_to lato_cms.pages_show_path(@page), notice: t('lato_cms.component_cloned') }
-          format.json { render json: { message: t('lato_cms.component_cloned') } }
-        else
+      unless source && clone_component_fields(source, @page, template_component_id)
+        respond_to do |format|
           format.html { redirect_to lato_cms.pages_show_path(@page), alert: t('lato_cms.component_clone_failed') }
           format.json { render json: { error: t('lato_cms.component_clone_failed') }, status: :unprocessable_entity }
         end
+        return
+      end
+
+      unless translate
+        respond_to do |format|
+          format.html { redirect_to lato_cms.pages_show_path(@page), notice: t('lato_cms.component_cloned') }
+          format.json { render json: { message: t('lato_cms.component_cloned') } }
+        end
+        return
+      end
+
+      # The clone above already happened synchronously and succeeded; only the
+      # translation step (a real network call to the LLM) runs as a
+      # Lato::Operation, so it can never block this request or time it out.
+      operation = Lato::Operation.generate(
+        'LatoCms::TranslateComponentFieldsJob',
+        { page_id: @page.id, template_component_id: template_component_id },
+        @session.user_id
+      )
+
+      if operation.start
+        redirect_to lato.operation_path(operation)
+      else
+        redirect_to lato_cms.pages_show_path(@page), alert: t('lato_cms.component_clone_translate_failed')
       end
     end
 
@@ -206,7 +238,12 @@ module LatoCms
     private
 
     # Replaces the target page's fields for a component with copies of the source
-    # page's fields for the same component. Attachments share the source blobs.
+    # page's fields for the same component. Media references are shared (not
+    # duplicated), so a cloned video field's poster stays correct for free.
+    # Media's own alt text is untouched here — it's translated independently
+    # by its own LLM job (see LatoCms::Media), not as part of cloning a
+    # page's fields. Translation, when requested, is a separate async step
+    # (see clone_component_action) on top of this already-committed clone.
     def clone_component_fields(source, target, template_component_id)
       # Components are template-specific: only clone between pages using the same template.
       return false unless source.template_id == target.template_id
@@ -225,7 +262,7 @@ module LatoCms
             field_id: src.field_id,
             value: src.value
           )
-          src.files.each { |file| field.files.attach(file.blob) }
+          field.replace_media!(src.media.pluck(:id))
         end
       end
 
@@ -288,41 +325,33 @@ module LatoCms
       field_config = component&.dig('fields', config_field_id)
       field_type = field_config&.dig('type') || 'string'
 
-      assign_field_value(field, field_type, field_data)
-
-      unless field.save
-        errors << { field_id: persisted_field_id, errors: field.errors.full_messages }
-        return
+      if LatoCms::PageField::ATTACHMENT_FIELD_TYPES.include?(field_type)
+        # Bootstrap-persist to get an id so join rows can reference it before
+        # the real, validated save below (the one that actually enforces
+        # `required`, now possible since media presence is a real association).
+        field.save(validate: false) if field.new_record?
+        assign_media_field_value(field, field_type, field_data)
+      else
+        assign_scalar_field_value(field, field_type, field_data)
       end
 
-      # Attachments are attached/purged here in the controller, so the model
-      # cannot validate `required` for attachment fields. Backstop the
-      # client-side enforcement: a required field must end the save with at
-      # least one file, otherwise required would be bypassable.
-      if ATTACHMENT_FIELD_TYPES.include?(field_type) && field_config&.dig("required") == true && field.files.reload.empty?
-        errors << { field_id: persisted_field_id, errors: [t("lato_cms.field_required_attachment_error")] }
-      end
+      errors << { field_id: persisted_field_id, errors: field.errors.full_messages } unless field.save
     end
 
-    def assign_field_value(field, field_type, field_data)
+    def assign_media_field_value(field, field_type, field_data)
       case field_type
       when 'file'
-        field.save if field.new_record?
-        assign_file_field_files(field, field_data)
-      when 'image'
-        field.save if field.new_record?
-        replace_field_image(field, field_data)
-      when 'video'
-        field.save if field.new_record?
-        replace_field_video(field, field_data)
+        ids = field.field_settings['multiple'] == true ? Array(field_data[:media_ids]) : [field_data[:media_id]]
+        assign_media_field(field, ids)
+      when 'image', 'video'
+        assign_media_field(field, [field_data[:media_id]])
       when 'gallery'
-        field.save if field.new_record?
-        attach_field_files(field, field_data)
-        remove_field_files(field, field_data)
-        order = Array(field_data[:order]).reject(&:blank?).map(&:to_s)
-        all_ids = field.files.reload.map { |f| f.id.to_s }
-        sorted = order.select { |id| all_ids.include?(id) }
-        field.value = (sorted + (all_ids - sorted)).to_json
+        assign_media_field(field, Array(field_data[:media_ids]))
+      end
+    end
+
+    def assign_scalar_field_value(field, field_type, field_data)
+      case field_type
       when 'multiselect'
         field.value = Array(field_data[:value]).reject(&:blank?).to_json
       else
@@ -331,58 +360,13 @@ module LatoCms
       end
     end
 
-    # Browsers submit empty entries for file inputs with no selection: strip
-    # them so `attach` never receives a blank value and the required check
-    # sees the field as actually empty.
-    def submitted_files(field_data)
-      Array(field_data[:files]).reject(&:blank?)
-    end
-
-    def attach_field_files(field, field_data)
-      submitted_files(field_data).each { |file| field.files.attach(file) }
-    end
-
-    def assign_file_field_files(field, field_data)
-      new_file = submitted_files(field_data).first
-      if field.field_settings['multiple'] != true && new_file
-        field.files.each(&:purge)
-        field.files.attach(new_file)
-      else
-        attach_field_files(field, field_data)
-        remove_field_files(field, field_data)
-      end
-    end
-
-    def remove_field_files(field, field_data)
-      return unless field_data[:remove_file_ids].present?
-
-      Array(field_data[:remove_file_ids]).reject(&:blank?).each do |file_id_to_remove|
-        field.files.find { |file| file.id == file_id_to_remove.to_i }&.purge
-      end
-    end
-
-    def replace_field_image(field, field_data)
-      new_file = submitted_files(field_data).first
-      if new_file
-        field.files.each(&:purge)
-        field.files.attach(new_file)
-      else
-        remove_field_files(field, field_data)
-      end
-    end
-
-    # Single-video semantics: uploading a new video replaces both the previous
-    # video and its auto-generated poster; removing the video drops the poster
-    # too. Poster generation runs in a background job to keep the save fast.
-    def replace_field_video(field, field_data)
-      new_file = submitted_files(field_data).first
-      if new_file
-        field.files.each(&:purge)
-        field.files.attach(new_file)
-        LatoCms::GenerateVideoPosterJob.perform_later(field.id)
-      elsif field_data[:remove_file_ids].present?
-        field.files.each(&:purge)
-      end
+    # Tenant-scopes the submitted media ids (drops any id outside this
+    # session's spaces group) before delegating to the model, preserving the
+    # order given by the client.
+    def assign_media_field(field, media_ids)
+      ordered_ids = Array(media_ids).reject(&:blank?).map(&:to_s).uniq
+      allowed_ids = query_media.where(id: ordered_ids).pluck(:id).map(&:to_s)
+      field.replace_media!(ordered_ids & allowed_ids)
     end
 
     def create_params

data/app/helpers/lato_cms/media_helper.rb

@@ -0,0 +1,50 @@
+module LatoCms
+  module MediaHelper
+    MEDIA_TYPE_ICONS = {
+      'image' => 'bi-image',
+      'video' => 'bi-film',
+      'document' => 'bi-file-earmark-text',
+      'file' => 'bi-paperclip'
+    }.freeze
+
+    # Index name cell: thumbnail (or type icon) + name + filename.
+    def lato_cms_media_name(media)
+      content_tag(:div, class: 'd-flex align-items-center gap-2') do
+        concat lato_cms_media_thumb(media)
+        concat(content_tag(:div) do
+          concat content_tag(:div, media.name)
+          concat content_tag(:span, media.filename, class: 'text-muted small')
+        end)
+      end
+    end
+
+    # Small thumbnail (image variant) or a type icon when there's no visual preview.
+    def lato_cms_media_thumb(media, size: 40)
+      if media.thumbnail_url
+        image_tag media.thumbnail_url, class: 'rounded', style: "width: #{size}px; height: #{size}px; object-fit: cover;", alt: media.alt_text
+      else
+        content_tag(:div, class: 'd-flex align-items-center justify-content-center bg-light rounded text-muted',
+          style: "width: #{size}px; height: #{size}px;") do
+          content_tag(:i, '', class: "bi #{MEDIA_TYPE_ICONS[media.media_type] || 'bi-file-earmark'}")
+        end
+      end
+    end
+
+    def lato_cms_media_media_type(media)
+      content_tag(:span, media.media_type, class: 'badge bg-secondary')
+    end
+
+    # Index actions cell: edit metadata + delete (delete gated to admins, same
+    # convention as pages).
+    def lato_cms_media_actions(media)
+      content_tag(:div, class: 'btn-group btn-group-sm') do
+        concat link_to(t('lato_cms.cta_edit'), lato_cms.media_update_path(media), class: 'btn btn-secondary',
+          data: { lato_action_target: 'trigger', turbo_frame: dom_id(media, 'form'), action_title: t('lato_cms.media_update_title') })
+        if lato_cms_admin?
+          concat link_to(t('lato_cms.cta_delete'), lato_cms.media_destroy_action_path(media), class: 'btn btn-danger',
+            data: { turbo_method: 'DELETE', turbo_confirm: t('lato_cms.cta_delete_confirm') })
+        end
+      end
+    end
+  end
+end

data/app/jobs/lato_cms/export_sitemap_csv_job.rb

@@ -0,0 +1,33 @@
+require 'csv'
+
+module LatoCms
+  # Exports every page across every locale of a spaces group as a CSV sitemap.
+  # Runs as a Lato::Operation so large sites don't block the request.
+  class ExportSitemapCsvJob < Lato::ApplicationJob
+    def perform(params = {})
+      params = params.with_indifferent_access
+      pages = LatoCms::Page.for_lato_spaces_group(params[:lato_spaces_group_id]).order(:locale, :permalink)
+
+      file_path = Rails.root.join('tmp', "sitemap_#{SecureRandom.hex(8)}.csv")
+      generate_csv(file_path, pages)
+
+      return file_path unless operation?
+
+      save_operation_output_file(file_path)
+      save_operation_output_message(I18n.t('lato_cms.sitemap_export_message', count: pages.count))
+    ensure
+      File.delete(file_path) if file_path && File.exist?(file_path)
+    end
+
+    private
+
+    def generate_csv(file_path, pages)
+      CSV.open(file_path, 'wb') do |csv|
+        csv << %w[locale title permalink frontend_url]
+        pages.find_each do |page|
+          csv << [page.locale, page.title, page.permalink, page.frontend_url]
+        end
+      end
+    end
+  end
+end

data/app/jobs/lato_cms/generate_alt_text_job.rb

@@ -0,0 +1,21 @@
+module LatoCms
+  # Generates alt text for an image Media via an OpenAI-compatible LLM.
+  # Doubles as a plain background job (automatic post-upload call site, see
+  # Media#enqueue_alt_text_generation: fire-and-forget, best effort, never
+  # blocks the upload) and as a Lato::Operation-backed job (the "Regenerate
+  # with AI" admin action, see MediaController#regenerate_alt_text_action:
+  # the admin is watching, so failures should surface instead of being
+  # swallowed). Inheriting Lato::ApplicationJob makes both work from the
+  # same perform: `operation?` is only true when a `_operation_id` was
+  # injected by Lato::Operation#start.
+  class GenerateAltTextJob < Lato::ApplicationJob
+    def perform(params = {})
+      params = params.with_indifferent_access
+      media = LatoCms::Media.find_by(id: params[:media_id])
+      return unless media
+
+      media.generate_alt_text!(raise_on_error: operation?)
+      save_operation_output_message(I18n.t('lato_cms.media_alt_text_regenerated')) if operation?
+    end
+  end
+end

data/app/jobs/lato_cms/generate_video_poster_job.rb

@@ -1,12 +1,14 @@
 module LatoCms
-  # Generates the poster image for a video field in the background so the save
-  # request is not blocked by ffmpeg processing. Failures are swallowed by the
-  # model (logged as warnings): a missing poster must never break the field.
+  # Generates the poster image for a video Media in the background so the
+  # upload request is not blocked by ffmpeg processing. Runs once per Media
+  # (not per field usage), since the same video can be referenced by many
+  # fields. Failures are swallowed by the model (logged as warnings): a
+  # missing poster must never break the video.
   class GenerateVideoPosterJob < ApplicationJob
     queue_as :default
 
-    def perform(page_field_id)
-      LatoCms::PageField.find_by(id: page_field_id)&.generate_video_poster!
+    def perform(media_id)
+      LatoCms::Media.find_by(id: media_id)&.generate_video_poster!
     end
   end
 end

data/app/jobs/lato_cms/translate_component_fields_job.rb

@@ -0,0 +1,16 @@
+module LatoCms
+  # Translates a just-cloned component's free-text fields via the configured
+  # LLM, as a Lato::Operation so a slow/unreachable LLM never blocks the
+  # clone request (see PagesController#clone_component_action). The verbatim
+  # clone this follows has already happened synchronously and is not undone
+  # if this fails.
+  class TranslateComponentFieldsJob < Lato::ApplicationJob
+    def perform(params = {})
+      params = params.with_indifferent_access
+      page = LatoCms::Page.find(params[:page_id])
+      page.translate_component_fields!(params[:template_component_id])
+
+      save_operation_output_message(I18n.t('lato_cms.component_clone_translated')) if operation?
+    end
+  end
+end

data/app/models/lato_cms/llm_client.rb

@@ -0,0 +1,31 @@
+require 'net/http'
+
+module LatoCms
+  # Thin transport for the configured OpenAI-compatible chat completions
+  # endpoint (see LatoCms::Config#llm_configured?). Callers own their own
+  # prompt/response-shape concerns (e.g. LatoCms::Media for alt text,
+  # LatoCms::PagesController for translating cloned fields); this class only
+  # knows how to send `messages` and hand back the response's text content.
+  class LlmClient
+    class Error < StandardError; end
+
+    def self.chat(messages:)
+      uri = URI.join("#{LatoCms.config.llm_api_url.chomp('/')}/", 'chat/completions')
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = 10
+      http.read_timeout = 30
+
+      request = Net::HTTP::Post.new(uri)
+      request['Content-Type'] = 'application/json'
+      request['Authorization'] = "Bearer #{LatoCms.config.llm_api_key}"
+      request.body = { model: LatoCms.config.llm_model, messages: messages }.to_json
+
+      response = http.request(request)
+      raise Error, "LLM request failed with status #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(response.body).dig('choices', 0, 'message', 'content')
+    end
+  end
+end

data/app/models/lato_cms/media.rb

@@ -0,0 +1,270 @@
+require 'base64'
+
+module LatoCms
+  class Media < ApplicationRecord
+    attr_accessor :actions
+
+    include LatoSpaces::Associable
+    include LatoSpaces::AssociableRequired
+    include LatoSpaces::AssociableUnique
+
+    MEDIA_TYPES = %w[image video document file].freeze
+
+    # alt_text is stored as a single JSON-serialized {locale => text} hash in
+    # the `alt_text` column (kept as one column rather than a translations
+    # table since it's the only translatable attribute Media has). `alt_text`
+    # itself is overridden below to read/write the current I18n.locale's
+    # entry; `alt_text_en`, `alt_text_it`, etc. (one per configured locale)
+    # are handled dynamically so forms can render/submit them like any other
+    # attribute without predefining a method per locale.
+    ALT_TEXT_ACCESSOR = /\Aalt_text_(?<locale>[a-z]{2}(?:_[A-Z]{2})?)(?<setter>=)?\z/
+
+    has_one_attached :file
+    has_one_attached :poster_file
+
+    has_many :page_field_media, class_name: 'LatoCms::PageFieldMedia', foreign_key: :media_id, dependent: :destroy
+    has_many :page_fields, through: :page_field_media, class_name: 'LatoCms::PageField'
+
+    validates :name, presence: true
+    validate :file_attached, on: :create
+
+    before_validation :default_name_from_filename, on: :create
+    before_validation :set_media_type, on: :create
+
+    after_create_commit :enqueue_poster_generation, if: :video?
+    after_create_commit :enqueue_alt_text_generation, if: -> { image? && LatoCms.config.llm_configured? }
+
+    scope :of_type, ->(type) { where(media_type: type) if type.present? }
+
+    def self.infer_media_type(content_type)
+      content_type = content_type.to_s
+      return 'image' if content_type.start_with?('image/')
+      return 'video' if content_type.start_with?('video/')
+      return 'document' if content_type == 'application/pdf' || content_type.start_with?('application/vnd') || content_type.start_with?('text/')
+
+      'file'
+    end
+
+    def self.variant_transformation(opts)
+      opts = {} unless opts.respond_to?(:[])
+      dimensions = [opts['width'] || opts[:width], opts['height'] || opts[:height]]
+      return nil if dimensions.compact.empty?
+
+      case (opts['resize'] || opts[:resize] || 'limit').to_s
+      when 'fill' then { resize_to_fill: dimensions }
+      when 'fit' then { resize_to_fit: dimensions }
+      else { resize_to_limit: dimensions }
+      end
+    end
+
+    def image?
+      media_type == 'image'
+    end
+
+    def video?
+      media_type == 'video'
+    end
+
+    def usage_count
+      page_field_media.count
+    end
+
+    def filename
+      file.filename.to_s if file.attached?
+    end
+
+    def alt_text(locale = I18n.locale)
+      alt_text_translations[locale.to_s].presence
+    end
+
+    def alt_text=(value)
+      self.alt_text_translations = alt_text_translations.merge(I18n.locale.to_s => value)
+    end
+
+    def alt_text_translations
+      JSON.parse(self[:alt_text].presence || '{}')
+    rescue JSON::ParserError
+      {}
+    end
+
+    def alt_text_translations=(hash)
+      self[:alt_text] = hash.stringify_keys.to_json
+    end
+
+    def method_missing(name, *args)
+      match = ALT_TEXT_ACCESSOR.match(name.to_s)
+      return super unless match
+
+      if match[:setter]
+        self.alt_text_translations = alt_text_translations.merge(match[:locale] => args.first)
+      else
+        alt_text_translations[match[:locale]].presence
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      ALT_TEXT_ACCESSOR.match?(name.to_s) || super
+    end
+
+    def url
+      Rails.application.routes.url_helpers.rails_blob_path(file, only_path: true) if file.attached?
+    end
+
+    def poster_url
+      Rails.application.routes.url_helpers.rails_blob_path(poster_file, only_path: true) if poster_file.attached?
+    end
+
+    # Best effort: generates a poster from the video via Active Storage previews
+    # (ffmpeg). Any failure is logged, the video keeps working without a poster.
+    def generate_video_poster!
+      return unless video? && file.attached?
+      return if poster_file.attached?
+
+      unless file.previewable?
+        Rails.logger.warn("LatoCms: video preview unavailable (ffmpeg missing?) for media #{id}, skipping poster generation")
+        return
+      end
+
+      preview = file.preview(resize_to_limit: [1280, 720]).processed
+      preview.image.blob.open do |f|
+        poster_file.attach(io: f, filename: "#{file.filename.base}_poster.jpg", content_type: preview.image.blob.content_type)
+      end
+    rescue StandardError => e
+      Rails.logger.warn("LatoCms: failed to generate video poster for media #{id}: #{e.message}")
+    end
+
+    # Asks the configured OpenAI-compatible LLM for alt text in every
+    # configured locale and merges it in (existing translations for locales
+    # the LLM didn't return, or that it's re-run for, are kept/replaced
+    # individually). No-op unless an LLM is configured (see
+    # LatoCms::Config#llm_configured?) and this media is an image.
+    #
+    # Best effort by default (`raise_on_error: false`): any failure is logged
+    # and swallowed, since the automatic post-upload call site (see
+    # GenerateAltTextJob) must never break the upload over a flaky LLM. The
+    # manual "Regenerate with AI" action runs as a Lato::Operation the admin
+    # is actively watching, so it passes `raise_on_error: true` to have
+    # failures surface there instead of disappearing silently.
+    def generate_alt_text!(raise_on_error: false)
+      return unless image? && file.attached? && LatoCms.config.llm_configured?
+
+      translations = fetch_alt_text_translations
+      raise 'The LLM returned no usable alt text' if translations.blank?
+
+      self.alt_text_translations = alt_text_translations.merge(translations)
+      save!
+    rescue StandardError => e
+      Rails.logger.warn("LatoCms: failed to generate alt text for media #{id}: #{e.message}")
+      raise if raise_on_error
+    end
+
+    # Fixed small variant used across admin UI (Media index, picker grid, field
+    # preview) regardless of a field's own `settings.sizes` (used only by the
+    # public API, see `variant_urls`).
+    def thumbnail_url
+      return nil unless image? && file.attached? && file.variable?
+
+      Rails.application.routes.url_helpers.rails_representation_path(
+        file.variant(resize_to_fill: [200, 200]), only_path: true
+      )
+    rescue StandardError => e
+      Rails.logger.error("LatoCms: Failed to build thumbnail for media #{id}: #{e.message}")
+      nil
+    end
+
+    # Builds a map of { size_name => variant_url } from a field's `settings.sizes`
+    # config. The config is field-owned (different fields can request different
+    # crops of the same reused Media); the mechanics live here since Media owns
+    # the attached blob.
+    def variant_urls(sizes_config)
+      return {} if sizes_config.blank? || !sizes_config.respond_to?(:each_pair) || !file.attached? || !file.variable?
+
+      url_helpers = Rails.application.routes.url_helpers
+      sizes_config.each_with_object({}) do |(name, opts), acc|
+        transformation = self.class.variant_transformation(opts)
+        next if transformation.blank?
+
+        acc[name] = url_helpers.rails_representation_path(file.variant(transformation), only_path: true)
+      end
+    rescue StandardError => e
+      Rails.logger.error("LatoCms: Failed to build image variants for media #{id}: #{e.message}")
+      {}
+    end
+
+    def as_json(_options = {})
+      {
+        id: id,
+        name: name,
+        alt_text: alt_text,
+        alt_text_translations: alt_text_translations,
+        media_type: media_type,
+        filename: filename,
+        content_type: file.attached? ? file.content_type : nil,
+        byte_size: file.attached? ? file.byte_size : nil,
+        url: url,
+        thumbnail_url: thumbnail_url,
+        poster_url: poster_url,
+        usage_count: usage_count,
+        created_at: created_at,
+        updated_at: updated_at
+      }
+    end
+
+    private
+
+    def file_attached
+      errors.add(:file, :blank) unless file.attached?
+    end
+
+    def default_name_from_filename
+      self.name = file.filename.to_s if name.blank? && file.attached?
+    end
+
+    def set_media_type
+      self.media_type = self.class.infer_media_type(file.content_type) if file.attached?
+    end
+
+    def enqueue_poster_generation
+      LatoCms::GenerateVideoPosterJob.perform_later(id)
+    end
+
+    def enqueue_alt_text_generation
+      LatoCms::GenerateAltTextJob.perform_later(media_id: id)
+    end
+
+    def fetch_alt_text_translations
+      locales = LatoCms.config.locales.map(&:to_s)
+      content = request_alt_text_completion(locales)
+      parse_alt_text_response(content, locales)
+    end
+
+    # Sends the image as a base64 data URI rather than a URL: the file may be
+    # stored on a service (or behind auth) the LLM can't reach, so this works
+    # regardless of storage backend or app visibility settings.
+    def request_alt_text_completion(locales)
+      LatoCms::LlmClient.chat(messages: [{
+        role: 'user',
+        content: [
+          { type: 'text', text: alt_text_prompt(locales) },
+          { type: 'image_url', image_url: { url: "data:#{file.content_type};base64,#{Base64.strict_encode64(file.download)}" } }
+        ]
+      }])
+    end
+
+    def alt_text_prompt(locales)
+      "Write a concise, descriptive alt text for this image, for the HTML <img alt> attribute " \
+      "(accessibility use, not a caption). Respond with a single JSON object only, no markdown, " \
+      "no extra text, with exactly these keys: #{locales.join(', ')}. Each value is the alt text " \
+      "written in that language."
+    end
+
+    def parse_alt_text_response(content, locales)
+      return {} if content.blank?
+
+      parsed = JSON.parse(content[/\{.*\}/m] || content)
+      parsed.slice(*locales).transform_values(&:to_s)
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end