featureparity 0.0.22 → 0.0.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b06053deae8d893e793e13d2dd56773db5ff1ce04d2cc5f2be40b65da3520d11
-  data.tar.gz: 0c7d0b2ae20e481fedab84bf188d7a3b8c3ae47d91c0b16c816d49e697d2f16a
+  metadata.gz: 4e68b70dce16d28e928ead4413623002ccda97f4508f62bbe6d980c8bb29a21c
+  data.tar.gz: e630a9bd6f49db70c343f6374cd3c049a9c9fb4b786251dd313b76a177e0a1f9
 SHA512:
-  metadata.gz: b8f6ae3cedd0abb1c6a1cc248092d83f1643858d08aee76bd4d6707f1a5072bbc1f06d0ba83ed35cc79cd36afd24b543e625d58c6f9044c102f47b77a4cc2d79
-  data.tar.gz: c938e91cd9bbf92197bb0a85dcb6488d0c0621ed6760f12bdac0e4c23002bac09ca7232d3a12d93618011261d90150f98a02dc861e0f2b893bc8ac9f003d0b10
+  metadata.gz: 55bde2507b4cfccbe49b8d799d0b3e7efba22c0298450e823a3ac86299ec4d392b0e51f13c3c643a2abc1d60f1d68d091074420c0928fbbcf9da6947fea296d1
+  data.tar.gz: c5d9754313a59721bfc78f5d4e65d4924ef1f5120659037cace19e6ee816a96dea0e467f47ad285cf03003ba37ed836501754c5592f9b22385f5a52315be5cae

data/lib/fp/client.rb

@@ -96,6 +96,54 @@ module Fp
       get("/api/projects/#{project_id}/showroom/share_link")
     end
 
+    # --- Showroom media ---
+    #
+    # Screenshots and videos on the client showroom: on a surface's card, or in the
+    # project gallery under the welcome note (surface_id nil). Uploaded the same way as
+    # attachments — presign, PUT the bytes, then confirm.
+
+    # GET /projects/:id/showroom/media
+    def list_showroom_media(project_id)
+      get("/api/projects/#{project_id}/showroom/media")
+    end
+
+    # POST /projects/:id/showroom/media/presign
+    def presign_showroom_media(project_id, filename:, content_type:, size_bytes:, surface_id: nil, purpose: nil)
+      body = { filename: filename, content_type: content_type, size_bytes: size_bytes }
+      body[:surface_id] = surface_id if surface_id
+      body[:purpose] = purpose if purpose
+      post("/api/projects/#{project_id}/showroom/media/presign", body)
+    end
+
+    # POST /projects/:id/showroom/media
+    # Confirm an upload and create the media record.
+    def create_showroom_media(project_id, media_id:, s3_key:, filename:, content_type:, size_bytes:,
+                              surface_id: nil, caption: nil, position: nil, purpose: nil)
+      body = {
+        media_id: media_id,
+        s3_key: s3_key,
+        filename: filename,
+        content_type: content_type,
+        size_bytes: size_bytes
+      }
+      body[:surface_id] = surface_id if surface_id
+      body[:caption] = caption if caption
+      body[:position] = position if position
+      body[:purpose] = purpose if purpose
+      post("/api/projects/#{project_id}/showroom/media", body)
+    end
+
+    # PUT /projects/:id/showroom/media/:media_id
+    # { caption?, position? } — an empty caption clears it, position 0 clears it.
+    def update_showroom_media(project_id, media_id, params)
+      put("/api/projects/#{project_id}/showroom/media/#{media_id}", params)
+    end
+
+    # DELETE /projects/:id/showroom/media/:media_id
+    def delete_showroom_media(project_id, media_id)
+      delete("/api/projects/#{project_id}/showroom/media/#{media_id}")
+    end
+
     # GET /requirements
     def list_requirements(project_id: nil, status: nil, category: nil, tag: nil)
       params = {}

data/lib/fp/commands/attach.rb

@@ -212,13 +212,6 @@ module Fp
         output.error(message)
         1
       end
-
-      def format_size(bytes)
-        return format('%.1f MB', bytes.to_f / (1024 * 1024)) if bytes >= 1024 * 1024
-        return format('%.1f KB', bytes.to_f / 1024) if bytes >= 1024
-
-        "#{bytes} bytes"
-      end
     end
   end
 end

data/lib/fp/commands/base.rb

@@ -239,6 +239,14 @@ module Fp
         opts[:project]
       end
 
+      # "12.3 MB" / "4.0 KB" / "512 bytes", for upload limits and file listings.
+      def format_size(bytes)
+        return format('%.1f MB', bytes.to_f / (1024 * 1024)) if bytes >= 1024 * 1024
+        return format('%.1f KB', bytes.to_f / 1024) if bytes >= 1024
+
+        "#{bytes} bytes"
+      end
+
       def truncate(str, max)
         return str if str.nil? || str.length <= max
 

data/lib/fp/commands/help.rb

@@ -50,6 +50,10 @@ module Fp
             surfaces edit <key> --project ... Change a surface (name, kind, repo, key, showroom card...)
             surfaces delete <key> --project . Delete a surface (asks first; --yes to skip)
             showroom --project <slug>         Preview the client showroom as a client sees it
+            showroom media --project <slug>   List the showroom's screenshots and videos
+            showroom media add <file> ...     Add an image/video to a surface card (--surface) or the gallery
+            showroom media edit <id> ...      Change a media item's --caption or --position
+            showroom media remove <id> --yes  Take a media item off the showroom
             list --project <slug>             List active requirements
             show <slug> --project <slug>      Show requirement details
             propose --project <slug> ...      Propose a new requirement (as draft)
@@ -106,10 +110,13 @@ module Fp
               fp surfaces edit web --showroom-url https://dev.example.com \\
                                    --showroom-label "Open the web app" \\
                                    --showroom-instructions-file docs/showroom/web.txt
+              fp showroom media add e2e/checkout.webm --surface web --caption "Checking out"
+              fp showroom media add overview.png   # no --surface: the gallery under the welcome
               fp showroom          # what the client will see, and which surfaces are hidden
 
-            A surface is shown once it has a link or instructions; pass an empty value
-            to clear a field (`--showroom-url ""`) and a surface with neither drops out.
+            A surface is shown once it has a link, instructions, or media; pass an empty
+            value to clear a field (`--showroom-url ""`) and a surface with none drops out.
+            Media is images and video only (png, jpg, gif, webp, mp4, webm, mov; 100 MB).
             Leaving feedback and turning the share link on or off are for humans, in the
             web app under Project Settings → Showroom.
 

data/lib/fp/commands/showroom.rb

@@ -14,15 +14,38 @@ module Fp
     #
     # Whether the share link is on is a human's business — the API refuses an agent's
     # key — so it is reported as unknown rather than guessed at.
+    #
+    # `fp showroom media ...` manages the screenshots and videos on the showroom — a
+    # surface's card, or the gallery under the welcome note — and is handled by
+    # ShowroomMedia; its flags are documented here so `fp showroom --help` covers both.
     class Showroom < Base
-      help_summary 'Preview the client showroom exactly as a client will see it'
-      help_usage 'fp showroom --project <slug>'
+      help_summary 'Preview the client showroom exactly as a client will see it, and manage its media'
+      help_usage 'fp showroom --project <slug>',
+                 'fp showroom media --project <slug>',
+                 'fp showroom media add <file> --project <slug> [--surface <key>] [--caption "..."] [--position N]',
+                 'fp showroom media add <image> --project <slug> --surface <key> --icon',
+                 'fp showroom media edit <id> --project <slug> [--caption "..."] [--position N]',
+                 'fp showroom media remove <id> --project <slug> [--yes]'
       help_flag :project, 'Project slug (falls back to .featureparity.yml)'
+      help_flag :surface, "media add: the surface whose card shows it (omit for the project gallery)"
+      help_flag :caption, 'media add/edit: text shown under the image or video (edit: empty clears)'
+      help_flag :position, 'media add/edit: slot within its card or the gallery, 1 is first; others shift (edit: empty moves it last)'
+      help_flag :yes, 'media remove: skip the typed-filename confirmation'
       help_example 'fp showroom --project stowzilla'
-      help_note "Prints the welcome note and each surface's card, then the surfaces that are NOT shown and why.\n" \
+      help_example 'fp showroom media add e2e/checkout.webm --project stowzilla --surface web --caption "Checking out"'
+      help_example 'fp showroom media add overview.png --project stowzilla --position 1'
+      help_example 'fp showroom media add app-icon.png --project stowzilla --surface ios --icon'
+      help_example 'fp showroom media edit <id> --project stowzilla --caption ""'
+      help_example 'fp showroom media remove <id> --project stowzilla --yes'
+      help_note "Prints the welcome note, the gallery, and each surface's card, then the surfaces that are NOT shown and why.\n" \
                 "Write the content with `fp projects edit --showroom-welcome` and `fp surfaces edit --showroom-*`.\n" \
+                "Media: png, jpg, gif, webp, mp4, webm, mov; max 100 MB. SVG and PDF are refused.\n" \
                 'The share link is reported as unknown: only a person can see or change it.'
       def run(args)
+        if args.first == 'media'
+          return ShowroomMedia.new(client: client, output: output, config: config).run(args.drop(1))
+        end
+
         opts, = parse_flags(args)
         require_project!(opts)
 
@@ -46,15 +69,16 @@ module Fp
 
       private
 
-      # Surfaces with neither a link nor instructions. The showroom payload leaves them
-      # out, so they are read from the surface list instead.
+      # Surfaces with no link, no instructions, and no media. The showroom payload leaves
+      # them out (and includes a media-only surface), so whatever the payload doesn't
+      # carry is hidden; they are read from the surface list.
       def hidden_surfaces(project_id, shown_ids)
         result = client.list_surfaces(project_id)
         return [] unless result[:ok]
 
         (result[:data]['surfaces'] || []).reject { |surface| shown_ids.include?(surface['id']) }.map do |surface|
           { 'key' => surface['key'], 'name' => surface['name'], 'kind' => surface['kind'],
-            'reason' => 'no showroom link or instructions' }
+            'reason' => 'no showroom link or instructions, and no media' }
         end
       end
 
@@ -88,9 +112,16 @@ module Fp
         end
         puts
 
+        gallery = showroom['gallery'] || []
+        unless gallery.empty?
+          puts "Gallery (#{media_summary(gallery)}):"
+          print_media(gallery, indent: '  ')
+          puts
+        end
+
         surfaces = showroom['surfaces'] || []
         if surfaces.empty?
-          puts 'Surfaces shown: none. The client sees only the welcome note.'
+          puts "Surfaces shown: none. The client sees only the welcome note#{gallery.empty? ? '' : ' and the gallery'}."
         else
           puts "Surfaces shown (#{surfaces.size}):"
           surfaces.each { |surface| print_card(surface) }
@@ -104,6 +135,7 @@ module Fp
           end
           puts "  Add one with: fp surfaces edit <key> --project #{project} --showroom-url ... " \
                '--showroom-instructions-file ...'
+          puts "  or: fp showroom media add <file> --project #{project} --surface <key>"
         end
 
         puts
@@ -130,6 +162,29 @@ module Fp
         else
           puts '    Instructions: (none)'
         end
+        media = surface['media'] || []
+        if media.empty?
+          puts '    Media:        (none)'
+        else
+          puts "    Media:        #{media_summary(media)}"
+          print_media(media, indent: '      ')
+        end
+      end
+
+      # "2 images, 1 video"
+      def media_summary(media)
+        counts = media.group_by { |item| item['media_kind'] == 'video' ? 'video' : 'image' }
+        %w[image video].filter_map do |kind|
+          count = counts.fetch(kind, []).size
+          "#{count} #{kind}#{count == 1 ? '' : 's'}" if count.positive?
+        end.join(', ')
+      end
+
+      def print_media(media, indent:)
+        media.each do |item|
+          caption = text_or_nil(item['caption'])
+          puts "#{indent}- #{item['media_kind'] || 'image'}: #{caption || '(no caption)'}"
+        end
       end
 
       def text_or_nil(value)

data/lib/fp/commands/showroom_media.rb

@@ -0,0 +1,366 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'attach'
+
+module Fp
+  module Commands
+    # fp showroom media [--project <slug>]                        - list the showroom's media
+    # fp showroom media add <file> [--surface <key>] [--caption] [--position N]
+    # fp showroom media add <image> --surface <key> --icon         - set the surface's icon
+    # fp showroom media edit <id> [--caption "..."] [--position N]
+    # fp showroom media remove <id> [--yes]
+    #
+    # Plenty of clients never open the demo, so the showroom can show them the thing
+    # instead: screenshots or a short clip on a surface's card, or in the project gallery
+    # under the welcome note (no --surface). The agent that ran the e2e suite already has
+    # the captures, so it puts them there rather than leaving a human to re-upload them.
+    #
+    # Dispatched from `fp showroom media ...`; its help lives on `fp showroom --help`.
+    # Uploads reuse attach's flow (presign, PUT the bytes, confirm) and its visual file
+    # types — images and videos only. SVG can carry script and PDFs don't render inline,
+    # so both are refused before anything is sent.
+    #
+    # `--icon` (Fizzy #1499) makes the image the surface's own icon in place of the
+    # built-in platform logo: one per surface, a new one replaces the old, and removing
+    # it brings the built-in logo back.
+    class ShowroomMedia < Base
+      CONTENT_TYPES = Attach::CONTENT_TYPES.slice(*Attach::VISUAL_EXTENSIONS).freeze
+      MAX_FILE_SIZE = Attach::MAX_FILE_SIZE
+      MAX_CAPTION_LENGTH = 500
+      ICON_EXTENSIONS = %w[png jpg jpeg gif webp].freeze
+      MAX_ICON_SIZE = 5 * 1024 * 1024
+
+      LIST_FLAGS = { project: :string }.freeze
+      ADD_FLAGS = { project: :string, surface: :string, caption: :string, position: :string, icon: :boolean }.freeze
+      EDIT_FLAGS = { project: :string, caption: :string, position: :string }.freeze
+      REMOVE_FLAGS = { project: :string, yes: :boolean }.freeze
+
+      def run(args)
+        case args.first
+        when 'add'
+          add(args[1..])
+        when 'edit'
+          edit(args[1..])
+        when 'remove', 'rm', 'delete'
+          remove(args[1..])
+        else
+          list(args)
+        end
+      end
+
+      private
+
+      # Gallery first, then each surface's media in the order a client sees the cards.
+      def list(args)
+        opts, = parse_flags(args, LIST_FLAGS)
+        require_project!(opts)
+        project_id = resolve_project_id(opts[:project])
+
+        media = fetch!(client.list_showroom_media(project_id))['media'] || []
+        groups = group_media(media, surfaces_for(project_id))
+
+        flat = groups.flat_map do |group|
+          group[:items].map { |item| item.merge('surface_key' => group[:key]) }
+        end
+
+        output.success({ media: flat, project: opts[:project] }) do
+          if media.empty?
+            puts "No showroom media in project '#{opts[:project]}'."
+            puts "Add some with: fp showroom media add <file> --project #{opts[:project]} [--surface <key>]"
+          else
+            puts "Showroom media for '#{opts[:project]}' (#{media.size}):"
+            groups.each do |group|
+              puts
+              puts "#{group[:title]} (#{group[:items].size}):"
+              group[:items].each { |item| print_item_line(item) }
+            end
+          end
+        end
+      end
+
+      def add(args)
+        opts, positional = parse_flags(args, ADD_FLAGS)
+        path = positional.first
+        if path.nil? || path.strip.empty?
+          output.error('Usage: fp showroom media add <file> --project <slug> [--surface <key>] ' \
+                       '[--caption "..."] [--position N]')
+          exit 1
+        end
+
+        # Everything that can be checked locally is checked before a byte is sent.
+        file = prepare_file!(path)
+        check_icon!(file, opts) if opts[:icon]
+        caption = flag_text(opts[:caption]).strip if opts.key?(:caption)
+        caption = nil if caption&.empty?
+        check_caption!(caption) if caption
+        position = position!(opts[:position], clear: nil) if opts.key?(:position)
+        if opts.key?(:surface) && flag_text(opts[:surface]).strip.empty?
+          output.error('--surface needs a surface key. Omit it to add to the project gallery.')
+          exit 1
+        end
+
+        require_project!(opts)
+        project_id = resolve_project_id(opts[:project])
+        surface = opts[:surface] ? find_surface!(project_id, opts[:surface]) : nil
+        purpose = opts[:icon] ? 'icon' : nil
+
+        presign = fetch!(client.presign_showroom_media(
+                           project_id,
+                           filename: file[:filename], content_type: file[:content_type],
+                           size_bytes: file[:size], surface_id: surface&.dig('id'), purpose: purpose
+                         ), prefix: 'Failed to get upload URL')['presign'] || {}
+
+        uploaded = client.upload_to_presigned_url(presign['upload_url'], file[:path], file[:content_type])
+        fetch!(uploaded, prefix: 'Upload failed')
+
+        item = fetch!(client.create_showroom_media(
+                        project_id,
+                        media_id: presign['media_id'], s3_key: presign['s3_key'],
+                        filename: file[:filename], content_type: file[:content_type], size_bytes: file[:size],
+                        surface_id: surface&.dig('id'), caption: caption, position: position, purpose: purpose
+                      ), prefix: 'Failed to confirm upload')['media'] || {}
+
+        where = surface ? "surface '#{surface['key']}'" : 'the project gallery'
+        output.success({ media: item, surface: surface&.dig('key'), project: opts[:project] }) do
+          if purpose
+            puts "Set #{file[:filename]} as the icon for #{where} in project '#{opts[:project]}'."
+            puts "Remove it to go back to the built-in logo: fp showroom media remove #{item['id']} " \
+                 "--project #{opts[:project]}"
+          else
+            puts "Added #{file[:filename]} to #{where} in project '#{opts[:project]}'."
+            print_item_detail(item)
+          end
+        end
+      end
+
+      def edit(args)
+        opts, positional = parse_flags(args, EDIT_FLAGS)
+        media_id = positional.first
+        if media_id.nil? || media_id.strip.empty?
+          output.error('Usage: fp showroom media edit <id> --project <slug> [--caption "..."] [--position N]')
+          exit 1
+        end
+
+        # Only what was passed is sent. Empty caption clears it. Positions are kept dense
+        # (1..n) per card or gallery: N inserts at slot N and shifts the rest, and an empty
+        # value — sent as 0, since the API types it as an integer — moves the item to the end.
+        params = {}
+        if opts.key?(:caption)
+          params[:caption] = flag_text(opts[:caption]).strip
+          check_caption!(params[:caption])
+        end
+        params[:position] = position!(opts[:position], clear: 0) if opts.key?(:position)
+
+        if params.empty?
+          output.error('Nothing to change. Pass --caption and/or --position (an empty value clears either).')
+          exit 1
+        end
+
+        require_project!(opts)
+        project_id = resolve_project_id(opts[:project])
+        item = fetch!(client.update_showroom_media(project_id, media_id, params))['media'] || {}
+
+        output.success({ media: item, project: opts[:project] }) do
+          puts "Updated showroom media #{media_id} in project '#{opts[:project]}'."
+          print_item_detail(item)
+        end
+      end
+
+      def remove(args)
+        opts, positional = parse_flags(args, REMOVE_FLAGS)
+        media_id = positional.first
+        if media_id.nil? || media_id.strip.empty?
+          output.error('Usage: fp showroom media remove <id> --project <slug> [--yes]')
+          exit 1
+        end
+
+        require_project!(opts)
+        project_id = resolve_project_id(opts[:project])
+
+        # Read it first: the confirmation names the file, and an unknown id fails here
+        # rather than as a bare 404 from the delete.
+        media = fetch!(client.list_showroom_media(project_id))['media'] || []
+        item = media.find { |m| m['id'] == media_id }
+        unless item
+          output.error("Showroom media '#{media_id}' not found in project '#{opts[:project]}'. " \
+                       "List it with: fp showroom media --project #{opts[:project]}", status: 404)
+          exit 1
+        end
+
+        confirm_remove!(item, opts)
+        fetch!(client.delete_showroom_media(project_id, media_id), prefix: 'Failed to remove showroom media')
+
+        output.success({ deleted: true, media: { 'id' => media_id, 'filename' => item['filename'] },
+                         project: opts[:project] }) do
+          puts "Removed #{item['filename']} (#{media_id}) from the showroom of project '#{opts[:project]}'."
+        end
+      end
+
+      # Same guard as `fp surfaces delete`: --yes skips the prompt, an interactive
+      # terminal types the filename back, and anything else is refused.
+      def confirm_remove!(item, opts)
+        return if opts[:yes]
+
+        unless interactive?
+          output.error("Refusing to remove '#{item['filename']}' without confirmation. " \
+                       'Re-run with --yes to confirm from a non-interactive session.')
+          exit 1
+        end
+
+        warn "This will remove '#{item['filename']}' from the showroom of project '#{opts[:project]}'. " \
+             'Clients stop seeing it at once.'
+        $stderr.print "Type '#{item['filename']}' to confirm: "
+        $stderr.flush
+
+        typed = $stdin.gets&.strip
+        return if typed == item['filename']
+
+        output.error('Aborted. The filename did not match; nothing was removed.')
+        exit 1
+      end
+
+      def interactive?
+        $stdin.respond_to?(:tty?) && $stdin.tty?
+      end
+
+      # { path:, filename:, content_type:, size: }, or exit with the reason it can't go up.
+      def prepare_file!(path)
+        unless File.file?(path)
+          output.error("File not found: #{path}")
+          exit 1
+        end
+
+        filename = File.basename(path)
+        extension = File.extname(filename).delete('.').downcase
+        content_type = CONTENT_TYPES[extension]
+        unless content_type
+          why = extension == 'svg' ? ' (SVG can carry script)' : ''
+          output.error("Unsupported file type: .#{extension}#{why}. The showroom takes images " \
+                       "(png, jpg, jpeg, gif, webp) and videos (mp4, webm, mov) only.")
+          exit 1
+        end
+
+        size = File.size(path)
+        if size.zero?
+          output.error("File is empty: #{path}")
+          exit 1
+        end
+        if size > MAX_FILE_SIZE
+          output.error("File too large: #{format_size(size)} (max #{format_size(MAX_FILE_SIZE)})")
+          exit 1
+        end
+
+        { path: path, filename: filename, content_type: content_type, size: size }
+      end
+
+      # An icon is a still picture on one surface, with nothing to caption or order.
+      def check_icon!(file, opts)
+        problem =
+          if flag_text(opts[:surface]).strip.empty? then '--icon needs --surface <key>: an icon belongs to a surface.'
+          elsif opts.key?(:caption) || opts.key?(:position) then '--icon takes no --caption or --position.'
+          elsif !ICON_EXTENSIONS.include?(File.extname(file[:filename]).delete('.').downcase)
+            'An icon must be an image (png, jpg, jpeg, gif, webp).'
+          elsif file[:size] > MAX_ICON_SIZE
+            "Icon too large: #{format_size(file[:size])} (max #{format_size(MAX_ICON_SIZE)})"
+          end
+        return unless problem
+
+        output.error(problem)
+        exit 1
+      end
+
+      def check_caption!(caption)
+        return if caption.length <= MAX_CAPTION_LENGTH
+
+        output.error("--caption is #{caption.length} characters; the limit is #{MAX_CAPTION_LENGTH}.")
+        exit 1
+      end
+
+      # 1 is first. An empty value returns `clear` (nil on add — it goes at the end
+      # anyway — and 0 on edit, which moves it to the end); anything else must be a whole
+      # number of 1 or more.
+      def position!(value, clear:)
+        text = flag_text(value).strip
+        return clear if text.empty?
+
+        position = Integer(text, 10, exception: false)
+        return position if position&.positive?
+
+        output.error("Invalid --position '#{text}'. Must be a whole number of 1 or more; " \
+                     'pass an empty value to clear it.')
+        exit 1
+      end
+
+      # A string flag given with no value parses as `true`; treat that as empty.
+      def flag_text(value)
+        value == true ? '' : value.to_s
+      end
+
+      def surfaces_for(project_id)
+        result = client.list_surfaces(project_id)
+        result[:ok] ? (result[:data]['surfaces'] || []) : []
+      end
+
+      def find_surface!(project_id, key)
+        fetch!(client.find_surface_by_key(project_id, key))['surface']
+      end
+
+      # [{ title:, key:, items: }] — the gallery, then each surface with media in showroom
+      # order (placed surfaces lowest first, then by name, as Surface#showroom_sort_key
+      # does). Within a group the server's order stands: it already sorts by position.
+      def group_media(media, surfaces)
+        groups = []
+        gallery = media.select { |m| m['surface_id'].to_s.empty? }
+        groups << { title: 'Gallery (under the welcome note)', key: nil, items: gallery } unless gallery.empty?
+
+        by_surface = media.reject { |m| m['surface_id'].to_s.empty? }.group_by { |m| m['surface_id'] }
+        surfaces.sort_by { |s| surface_sort_key(s) }.each do |surface|
+          items = by_surface.delete(surface['id'])
+          next unless items
+
+          groups << { title: "#{surface['name'] || surface['key']} (#{surface['key']})", key: surface['key'],
+                      items: items }
+        end
+        by_surface.each do |surface_id, items|
+          groups << { title: "Unknown surface #{surface_id}", key: nil, items: items }
+        end
+        groups
+      end
+
+      def surface_sort_key(surface)
+        position = surface['showroom_position'].to_i
+        position = nil if position < 1
+        [position ? 0 : 1, position || 0, surface['name'].to_s.downcase, surface['id'].to_s]
+      end
+
+      def print_item_line(item)
+        position = item['position'].to_i.positive? ? "##{item['position'].to_i}" : '-'
+        position = 'icon' if item['purpose'] == 'icon'
+        caption = item['caption'].to_s.strip
+        line = "  #{item['id']}  #{position.ljust(3)}  #{item['media_kind'].to_s.ljust(5)}  #{item['filename']}"
+        line += "  \"#{caption}\"" unless caption.empty?
+        puts line
+      end
+
+      def print_item_detail(item)
+        puts
+        puts "  ID:       #{item['id']}"
+        puts "  Kind:     #{item['media_kind']} (#{item['content_type']})"
+        puts "  File:     #{item['filename']}#{item['size_bytes'] ? " (#{format_size(item['size_bytes'].to_i)})" : ''}"
+        caption = item['caption'].to_s.strip
+        puts "  Caption:  #{caption.empty? ? '(none)' : caption}"
+        position = item['position'].to_i
+        puts "  Position: #{position.positive? ? position : '(last)'}"
+      end
+
+      # The response data, or exit with the API's error.
+      def fetch!(result, prefix: nil)
+        return result[:data] || {} if result[:ok]
+
+        output.error([prefix, result[:error]].compact.join(': '), status: result[:status])
+        exit 1
+      end
+    end
+  end
+end

data/lib/fp/commands/surfaces.rb

@@ -39,7 +39,8 @@ module Fp
         showroom_url: :string,
         showroom_label: :string,
         showroom_instructions: :string,
-        showroom_instructions_file: :string
+        showroom_instructions_file: :string,
+        showroom_position: :string
       }.freeze
 
       EDIT_FLAGS = ADD_FLAGS.merge(key: :string).merge(SHOWROOM_FLAGS).freeze
@@ -68,11 +69,13 @@ module Fp
       help_flag :showroom_label, 'Client showroom card: the button text for that link (edit)'
       help_flag :showroom_instructions, 'Client showroom card: how to sign in and try the surface (edit)'
       help_flag :showroom_instructions_file, 'Read --showroom-instructions from a file (multi-line)'
+      help_flag :showroom_position, 'Client showroom order: 1 is first; empty clears (unplaced surfaces follow, A-Z) (edit)'
       help_flag :yes, 'Skip the typed-key confirmation on delete'
       help_example 'fp surfaces --project stowzilla'
       help_example 'fp surfaces add customer_android --project stowzilla --kind android --repo stowzilla/customer-android'
       help_example 'fp surfaces delete web --project stowzilla --yes'
       help_example 'fp surfaces edit web --project stowzilla --showroom-url https://dev.example.com --showroom-instructions-file docs/showroom/web.txt'
+      help_example 'fp surfaces edit web --project stowzilla --showroom-position 1'
 
       def run(args)
         # Subcommand dispatch. Bare `fp surfaces --project X` stays a list, so existing
@@ -205,7 +208,8 @@ module Fp
           output.error('Usage: fp surfaces edit <key> --project <slug> [--name "Name"] [--kind ...] ' \
                        '[--audience ...] [--repo org/repo] [--default-branch main] [--key new_key] ' \
                        '[--showroom-url URL] [--showroom-label "..."] ' \
-                       '[--showroom-instructions "..." | --showroom-instructions-file PATH]')
+                       '[--showroom-instructions "..." | --showroom-instructions-file PATH] ' \
+                       '[--showroom-position N]')
           exit 1
         end
 
@@ -271,6 +275,8 @@ module Fp
                                                            '--showroom-instructions-file')
         end
 
+        params[:showroom_position] = showroom_position!(opts[:showroom_position]) if opts.key?(:showroom_position)
+
         url = params[:showroom_url]
         if url && !url.empty? && url !~ %r{\Ahttps?://\S+\z}i
           output.error("Invalid --showroom-url '#{url}'. Must be an http:// or https:// link; " \
@@ -281,6 +287,21 @@ module Fp
         params
       end
 
+      # 1 is first. Empty clears it, sent as 0 because the API types the field as an
+      # integer (null would be refused at the gateway); the surface then follows the
+      # placed ones alphabetically.
+      def showroom_position!(value)
+        text = flag_text(value).strip
+        return 0 if text.empty?
+
+        position = Integer(text, 10, exception: false)
+        return position if position&.positive?
+
+        output.error("Invalid --showroom-position '#{text}'. Must be a whole number of 1 or more; " \
+                     'pass an empty value to clear it.')
+        exit 1
+      end
+
       # A string flag given with no value parses as `true`; treat that as "clear it",
       # the same as an explicit empty string.
       def flag_text(value)
@@ -417,9 +438,14 @@ module Fp
         instructions = text_or_nil(surface['showroom_instructions'])
         shown = !(url.nil? && instructions.nil?)
 
+        position = surface['showroom_position']
+        position = nil if position.to_s.strip.empty? || position.to_i < 1
+
         puts "#{indent}Showroom: #{shown ? 'shown to clients' : 'hidden (no link or instructions)'}"
         return unless shown
 
+        puts "#{indent}  Position:     #{position ? position.to_i : '(not set; ordered by name)'}"
+
         puts "#{indent}  Link:         #{url || '(none)'}#{label ? " [#{label}]" : ''}"
         puts "#{indent}  Instructions: #{instructions ? '' : '(none)'}"
         instructions&.each_line { |line| puts "#{indent}    #{line.rstrip}" }

data/lib/fp/commands.rb

@@ -4,6 +4,7 @@ require_relative 'commands/base'
 require_relative 'commands/projects'
 require_relative 'commands/surfaces'
 require_relative 'commands/showroom'
+require_relative 'commands/showroom_media'
 require_relative 'commands/list'
 require_relative 'commands/show'
 require_relative 'commands/propose'

data/lib/fp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fp
-  VERSION = '0.0.22'
+  VERSION = '0.0.24'
 end

data/skills/fp/SKILL.md

@@ -351,14 +351,30 @@ fp surfaces edit web --project X \
   --showroom-url https://dev.example.com \
   --showroom-label "Open the web app" \
   --showroom-instructions-file docs/showroom/web.txt
+fp showroom media add e2e/results/checkout.webm --project X --surface web \
+  --caption "Checking out with a saved card"       # on the web card
+fp showroom media add docs/showroom/overview.png --project X   # no --surface: the gallery
 ```
 
 Write instructions a non-technical reader can follow: where to click, which account to
 sign in as (a dedicated demo account, not the one your e2e suite mutates), what data is
 already there to look at, and one or two things worth trying. Keep the file in the repo
 (`docs/showroom/<surface>.txt`) so the next deploy can re-send it. A surface with neither
-a link nor instructions is not shown; clear both to take a card down. Feedback and the
-share link are human-only, so after writing the content tell a person it's ready.
+a link nor instructions is not shown; clear both to take a card down. Cards appear in the
+team's chosen order (`--showroom-position 1` is first); surfaces with no position follow,
+alphabetically.
+
+Plenty of clients never open the demo, so show them the thing: put a screenshot or a
+short clip of each surface on its card, and an overview in the gallery under the welcome
+note. The captures your e2e run already recorded are usually the right ones — pick the
+ones that show a finished flow, not a test fixture, and caption them in the client's
+words. Images and video only (png, jpg, gif, webp, mp4, webm, mov; 100 MB); SVG and PDF
+are refused. `fp showroom media` lists what's there with ids, `fp showroom media edit
+<id> --caption ... --position N` reorders or rewords (`--position N` takes slot N and
+shifts the rest; an empty value clears the caption or moves the item last), and `fp showroom
+media remove <id> --yes` takes one down. A surface with media but no link is still shown.
+Feedback and the share link are human-only, so after writing the content tell a person
+it's ready.
 
 ### Repo-local config (`.featureparity.yml`)
 
@@ -446,6 +462,8 @@ not as the fix — you still write the proposal.
 | Preview the client showroom | `fp showroom --project X` |
 | Write a surface's showroom card | `fp surfaces edit <key> --project X --showroom-url ... --showroom-instructions-file ...` |
 | Write the showroom welcome | `fp projects edit <slug> --showroom-welcome-file ...` |
+| Add a screenshot/video to the showroom | `fp showroom media add <file> --project X [--surface <key>] [--caption "..."]` |
+| List / edit / remove showroom media | `fp showroom media --project X`, `fp showroom media edit <id> ...`, `fp showroom media remove <id> --yes` |
 
 All commands support `--json` for machine-readable output.
 

data/skills/fp/references/cli.md

@@ -62,7 +62,7 @@ fp surfaces --project stowzilla --json
 fp surfaces show <key> --project stowzilla
 fp surfaces add <key> --project stowzilla [--name "..."] [--kind api|web|android|ios|other] [--audience ...] [--repo org/repo] [--default-branch main]
 fp surfaces edit <key> --project stowzilla [--name "..."] [--kind ...] [--audience ...] [--repo ...] [--default-branch ...] [--key new_key]
-fp surfaces edit <key> --project stowzilla [--showroom-url URL] [--showroom-label "..."] [--showroom-instructions "..." | --showroom-instructions-file PATH]
+fp surfaces edit <key> --project stowzilla [--showroom-url URL] [--showroom-label "..."] [--showroom-instructions "..." | --showroom-instructions-file PATH] [--showroom-position N]
 fp surfaces delete <key> --project stowzilla [--yes]
 ```
 
@@ -78,13 +78,14 @@ one rather than working around it.
 ### fp showroom
 
 The client showroom is the one page a client of the project sees: the project's
-welcome note, then a card per surface with a link, a button label, and instructions
-for signing in and trying it. The team's agents keep that content; this command
+welcome note and a gallery of screenshots or videos under it, then a card per surface
+with a link, a button label, instructions for signing in and trying it, and its own
+media. The team's agents keep that content; this command
 shows the result.
 
 ```bash
 fp showroom --project stowzilla          # what a client sees, plus which surfaces are hidden and why
-fp showroom --project stowzilla --json   # { showroom, hidden, share_link }
+fp showroom --project stowzilla --json   # { showroom, hidden, share_link }; showroom.gallery and each surface's media
 ```
 
 Writing the content:
@@ -97,10 +98,35 @@ fp surfaces edit web --project stowzilla \
   --showroom-label "Open the web app" \
   --showroom-instructions-file docs/showroom/web.txt
 fp surfaces edit ios --project stowzilla --showroom-url "" --showroom-instructions ""   # take the card down
+fp surfaces edit web --project stowzilla --showroom-position 1    # clients see web first
+fp surfaces edit web --project stowzilla --showroom-position ""   # back to alphabetical
 ```
 
-A surface is on the showroom once it has a link or instructions, and leaves it when
-both are blank; there is no separate on/off switch, so `fp showroom` lists the hidden
+Media — screenshots and videos on a surface's card, or in the project gallery under the
+welcome note when `--surface` is omitted:
+
+```bash
+fp showroom media --project stowzilla             # gallery, then each surface in showroom order: id, kind, file, caption, position
+fp showroom media --project stowzilla --json      # { media: [...each with surface_key (null = gallery)], project }
+fp showroom media add e2e/results/checkout.webm --project stowzilla --surface web \
+  --caption "Checking out with a saved card" --position 1
+fp showroom media add docs/showroom/overview.png --project stowzilla    # the gallery
+fp showroom media edit <id> --project stowzilla --caption "New words" --position 2
+fp showroom media edit <id> --project stowzilla --caption "" --position ""   # clear the caption, move it last
+fp showroom media remove <id> --project stowzilla --yes
+```
+
+Accepted: png, jpg/jpeg, gif, webp, mp4, webm, mov, up to 100 MB. Anything else — SVG
+(it can carry script) and PDF included — is refused with the reason before anything is
+sent, as is a `--position` that isn't a whole number of 1 or more. Within a card or the
+gallery, positions run 1..n with no gaps: `--position N` puts the item at slot N and
+shifts the others, an empty `--position` moves it to the end, and `add` without one
+appends. `remove`
+asks you to type the filename back in a terminal and refuses non-interactively without
+`--yes`.
+
+A surface is on the showroom once it has a link, instructions, or media, and leaves it
+when all three are empty; there is no separate on/off switch, so `fp showroom` lists the hidden
 surfaces so a card that dropped out is noticed. Links must be `http://` or `https://`
 (the CLI checks before sending). The `-file` variants are for anything longer than a
 line: the showroom keeps line breaks, so write real paragraphs. Only the flags you pass

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: featureparity
 version: !ruby/object:Gem::Version
-  version: 0.0.22
+  version: 0.0.24
 platform: ruby
 authors:
 - Stowzilla
@@ -120,6 +120,7 @@ files:
 - lib/fp/commands/setup.rb
 - lib/fp/commands/show.rb
 - lib/fp/commands/showroom.rb
+- lib/fp/commands/showroom_media.rb
 - lib/fp/commands/surfaces.rb
 - lib/fp/commands/version.rb
 - lib/fp/commands/whoami.rb