vizcore 1.1.0 → 1.2.0

data/lib/vizcore/cli/shader_template.rb

@@ -17,8 +17,13 @@ module Vizcore
         uniform float u_bass;
         uniform float u_mid;
         uniform float u_high;
+        uniform float u_bass_peak;
+        uniform float u_mid_peak;
+        uniform float u_high_peak;
         uniform float u_beat;
         uniform float u_beat_pulse;
+        uniform float u_beat_phase;
+        uniform float u_bar_phase;
         uniform float u_onset;
         uniform float u_kick;
         uniform float u_bpm;
@@ -29,9 +34,9 @@ module Vizcore
 
         void main() {
           vec2 uv = gl_FragCoord.xy / u_resolution.xy;
-          float wave = 0.5 + 0.5 * sin((uv.x + u_time * 0.12) * 12.0 + u_bass * 4.0);
+          float wave = 0.5 + 0.5 * sin((uv.x + u_time * 0.12 + u_bar_phase * 0.2) * 12.0 + u_bass * 4.0);
           vec3 color = mix(vec3(0.02, 0.06, 0.12), vec3(0.1, 0.75, 0.95), wave);
-          color += vec3(0.95, 0.16, 0.32) * (u_beat_pulse * 0.35 + u_onset * 0.2 + u_kick * 0.25 + u_high * 0.2);
+          color += vec3(0.95, 0.16, 0.32) * (u_beat_pulse * 0.35 + u_onset * 0.2 + u_kick * 0.25 + u_high_peak * 0.2);
           color *= 0.35 + u_amplitude * 1.8;
           outColor = vec4(color, 1.0);
         }

data/lib/vizcore/cli/shader_uniform_docs.rb

@@ -13,8 +13,19 @@ module Vizcore
         Uniform.new(name: "u_bass", type: "float", description: "Low-frequency band level."),
         Uniform.new(name: "u_mid", type: "float", description: "Mid-frequency band level."),
         Uniform.new(name: "u_high", type: "float", description: "High-frequency band level."),
+        Uniform.new(name: "u_bass_peak", type: "float", description: "Held low-frequency band peak."),
+        Uniform.new(name: "u_mid_peak", type: "float", description: "Held mid-frequency band peak."),
+        Uniform.new(name: "u_high_peak", type: "float", description: "Held high-frequency band peak."),
         Uniform.new(name: "u_beat", type: "float", description: "1.0 on detected beat frames, otherwise 0.0."),
         Uniform.new(name: "u_beat_pulse", type: "float", description: "Decaying beat pulse after detection."),
+        Uniform.new(name: "u_beat_phase", type: "float", description: "0.0..1.0 phase inside the current beat."),
+        Uniform.new(name: "u_bar_phase", type: "float", description: "0.0..1.0 phase inside the current 4-beat bar."),
+        Uniform.new(name: "u_bar_count", type: "float", description: "Completed 4-beat bars since analysis start."),
+        Uniform.new(name: "u_phrase_count", type: "float", description: "Completed 8-bar phrases since analysis start."),
+        Uniform.new(name: "u_beat_2", type: "float", description: "Half-beat subdivision pulse."),
+        Uniform.new(name: "u_beat_4", type: "float", description: "Quarter-beat subdivision pulse."),
+        Uniform.new(name: "u_beat_8", type: "float", description: "Eighth-beat subdivision pulse."),
+        Uniform.new(name: "u_beat_triplet", type: "float", description: "Triplet subdivision pulse."),
         Uniform.new(name: "u_onset", type: "float", description: "Positive amplitude rise since the previous active frame."),
         Uniform.new(name: "u_sub_onset", type: "float", description: "Positive sub-band rise since the previous active frame."),
         Uniform.new(name: "u_low_onset", type: "float", description: "Positive low-band rise since the previous active frame."),

data/lib/vizcore/cli.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "json"
 require "net/http"
 require "pathname"
 require "thor"
@@ -10,11 +11,13 @@ require_relative "audio"
 require_relative "cli/doctor"
 require_relative "cli/dsl_reference"
 require_relative "cli/layer_docs"
+require_relative "cli/plugin_checker"
 require_relative "cli/scene_diagnostics"
 require_relative "cli/shader_template"
 require_relative "cli/shader_uniform_docs"
 require_relative "config"
 require_relative "project_manifest"
+require_relative "scene_trust"
 require_relative "server"
 
 module Vizcore
@@ -120,8 +123,12 @@ module Vizcore
     option :bpm, type: :numeric, desc: "Fixed BPM value used with --bpm-lock"
     option :bpm_lock, type: :boolean, default: false, desc: "Lock analysis BPM output to --bpm"
     option :osc_port, type: :numeric, desc: "UDP port for OSC sync (/vizcore/scene, /vizcore/tap)"
+    option :scene_switch_effect, type: :string, desc: "Transition effect name for manual scene switch actions"
+    option :scene_switch_duration, type: :numeric, desc: "Duration in seconds for manual scene switch effects"
     option :reload, type: :boolean, default: Config::DEFAULT_RELOAD, desc: "Reload the scene file when it changes"
     option :projector, type: :boolean, default: false, desc: "Hide browser operator UI for projection output"
+    option :allow_public_control, type: :boolean, default: false, desc: "Allow control panel/WebSocket when binding to a public host"
+    option :trust, type: :boolean, default: false, desc: "Suppress Ruby scene execution safety warning"
     # Start the Vizcore server with the given scene file.
     #
     # @param scene_file [String] path to a Ruby scene DSL file
@@ -146,10 +153,14 @@ module Vizcore
         bpm: options[:bpm],
         bpm_lock: options.fetch(:bpm_lock),
         osc_port: options[:osc_port] || defaults[:osc_port],
+        scene_switch_effect: options[:scene_switch_effect] || defaults[:scene_switch_effect],
+        scene_switch_effect_duration: options[:scene_switch_duration] || defaults[:scene_switch_effect_duration],
         reload: options.fetch(:reload),
-        projector_mode: options.fetch(:projector)
+        projector_mode: options.fetch(:projector),
+        allow_public_control: options.fetch(:allow_public_control)
       )
-      Server::Runner.new(config).run
+      warn_untrusted_scene(config.scene_file, project_root: manifest&.root || Dir.pwd) unless options.fetch(:trust)
+      Server::Runner.new(config, manifest: manifest, initial_profile: profile).run
     rescue ArgumentError => e
       raise Thor::Error, e.message
     end
@@ -162,7 +173,10 @@ module Vizcore
     option :bpm_lock, type: :boolean, default: false, desc: "Lock analysis BPM output to --bpm"
     option :control_preset, type: :string, desc: "Control preset JSON for browser HUD and MIDI learn"
     option :osc_port, type: :numeric, desc: "UDP port for OSC sync (/vizcore/scene, /vizcore/tap)"
+    option :scene_switch_effect, type: :string, desc: "Transition effect name for manual scene switch actions"
+    option :scene_switch_duration, type: :numeric, desc: "Duration in seconds for manual scene switch effects"
     option :projector, type: :boolean, default: false, desc: "Hide browser operator UI for projection output"
+    option :allow_public_control, type: :boolean, default: false, desc: "Allow control panel/WebSocket when binding to a public host"
     # Start a bundled scene with bundled audio for first-run verification.
     #
     # @return [void]
@@ -178,7 +192,10 @@ module Vizcore
         bpm_lock: options.fetch(:bpm_lock),
         control_preset: options[:control_preset],
         osc_port: options[:osc_port],
-        projector_mode: options.fetch(:projector)
+        scene_switch_effect: options[:scene_switch_effect],
+        scene_switch_effect_duration: options[:scene_switch_duration],
+        projector_mode: options.fetch(:projector),
+        allow_public_control: options.fetch(:allow_public_control)
       )
       Server::Runner.new(config).run
     rescue ArgumentError => e
@@ -256,16 +273,76 @@ module Vizcore
       raise Thor::Error, "vizcore doctor found required failures" if report.failure?
     end
 
+    desc "features", "Print optional runtime feature availability"
+    option :format, type: :string, default: "text", desc: "Output format: text or json"
+    # Print optional dependency feature flags for automation and doctor-style checks.
+    #
+    # @raise [Thor::Error] when the output format is unsupported
+    # @return [void]
+    def features
+      payload = Vizcore.features
+      case options.fetch(:format).to_s
+      when "json"
+        say(JSON.pretty_generate(payload.transform_keys(&:to_s)))
+      when "text"
+        payload.each do |name, available|
+          say("#{available ? '[ok]' : '[warn]'} #{name}: #{available ? 'available' : 'unavailable'}")
+        end
+      else
+        raise Thor::Error, "unsupported features format: #{options.fetch(:format)}"
+      end
+    end
+
+    desc "calibrate COMMAND", "Measure input levels for audio calibration"
+    option :audio_source, type: :string, default: "mic", desc: "Audio source: mic, file, dummy"
+    option :audio_file, type: :string, desc: "Path to audio file used when --audio-source file"
+    option :audio_device, type: :string, desc: "Audio input device index or name used when --audio-source mic"
+    option :duration, type: :numeric, default: Vizcore::Audio::Calibration::DEFAULT_DURATION, desc: "Calibration duration in seconds"
+    option :fps, type: :numeric, default: Vizcore::Audio::Calibration::DEFAULT_FPS, desc: "Calibration sampling rate"
+    option :format, type: :string, default: "text", desc: "Output format: text or json"
+    # Run calibration helpers.
+    #
+    # @param command [String, nil]
+    # @raise [Thor::Error] when arguments are invalid
+    # @return [void]
+    def calibrate(command = nil)
+      raise Thor::Error, "Unknown calibrate command: #{command || '(nil)'}. Use `vizcore calibrate audio`." unless command.to_s == "audio"
+
+      result = Vizcore::Audio::Calibration.new(
+        source: options.fetch(:audio_source),
+        file_path: options[:audio_file],
+        audio_device: options[:audio_device],
+        duration: options.fetch(:duration),
+        fps: options.fetch(:fps)
+      ).call
+      print_calibration_result(result, format: options.fetch(:format))
+    rescue ArgumentError => e
+      raise Thor::Error, e.message
+    end
+
     map "inspect" => :inspect_scene
     desc "inspect SCENE_FILE", "Print scenes, layers, mappings, and transitions"
+    option :format, type: :string, default: "text", desc: "Output format: text or json"
     # Load a scene DSL file and print its runtime structure.
     #
     # @param scene_file [String] path to a Ruby scene DSL file
     # @raise [Thor::Error] when scene loading fails
     # @return [void]
     def inspect_scene(scene_file)
+      format = options.fetch(:format).to_s
       diagnostics = Vizcore::CLISupport::SceneDiagnostics.new(scene_file: scene_file)
       result = diagnostics.validate
+      if format == "json"
+        payload = {
+          issues: result.issues.map(&:to_h),
+          definition: result.definition ? Vizcore::CLISupport::SceneInspector.new(definition: result.definition).to_h : nil
+        }
+        say(JSON.pretty_generate(payload))
+        raise Thor::Error, "scene inspection failed" unless result.definition
+        return
+      end
+      raise Thor::Error, "unsupported inspect format: #{format}" unless format == "text"
+
       print_issues(result.issues)
       raise Thor::Error, "scene inspection failed" unless result.definition
 
@@ -273,13 +350,14 @@ module Vizcore
     end
 
     desc "validate SCENE_FILE", "Validate a scene DSL file"
+    option :strict, type: :boolean, default: false, desc: "Error on unknown layer params and stricter duplicate mappings"
     # Load and validate a scene DSL file without starting the server.
     #
     # @param scene_file [String] path to a Ruby scene DSL file
     # @raise [Thor::Error] when validation fails
     # @return [void]
     def validate(scene_file)
-      result = Vizcore::CLISupport::SceneDiagnostics.new(scene_file: scene_file).validate
+      result = Vizcore::CLISupport::SceneDiagnostics.new(scene_file: scene_file, strict: options.fetch(:strict)).validate
       print_issues(result.issues)
       raise Thor::Error, "scene validation failed" unless result.valid?
 
@@ -343,8 +421,10 @@ module Vizcore
       case command.to_s
       when "new"
         create_plugin_scaffold(name)
+      when "check"
+        check_plugin_scaffold(name)
       else
-        raise Thor::Error, "Unknown plugin command: #{command || '(nil)'}. Use `vizcore plugin new NAME`."
+        raise Thor::Error, "Unknown plugin command: #{command || '(nil)'}. Use `vizcore plugin new NAME` or `vizcore plugin check PATH`."
       end
     rescue ArgumentError => e
       raise Thor::Error, e.message
@@ -357,6 +437,8 @@ module Vizcore
     option :wait, type: :numeric, default: 1000, desc: "Milliseconds to wait after page load"
     option :width, type: :numeric, default: 1280, desc: "Browser viewport width"
     option :height, type: :numeric, default: 720, desc: "Browser viewport height"
+    option :wait_for_frame, type: :boolean, default: false, desc: "Wait until the Vizcore page receives an audio frame"
+    option :frame_timeout, type: :numeric, default: 10_000, desc: "Milliseconds to wait for the first Vizcore frame"
     # Capture browser-rendered output from a running Vizcore server.
     #
     # @param url [String]
@@ -369,7 +451,9 @@ module Vizcore
         selector: options.fetch(:selector),
         wait: options.fetch(:wait),
         width: options.fetch(:width),
-        height: options.fetch(:height)
+        height: options.fetch(:height),
+        wait_for_frame: options.fetch(:wait_for_frame),
+        frame_timeout: options.fetch(:frame_timeout)
       )
     end
 
@@ -386,6 +470,10 @@ module Vizcore
     option :timeout, type: :numeric, default: 10, desc: "Seconds to wait for the temporary server"
     option :width, type: :numeric, default: 1280, desc: "Browser viewport width"
     option :height, type: :numeric, default: 720, desc: "Browser viewport height"
+    option :wait_for_frame, type: :boolean, default: true, desc: "Wait until the projector receives an audio frame"
+    option :frame_timeout, type: :numeric, default: 10_000, desc: "Milliseconds to wait for the first projector frame"
+    option :allow_public_control, type: :boolean, default: false, desc: "Allow control panel/WebSocket when binding to a public host"
+    option :trust, type: :boolean, default: false, desc: "Suppress Ruby scene execution safety warning"
     # Start Vizcore and capture a browser-rendered canvas from the projector route.
     #
     # @param scene_file [String]
@@ -401,9 +489,11 @@ module Vizcore
         feature_file: options[:feature_file],
         control_preset: options[:control_preset],
         reload: false,
-        projector_mode: true
+        projector_mode: true,
+        allow_public_control: options.fetch(:allow_public_control)
       )
       validate_snapshot_config!(config)
+      warn_untrusted_scene(config.scene_file) unless options.fetch(:trust)
 
       pid = Kernel.spawn(*temporary_server_command(config), out: File::NULL, err: File::NULL)
       begin
@@ -414,7 +504,9 @@ module Vizcore
           selector: options.fetch(:selector),
           wait: options.fetch(:wait),
           width: options.fetch(:width),
-          height: options.fetch(:height)
+          height: options.fetch(:height),
+          wait_for_frame: options.fetch(:wait_for_frame),
+          frame_timeout: options.fetch(:frame_timeout)
         )
       ensure
         stop_temporary_server(pid)
@@ -433,6 +525,8 @@ module Vizcore
     option :out, type: :string, default: "snapshot.png", desc: "Output PNG path"
     option :width, type: :numeric, default: Vizcore::Renderer::SnapshotRenderer::DEFAULT_WIDTH, desc: "Snapshot width"
     option :height, type: :numeric, default: Vizcore::Renderer::SnapshotRenderer::DEFAULT_HEIGHT, desc: "Snapshot height"
+    option :transparent, type: :boolean, default: false, desc: "Render a transparent PNG background"
+    option :trust, type: :boolean, default: false, desc: "Suppress Ruby scene execution safety warning"
     # Load a scene DSL file and write a software-rendered PNG preview.
     #
     # @param scene_file [String] path to a Ruby scene DSL file
@@ -449,11 +543,13 @@ module Vizcore
         bpm_lock: options.fetch(:bpm_lock)
       )
       validate_snapshot_config!(config)
+      warn_untrusted_scene(config.scene_file) unless options.fetch(:trust)
 
       result = Vizcore::Renderer::Snapshot.new(
         config: config,
         width: options.fetch(:width),
-        height: options.fetch(:height)
+        height: options.fetch(:height),
+        transparent: options.fetch(:transparent)
       ).write(out: options.fetch(:out))
       say("Snapshot written: #{result[:path]} (scene=#{result[:scene]}, #{result[:width]}x#{result[:height]})")
     rescue StandardError => e
@@ -469,15 +565,30 @@ module Vizcore
     option :bpm_lock, type: :boolean, default: false, desc: "Lock analysis BPM output to --bpm"
     option :out, type: :string, default: "frames", desc: "Output directory for PNG frames, or .mp4 video path"
     option :frames, type: :numeric, default: Vizcore::Renderer::RenderSequence::DEFAULT_FRAME_COUNT, desc: "Number of frames to write"
+    option :duration, type: :numeric, desc: "Render duration in seconds; overrides --frames"
+    option :from_frame, type: :numeric, default: 1, desc: "First 1-based frame to write"
+    option :to_frame, type: :numeric, desc: "Last 1-based frame to write"
+    option :resume, type: :boolean, default: false, desc: "Skip PNG frames that already exist"
+    option :seed, type: :numeric, desc: "Deterministic random seed for render"
+    option :transparent, type: :boolean, default: false, desc: "Render transparent PNG frames"
+    option :progress, type: :boolean, default: false, desc: "Print render progress for long renders"
+    option :feature_cache, type: :boolean, default: true, desc: "Reuse and write cached feature analysis for file-based renders"
+    option :feature_cache_dir, type: :string, desc: "Directory used to cache recorded analysis features"
+    option :codec, type: :string, desc: "ffmpeg video codec for MP4 output"
+    option :bitrate, type: :string, desc: "ffmpeg video bitrate for MP4 output"
+    option :crf, type: :string, desc: "ffmpeg CRF value for MP4 output"
+    option :pix_fmt, type: :string, default: "yuv420p", desc: "ffmpeg pixel format for MP4 output"
     option :fps, type: :numeric, default: Vizcore::Renderer::RenderSequence::DEFAULT_FRAME_RATE, desc: "Render frame rate"
     option :width, type: :numeric, default: Vizcore::Renderer::SnapshotRenderer::DEFAULT_WIDTH, desc: "Frame width"
     option :height, type: :numeric, default: Vizcore::Renderer::SnapshotRenderer::DEFAULT_HEIGHT, desc: "Frame height"
+    option :trust, type: :boolean, default: false, desc: "Suppress Ruby scene execution safety warning"
     # Load a scene DSL file and write a software-rendered PNG image sequence or MP4.
     #
     # @param scene_file [String] path to a Ruby scene DSL file
     # @raise [Thor::Error] when scene loading or frame writing fails
     # @return [void]
     def render(scene_file)
+      feature_file = resolve_render_feature_cache if feature_cache_enabled?(scene_file: scene_file)
       config = Config.new(
         scene_file: scene_file,
         audio_source: options.fetch(:audio_source),
@@ -485,16 +596,29 @@ module Vizcore
         audio_device: options[:audio_device],
         noise_gate: options.fetch(:noise_gate),
         bpm: options[:bpm],
-        bpm_lock: options.fetch(:bpm_lock)
+        bpm_lock: options.fetch(:bpm_lock),
+        feature_file: feature_file
       )
       validate_snapshot_config!(config)
+      warn_untrusted_scene(config.scene_file) unless options.fetch(:trust)
 
       result = Vizcore::Renderer::RenderSequence.new(
         config: config,
         frames: options.fetch(:frames),
         fps: options.fetch(:fps),
         width: options.fetch(:width),
-        height: options.fetch(:height)
+        height: options.fetch(:height),
+        duration: options[:duration],
+        from_frame: options.fetch(:from_frame),
+        to_frame: options[:to_frame],
+        resume: options.fetch(:resume),
+        seed: options[:seed],
+        transparent: options.fetch(:transparent),
+        video_codec: options[:codec],
+        video_bitrate: options[:bitrate],
+        video_crf: options[:crf],
+        pixel_format: options[:pix_fmt],
+        progress_reporter: render_progress_reporter
       ).write(out: options.fetch(:out))
       return say(render_video_message(result)) if result[:format] == :mp4
 
@@ -515,6 +639,8 @@ module Vizcore
     option :audio_normalize, type: :boolean, default: false, desc: "Apply adaptive feature normalization"
     option :bpm, type: :numeric, desc: "Fixed BPM value used with --bpm-lock"
     option :bpm_lock, type: :boolean, default: false, desc: "Lock analysis BPM output to --bpm"
+    option :cache, type: :boolean, default: true, desc: "Store and reuse recorded feature cache"
+    option :cache_dir, type: :string, desc: "Directory for feature cache storage"
     # Analyze an audio file and persist feature frames as JSON.
     #
     # @param audio_file [String] path to WAV/MP3/FLAC audio file
@@ -528,7 +654,8 @@ module Vizcore
         noise_gate: options.fetch(:noise_gate),
         audio_normalize: feature_audio_normalize_setting,
         bpm: options[:bpm],
-        bpm_lock: options.fetch(:bpm_lock)
+        bpm_lock: options.fetch(:bpm_lock),
+        cache_root: feature_record_cache_root
       ).write(out: options.fetch(:out))
       say(
         "Features written: #{result[:path]} " \
@@ -540,6 +667,57 @@ module Vizcore
 
     private
 
+    def feature_cache_enabled?(scene_file:)
+      return false unless options.fetch(:audio_source) == "file"
+      return false unless options[:audio_file]
+      return false unless options.fetch(:feature_cache)
+
+      Pathname.new(scene_file).expand_path.file?
+    end
+
+    def resolve_render_feature_cache
+      cache_recorder = Vizcore::Analysis::FeatureRecorder.new(
+        audio_file: options[:audio_file],
+        frames: rendered_frame_count,
+        fps: options.fetch(:fps),
+        noise_gate: options.fetch(:noise_gate),
+        audio_normalize: nil,
+        bpm: options[:bpm],
+        bpm_lock: options.fetch(:bpm_lock),
+        cache_root: render_feature_cache_root
+      )
+      cache_path = cache_recorder.cache_path
+      return nil unless cache_path
+
+      cache_recorder.write(out: cache_path.to_s)
+      cache_path
+    end
+
+    def render_feature_cache_root
+      options[:feature_cache_dir] || default_feature_cache_root
+    end
+
+    def feature_record_cache_root
+      return nil unless options.fetch(:cache)
+
+      options[:cache_dir] || default_feature_cache_root
+    end
+
+    def default_feature_cache_root
+      base_path = if (value = ENV["XDG_CACHE_HOME"])
+                    Pathname.new(value)
+                  else
+                    Pathname.new(Dir.home).join(".cache")
+                  end
+      base_path.join("vizcore", "features")
+    end
+
+    def rendered_frame_count
+      return (Float(options[:duration]) * Float(options.fetch(:fps))).ceil if options[:duration]
+
+      Integer(options.fetch(:frames))
+    end
+
     def status_label(status)
       case status
       when :ok
@@ -554,7 +732,27 @@ module Vizcore
     def print_issues(issues)
       issues.each do |issue|
         label = issue.error? ? "[error]" : "[warn]"
-        say("#{label} #{issue.message}")
+        code = issue.respond_to?(:code) && issue.code ? " #{issue.code}" : ""
+        say("#{label}#{code} #{issue.message}")
+      end
+    end
+
+    def warn_untrusted_scene(scene_file, project_root: Dir.pwd)
+      warning = Vizcore::SceneTrust.warning_for(scene_file, project_root: project_root)
+      warn("[warn] #{warning}") if warning
+    end
+
+    def print_calibration_result(result, format:)
+      case format.to_s
+      when "json"
+        say(JSON.pretty_generate(result.to_h.transform_keys(&:to_s)))
+      when "text"
+        say("Audio calibration:")
+        result.to_h.each do |key, value|
+          say("  #{key}: #{value}")
+        end
+      else
+        raise Thor::Error, "unsupported calibration format: #{format}"
       end
     end
 
@@ -625,7 +823,18 @@ module Vizcore
         "(scene=#{result[:scene]}, frames=#{result[:frames]}, fps=#{result[:fps]}, #{result[:width]}x#{result[:height]})"
     end
 
-    def run_browser_capture(url, out:, selector:, wait:, width:, height:)
+    def render_progress_reporter
+      return nil unless options.fetch(:progress)
+
+      lambda do |event|
+        say(
+          "Render progress: frame #{event.fetch(:frame)}/#{event.fetch(:to_frame)} " \
+          "(#{event.fetch(:percent).round(1)}%)"
+        )
+      end
+    end
+
+    def run_browser_capture(url, out:, selector:, wait:, width:, height:, wait_for_frame: false, frame_timeout: 10_000)
       script = Vizcore.root.join("scripts", "browser_capture.mjs")
       command = [
         "node",
@@ -642,10 +851,43 @@ module Vizcore
         "--height",
         height.to_s
       ]
-      success = Kernel.system(*command)
+      if wait_for_frame
+        command << "--wait-for-frame"
+        command << "--frame-timeout"
+        command << frame_timeout.to_s
+      end
+
+      success = nil
+      with_frontend_node_modules do
+        success = Kernel.system(*command)
+      end
       raise Thor::Error, "browser capture failed" unless success
     end
 
+    def with_frontend_node_modules
+      frontend_node_modules = Vizcore.frontend_root.join("node_modules").expand_path
+      previous_node_path = ENV["NODE_PATH"]
+      had_node_modules = frontend_node_modules.directory?
+
+      if had_node_modules
+        ENV["NODE_PATH"] = if previous_node_path.to_s.empty?
+          frontend_node_modules.to_s
+        else
+          [frontend_node_modules.to_s, previous_node_path].join(File::PATH_SEPARATOR)
+        end
+      end
+
+      yield
+    ensure
+      if had_node_modules
+        if previous_node_path
+          ENV["NODE_PATH"] = previous_node_path
+        else
+          ENV.delete("NODE_PATH")
+        end
+      end
+    end
+
     def temporary_server_command(config)
       command = [
         Gem.ruby,
@@ -665,6 +907,7 @@ module Vizcore
       command.concat(["--audio-file", config.audio_file.to_s]) if config.audio_file
       command.concat(["--feature-file", config.feature_file.to_s]) if config.feature_file
       command.concat(["--control-preset", config.control_preset.to_s]) if config.control_preset
+      command << "--allow-public-control" if config.allow_public_control?
       command
     end
 
@@ -711,6 +954,16 @@ module Vizcore
       say("Next: require_relative \"#{root.basename}/lib/#{metadata.fetch(:plugin_name)}\" in your scene")
     end
 
+    def check_plugin_scaffold(path)
+      raise ArgumentError, "plugin path is required" if path.to_s.strip.empty?
+
+      report = Vizcore::CLISupport::PluginChecker.new(path).call
+      report.checks.each do |check|
+        say("#{status_label(check.status)} #{check.name}: #{check.message}")
+      end
+      raise Thor::Error, "plugin check failed" if report.failure?
+    end
+
     def plugin_scaffold_metadata(name)
       raw_name = name.to_s.strip
       raise ArgumentError, "plugin name is required" if raw_name.empty?

data/lib/vizcore/config.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "pathname"
+require_relative "plugin_asset_policy"
 
 module Vizcore
   # Runtime configuration for CLI/server startup.
@@ -18,7 +19,8 @@ module Vizcore
     # Supported CLI audio source values.
     SUPPORTED_AUDIO_SOURCES = %i[mic file dummy].freeze
 
-    attr_reader :host, :port, :scene_file, :audio_source, :audio_file, :audio_device, :feature_file, :control_preset, :plugin_assets, :noise_gate, :bpm, :osc_port, :projector_mode
+    attr_reader :host, :port, :scene_file, :audio_source, :audio_file, :audio_device, :feature_file, :control_preset, :plugin_assets,
+      :noise_gate, :bpm, :osc_port, :projector_mode, :scene_switch_effect
 
     # @param scene_file [String, Pathname] scene DSL file path
     # @param host [String] bind host
@@ -35,6 +37,8 @@ module Vizcore
     # @param osc_port [Integer, nil] UDP port for OSC control sync
     # @param reload [Boolean] true when scene file changes should be reloaded while running
     # @param projector_mode [Boolean] true when the browser should hide operator UI by default
+    # @param scene_switch_effect [Hash, nil] transition metadata applied to manual scene switches
+    # @param allow_public_control [Boolean] true when binding operator control routes on a public host is intentional
     def initialize(
       scene_file:,
       host: DEFAULT_HOST,
@@ -50,7 +54,10 @@ module Vizcore
       bpm_lock: false,
       osc_port: nil,
       reload: DEFAULT_RELOAD,
-      projector_mode: false
+      projector_mode: false,
+      scene_switch_effect: nil,
+      scene_switch_effect_duration: nil,
+      allow_public_control: false
     )
       @scene_file = Pathname.new(scene_file).expand_path if scene_file
       @host = host
@@ -67,6 +74,8 @@ module Vizcore
       @osc_port = normalize_optional_port(osc_port)
       @reload = !!reload
       @projector_mode = !!projector_mode
+      @scene_switch_effect = normalize_scene_switch_effect(scene_switch_effect, scene_switch_effect_duration)
+      @allow_public_control = !!allow_public_control
     end
 
     # @return [Boolean] true when the configured scene file exists.
@@ -89,6 +98,11 @@ module Vizcore
       @bpm_lock
     end
 
+    # @return [Boolean] true when public host binding is allowed.
+    def allow_public_control?
+      @allow_public_control
+    end
+
     private
 
     def normalize_audio_source(value)
@@ -140,8 +154,31 @@ module Vizcore
         raw_value = value.to_s.strip
         next if raw_value.empty?
 
-        value.is_a?(Pathname) ? value.expand_path : Pathname.new(raw_value).expand_path
+        path = value.is_a?(Pathname) ? value.expand_path : Pathname.new(raw_value).expand_path
+        Vizcore::PluginAssetPolicy.validate!(path)
+      end
+    end
+
+    def normalize_scene_switch_effect(effect_name, duration)
+      return nil if effect_name.nil?
+
+      raw_name = effect_name.to_s.strip
+      return nil if raw_name.empty?
+
+      options = {}
+      unless duration.nil?
+        normalized_duration = Float(duration)
+        options[:duration] = normalized_duration if normalized_duration.positive? || normalized_duration.zero?
       end
+
+      {
+        name: raw_name.to_sym,
+        options: options
+      }.tap do |effect|
+        effect.delete(:options) if options.empty?
+      end
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "scene_switch_duration must be numeric"
     end
   end
 end