vizcore 0.1.0 → 1.0.0

data/lib/vizcore/server/gallery_app.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+require "rack"
+require_relative "../dsl"
+require_relative "gallery_page"
+
+module Vizcore
+  module Server
+    # Rack app that lists bundled example scenes and their launch commands.
+    class GalleryApp
+      POSTER_PATH = "/assets/vizcore-poster.png"
+      DESCRIPTIONS = {
+        "basic.rb" => "Single wireframe cube starter.",
+        "intro_drop.rb" => "Beat-triggered intro to drop transition.",
+        "file_audio_demo.rb" => "File-audio walkthrough with layered visuals.",
+        "complex_audio_showcase.rb" => "Dense multi-scene showcase for audio-reactive layers.",
+        "rhythm_geometry.rb" => "Morphing geometric pattern driven by rhythm and bands.",
+        "ruby_crystal_show.rb" => "Ruby-themed crystal, particles, and text showcase.",
+        "parser_visualizer.rb" => "Parser-themed token, AST, and reduce visual sketch.",
+        "live_coding_minimal.rb" => "Tiny live-coding scene with a pulsing blob.",
+        "club_intro_drop.rb" => "Intro, build, and drop flow for rhythmic file input.",
+        "shader_playground.rb" => "Focused liquid shader scene with mapped params.",
+        "audio_inspector.rb" => "Audio feature visualization scene with bars and blob.",
+        "readme_demo.rb" => "Minimal beat pulse to ring radius demo.",
+        "midi_scene_switch.rb" => "MIDI note and CC driven scene switching.",
+        "midi_controller_show.rb" => "MIDI pads switch scenes and knobs drive global shader uniforms.",
+        "kansai_rubykaigi_visual.rb" => "Event showcase with ruby crystal, water ripple, and Kyoto-inspired pattern.",
+        "custom_shader.rb" => "Custom GLSL fragment shader example.",
+        "unyo_liquid.rb" => "Organic liquid wobble scene with FFT blobs and particles."
+      }.freeze
+      FILE_AUDIO_EXAMPLES = %w[
+        file_audio_demo.rb
+        complex_audio_showcase.rb
+        rhythm_geometry.rb
+        ruby_crystal_show.rb
+        parser_visualizer.rb
+        club_intro_drop.rb
+        audio_inspector.rb
+        readme_demo.rb
+        kansai_rubykaigi_visual.rb
+      ].freeze
+      ORDER = DESCRIPTIONS.keys.freeze
+
+      # @param examples_root [Pathname, String]
+      # @param docs_assets_root [Pathname, String]
+      def initialize(
+        examples_root: Vizcore.root.join("examples"),
+        docs_assets_root: Vizcore.root.join("docs", "assets")
+      )
+        @examples_root = Pathname.new(examples_root.to_s).expand_path
+        @docs_assets_root = Pathname.new(docs_assets_root.to_s).expand_path
+      end
+
+      # @param env [Hash]
+      # @return [Array(Integer, Hash, Array<String>)]
+      def call(env)
+        request = Rack::Request.new(env)
+
+        return html_response if request.path_info == "/"
+        return json_response if request.path_info == "/examples.json"
+        return poster_response if request.path_info == POSTER_PATH
+        return health_response if request.path_info == "/health"
+
+        not_found_response
+      end
+
+      private
+
+      def html_response
+        body = GalleryPage.new(entries: examples, poster_path: POSTER_PATH).render
+        response(body, content_type: "text/html; charset=utf-8")
+      end
+
+      def json_response
+        body = JSON.generate(examples: examples)
+        response(body, content_type: "application/json; charset=utf-8")
+      end
+
+      def health_response
+        body = JSON.generate(status: "ok", examples: examples.length)
+        response(body, content_type: "application/json; charset=utf-8")
+      end
+
+      def poster_response
+        path = @docs_assets_root.join("vizcore-poster.png")
+        return not_found_response unless path.file?
+
+        response(File.binread(path), content_type: "image/png")
+      end
+
+      def examples
+        example_paths.map { |path| example_payload(path) }
+      end
+
+      def example_paths
+        paths = @examples_root.children.select { |path| path.file? && path.extname == ".rb" }
+        paths.sort_by { |path| [ORDER.index(path.basename.to_s) || ORDER.length, path.basename.to_s] }
+      rescue Errno::ENOENT
+        []
+      end
+
+      def example_payload(path)
+        definition = Vizcore::DSL::Engine.load_file(path.to_s)
+        scenes = Array(definition[:scenes])
+        {
+          file: display_path(path),
+          title: path.basename(".rb").to_s.tr("_", " "),
+          description: DESCRIPTIONS.fetch(path.basename.to_s, "Vizcore example scene."),
+          scene_names: scenes.map { |scene| scene[:name].to_s },
+          layer_count: scenes.sum { |scene| Array(scene[:layers]).length },
+          command: launch_command(path),
+          audio_source: audio_source_for(path)
+        }
+      rescue StandardError => e
+        {
+          file: display_path(path),
+          title: path.basename(".rb").to_s.tr("_", " "),
+          description: "This example could not be inspected: #{e.message}",
+          scene_names: [],
+          layer_count: 0,
+          command: launch_command(path),
+          audio_source: audio_source_for(path)
+        }
+      end
+
+      def launch_command(path)
+        command = "vizcore start #{display_path(path)} --audio-source #{audio_source_for(path)}"
+        return command unless audio_source_for(path) == "file"
+
+        "#{command} --audio-file #{display_path(@examples_root.join('assets', 'complex_demo_loop.wav'))}"
+      end
+
+      def audio_source_for(path)
+        FILE_AUDIO_EXAMPLES.include?(path.basename.to_s) ? "file" : "dummy"
+      end
+
+      def display_path(path)
+        path = Pathname.new(path.to_s).expand_path
+        path.relative_path_from(Vizcore.root).to_s
+      rescue ArgumentError
+        path.to_s
+      end
+
+      def response(body, content_type:)
+        [200, { "content-type" => content_type, "content-length" => body.bytesize.to_s, "cache-control" => "no-store" }, [body]]
+      end
+
+      def not_found_response
+        [404, { "content-type" => "text/plain; charset=utf-8", "content-length" => "9" }, ["Not Found"]]
+      end
+    end
+  end
+end

data/lib/vizcore/server/gallery_page.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Vizcore
+  module Server
+    # Renders the browser HTML for the bundled example gallery.
+    class GalleryPage
+      # @param entries [Array<Hash>]
+      # @param poster_path [String]
+      def initialize(entries:, poster_path:)
+        @entries = entries
+        @poster_path = poster_path
+      end
+
+      # @return [String]
+      def render
+        cards = @entries.map { |entry| render_card(entry) }.join
+        <<~HTML
+          <!doctype html>
+          <html lang="en">
+          <head>
+            <meta charset="utf-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <title>Vizcore Example Gallery</title>
+            <style>#{css}</style>
+          </head>
+          <body>
+            <main>
+              <header class="header">
+                <img src="#{@poster_path}" alt="" class="poster">
+                <div>
+                  <p class="eyebrow">Vizcore Examples</p>
+                  <h1>Example Gallery</h1>
+                  <p class="lede">Bundled scenes with scene counts, layer counts, audio-source hints, and launch commands.</p>
+                </div>
+              </header>
+              <section class="grid" aria-label="Example scenes">
+                #{cards}
+              </section>
+            </main>
+          </body>
+          </html>
+        HTML
+      end
+
+      private
+
+      def render_card(entry)
+        scenes = entry.fetch(:scene_names).empty? ? "none" : entry.fetch(:scene_names).join(", ")
+        <<~HTML
+          <article class="card">
+            <div class="thumb"></div>
+            <div class="card-body">
+              <h2>#{escape(entry.fetch(:title))}</h2>
+              <p>#{escape(entry.fetch(:description))}</p>
+              <dl>
+                <div><dt>File</dt><dd>#{escape(entry.fetch(:file))}</dd></div>
+                <div><dt>Scenes</dt><dd>#{escape(scenes)}</dd></div>
+                <div><dt>Layers</dt><dd>#{entry.fetch(:layer_count)}</dd></div>
+                <div><dt>Audio</dt><dd>#{escape(entry.fetch(:audio_source))}</dd></div>
+              </dl>
+              <code>#{escape(entry.fetch(:command))}</code>
+            </div>
+          </article>
+        HTML
+      end
+
+      def css
+        <<~CSS
+          :root { color-scheme: dark; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #090b10; color: #ecf4ff; }
+          * { box-sizing: border-box; }
+          body { margin: 0; min-height: 100vh; background: #090b10; }
+          main { width: min(1180px, calc(100% - 32px)); margin: 0 auto; padding: 32px 0 48px; }
+          .header { display: grid; grid-template-columns: minmax(220px, 360px) 1fr; gap: 28px; align-items: end; margin-bottom: 28px; }
+          .poster { width: 100%; aspect-ratio: 16 / 9; object-fit: cover; border-radius: 8px; border: 1px solid rgba(255, 255, 255, 0.14); }
+          .eyebrow { margin: 0 0 8px; color: #7dd3fc; font-size: 13px; text-transform: uppercase; letter-spacing: 0; }
+          h1 { margin: 0; font-size: 42px; line-height: 1.05; letter-spacing: 0; }
+          .lede { max-width: 680px; margin: 14px 0 0; color: #b8c7d9; font-size: 17px; line-height: 1.55; }
+          .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(260px, 1fr)); gap: 16px; }
+          .card { overflow: hidden; border: 1px solid rgba(255, 255, 255, 0.12); border-radius: 8px; background: #111722; }
+          .thumb { height: 96px; background: url("#{@poster_path}") center / cover; border-bottom: 1px solid rgba(255, 255, 255, 0.1); }
+          .card-body { padding: 16px; }
+          h2 { margin: 0 0 8px; font-size: 20px; line-height: 1.2; letter-spacing: 0; }
+          p { margin: 0 0 14px; color: #bdcadb; line-height: 1.5; }
+          dl { display: grid; gap: 8px; margin: 0 0 14px; }
+          dl div { display: grid; grid-template-columns: 68px 1fr; gap: 10px; }
+          dt { color: #7dd3fc; font-size: 12px; text-transform: uppercase; }
+          dd { margin: 0; color: #dfe9f6; overflow-wrap: anywhere; }
+          code { display: block; min-height: 52px; padding: 10px; border-radius: 6px; background: #05070b; color: #b8f7d4; overflow-wrap: anywhere; line-height: 1.45; }
+          @media (max-width: 720px) { .header { grid-template-columns: 1fr; } h1 { font-size: 34px; } }
+        CSS
+      end
+
+      def escape(value)
+        CGI.escapeHTML(value.to_s)
+      end
+    end
+  end
+end

data/lib/vizcore/server/gallery_runner.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "puma"
+require_relative "../config"
+require_relative "gallery_app"
+
+module Vizcore
+  module Server
+    # Starts a small Rack/Puma server for the example gallery.
+    class GalleryRunner
+      DEFAULT_PORT = Config::DEFAULT_PORT + 1
+
+      # @param host [String]
+      # @param port [Integer]
+      # @param output [#puts]
+      def initialize(host: Config::DEFAULT_HOST, port: DEFAULT_PORT, output: $stdout)
+        @host = host
+        @port = Integer(port)
+        @output = output
+      end
+
+      # @return [void]
+      def run
+        server = Puma::Server.new(GalleryApp.new, nil, min_threads: 0, max_threads: 4)
+        server.add_tcp_listener(@host, @port)
+        server.run
+
+        @output.puts("Vizcore gallery: http://#{@host}:#{@port}")
+        @output.puts("Press Ctrl+C to stop.")
+        wait_for_interrupt
+      ensure
+        server&.stop(true)
+      end
+
+      private
+
+      def wait_for_interrupt
+        stop_requested = false
+        %w[INT TERM].each do |signal_name|
+          Signal.trap(signal_name) { stop_requested = true }
+        rescue ArgumentError
+          nil
+        end
+        sleep(0.1) until stop_requested
+      end
+    end
+  end
+end

data/lib/vizcore/server/rack_app.rb

@@ -3,6 +3,7 @@
 require "json"
 require "pathname"
 require "rack"
+require_relative "../control_preset"
 require_relative "websocket_handler"
 
 module Vizcore
@@ -10,6 +11,10 @@ module Vizcore
     # Rack app serving frontend assets, health endpoint, and WebSocket upgrade.
     class RackApp
       AUDIO_FILE_PATH = "/audio-file"
+      CONTROL_PATH = "/control"
+      CONTROL_PRESET_PATH = "/control-preset"
+      PLUGIN_ASSET_PREFIX = "/plugins/"
+      PROJECTOR_PATH = "/projector"
       RUNTIME_PATH = "/runtime"
 
       # @param frontend_root [Pathname]
@@ -17,12 +22,39 @@ module Vizcore
       # @param audio_source [Symbol, String, nil]
       # @param audio_file [String, Pathname, nil]
       # @param scene_names [Array<String, Symbol>, nil]
-      def initialize(frontend_root:, websocket_path: "/ws", audio_source: nil, audio_file: nil, scene_names: nil)
+      # @param tap_tempo_key [String, Symbol, nil]
+      # @param key_mappings [Array<Hash>, nil]
+      # @param globals [Hash, nil]
+      # @param control_preset [Hash, nil]
+      # @param control_preset_path [String, Pathname, nil]
+      # @param plugin_assets [Array<String, Pathname>, nil]
+      # @param projector_mode [Boolean]
+      def initialize(
+        frontend_root:,
+        websocket_path: "/ws",
+        audio_source: nil,
+        audio_file: nil,
+        scene_names: nil,
+        tap_tempo_key: nil,
+        key_mappings: nil,
+        globals: nil,
+        control_preset: nil,
+        control_preset_path: nil,
+        plugin_assets: nil,
+        projector_mode: false
+      )
         @frontend_root = frontend_root.expand_path
         @websocket_path = websocket_path
         @audio_source = audio_source&.to_sym
         @audio_file = audio_file ? Pathname.new(audio_file).expand_path : nil
         @scene_names = normalize_scene_names(scene_names)
+        @tap_tempo_key = normalize_tap_tempo_key(tap_tempo_key)
+        @key_mappings = normalize_key_mappings(key_mappings)
+        @globals = normalize_globals(globals)
+        @control_preset = normalize_control_preset(control_preset)
+        @control_preset_path = control_preset_path ? Pathname.new(control_preset_path).expand_path : nil
+        @plugin_assets = normalize_plugin_assets(plugin_assets)
+        @projector_mode = !!projector_mode
       end
 
       # @param env [Hash]
@@ -33,7 +65,12 @@ module Vizcore
         return WebSocketHandler.call(env) if request.path_info == @websocket_path
         return health_response if request.path_info == "/health"
         return runtime_response if request.path_info == RUNTIME_PATH
+        return control_preset_response(request) if request.path_info == CONTROL_PRESET_PATH
         return audio_file_response(request) if request.path_info == AUDIO_FILE_PATH
+        return plugin_asset_response(request.path_info) if request.path_info.start_with?(PLUGIN_ASSET_PREFIX)
+        return serve_index(display_mode: root_display_mode) if request.path_info == "/"
+        return serve_index(display_mode: "control") if request.path_info == CONTROL_PATH
+        return serve_index(display_mode: "projector") if request.path_info == PROJECTOR_PATH
 
         serve_static(request.path_info)
       end
@@ -51,7 +88,15 @@ module Vizcore
           audio_source: (@audio_source || :unknown).to_s,
           audio_file_name: nil,
           audio_file_url: nil,
-          scene_names: @scene_names
+          scene_names: @scene_names,
+          tap_tempo_key: @tap_tempo_key,
+          key_mappings: @key_mappings,
+          globals: @globals,
+          control_preset: @control_preset,
+          control_preset_writable: !!@control_preset_path,
+          control_preset_url: @control_preset_path ? CONTROL_PRESET_PATH : nil,
+          plugin_assets: @plugin_assets.map { |asset| asset.fetch(:url) },
+          projector_mode: @projector_mode
         }
 
         if audio_file_available?
@@ -85,16 +130,66 @@ module Vizcore
         [200, audio_headers(content_length: body.bytesize), [body]]
       end
 
+      def control_preset_response(request)
+        return not_found_response unless @control_preset_path
+        return method_not_allowed_response unless request.put? || request.post?
+
+        payload = JSON.parse(request.body.read)
+        @control_preset = Vizcore::ControlPreset.write(@control_preset_path, payload)
+        body = JSON.generate(status: "ok", control_preset: @control_preset)
+        [200, json_headers.merge("content-length" => body.bytesize.to_s), [body]]
+      rescue JSON::ParserError => e
+        body = JSON.generate(status: "error", error: "Invalid control preset JSON: #{e.message}")
+        [400, json_headers.merge("content-length" => body.bytesize.to_s), [body]]
+      rescue ArgumentError => e
+        body = JSON.generate(status: "error", error: e.message)
+        [400, json_headers.merge("content-length" => body.bytesize.to_s), [body]]
+      end
+
       def serve_static(path_info)
-        path = path_info == "/" ? "index.html" : path_info.delete_prefix("/")
+        path = path_info.delete_prefix("/")
         full_path = File.expand_path(path, @frontend_root.to_s)
 
         return not_found_response unless full_path.start_with?(@frontend_root.to_s)
         return not_found_response unless File.file?(full_path)
 
         body = File.binread(full_path)
+        static_response(body, content_type: Rack::Mime.mime_type(File.extname(full_path), "text/plain"))
+      end
+
+      def serve_index(display_mode:)
+        full_path = @frontend_root.join("index.html")
+        return not_found_response unless full_path.file?
+
+        body = File.binread(full_path)
+        body = body.gsub(
+          'data-projector-mode="false"',
+          "data-projector-mode=\"#{display_mode == 'projector' ? 'true' : 'false'}\""
+        )
+        body = body.gsub(
+          'data-display-mode="auto"',
+          "data-display-mode=\"#{display_mode}\""
+        )
+        body = inject_plugin_asset_scripts(body)
+        static_response(body, content_type: "text/html")
+      end
+
+      def plugin_asset_response(path_info)
+        asset = @plugin_assets.find { |entry| entry.fetch(:url) == path_info }
+        return not_found_response unless asset
+        return not_found_response unless asset.fetch(:path).file?
+
+        body = File.binread(asset.fetch(:path))
+        static_response(body, content_type: Rack::Mime.mime_type(asset.fetch(:path).extname, "text/javascript"))
+      end
+
+      def root_display_mode
+        @projector_mode ? "projector" : "auto"
+      end
+
+      def static_response(body, content_type:)
         headers = {
-          "content-type" => Rack::Mime.mime_type(File.extname(full_path), "text/plain"),
+          "content-type" => content_type,
           "content-length" => body.bytesize.to_s,
           "cache-control" => "no-store, max-age=0, must-revalidate"
         }
@@ -105,6 +200,10 @@ module Vizcore
         [404, text_headers.merge("content-length" => "9"), ["Not Found"]]
       end
 
+      def method_not_allowed_response
+        [405, text_headers.merge("allow" => "PUT, POST", "content-length" => "18"), ["Method Not Allowed"]]
+      end
+
       def text_headers
         { "content-type" => "text/plain; charset=utf-8" }
       end
@@ -137,6 +236,106 @@ module Vizcore
         []
       end
 
+      def normalize_tap_tempo_key(value)
+        key = value.to_s.strip.downcase
+        return nil if key.empty?
+
+        key
+      rescue StandardError
+        nil
+      end
+
+      def normalize_key_mappings(values)
+        Array(values).filter_map do |entry|
+          key = normalize_shortcut_key(entry[:key] || entry["key"])
+          action = entry[:action] || entry["action"]
+          next if key.empty? || !action.is_a?(Hash)
+
+          normalized_action = normalize_key_action(action)
+          next unless normalized_action
+
+          { key: key, action: normalized_action }
+        end
+      rescue StandardError
+        []
+      end
+
+      def normalize_shortcut_key(value)
+        raw = value.to_s
+        return "space" if raw == " "
+
+        key = raw.strip.downcase
+        key == "spacebar" ? "space" : key
+      end
+
+      def normalize_key_action(action)
+        type = (action[:type] || action["type"]).to_s.strip
+        case type
+        when "switch_scene"
+          scene = (action[:scene] || action["scene"]).to_s.strip
+          return nil if scene.empty?
+
+          { type: "switch_scene", scene: scene }
+        when "live_control"
+          control = (action[:control] || action["control"]).to_s.strip
+          return nil unless %w[blackout freeze].include?(control)
+
+          { type: "live_control", control: control }
+        end
+      end
+
+      def normalize_globals(values)
+        Hash(values || {}).each_with_object({}) do |(key, value), output|
+          name = key.to_s.strip
+          next if name.empty?
+
+          output[name] = value
+        end
+      rescue StandardError
+        {}
+      end
+
+      def normalize_control_preset(values)
+        preset = values.is_a?(Hash) ? values : {}
+        visual_settings = preset[:visual_settings] || preset["visual_settings"] || preset[:visualSettings] || preset["visualSettings"]
+        midi_learn_bindings = preset[:midi_learn_bindings] || preset["midi_learn_bindings"] || preset[:midiLearnBindings] || preset["midiLearnBindings"]
+
+        {}.tap do |payload|
+          payload["visual_settings"] = visual_settings if visual_settings.is_a?(Hash)
+          payload["midi_learn_bindings"] = midi_learn_bindings if midi_learn_bindings.is_a?(Hash)
+        end
+      rescue StandardError
+        {}
+      end
+
+      def normalize_plugin_assets(values)
+        Array(values).each_with_index.filter_map do |value, index|
+          raw_value = value.to_s.strip
+          next if raw_value.empty?
+
+          path = value.is_a?(Pathname) ? value.expand_path : Pathname.new(raw_value).expand_path
+          {
+            path: path,
+            url: "#{PLUGIN_ASSET_PREFIX}#{index}/#{rack_escape_path(path.basename.to_s)}"
+          }
+        end
+      rescue StandardError
+        []
+      end
+
+      def inject_plugin_asset_scripts(body)
+        return body if @plugin_assets.empty?
+
+        scripts = @plugin_assets.map do |asset|
+          %(<script type="module" src="#{asset.fetch(:url)}"></script>)
+        end.join("\n  ")
+        body.sub(%(<script type="module" src="/src/main.js?v=20260516d"></script>), "#{scripts}\n  \\0")
+      end
+
+      def rack_escape_path(value)
+        Rack::Utils.escape_path(value)
+      end
+
       def parse_byte_range(raw_range, file_size)
         range_value = raw_range.to_s.strip
         return nil if range_value.empty?