vizcore 0.1.0 → 1.0.0

data/lib/vizcore/server/websocket_handler.rb

@@ -9,6 +9,10 @@ module Vizcore
   module Server
     # Stateless WebSocket endpoint manager for frame broadcast transport.
     class WebSocketHandler
+      PROTOCOL_VERSION = "vizcore.frame.v1"
+      MAX_BUFFERED_FRAME_BYTES = 1_000_000
+      DROPPABLE_MESSAGE_TYPES = Set["audio_frame"].freeze
+
       class << self
         # Rack endpoint for WebSocket upgrade handling.
         #
@@ -36,15 +40,29 @@ module Vizcore
         def broadcast(type:, payload:)
           return false unless faye_websocket_class
 
-          message = JSON.generate(type: type, payload: payload)
+          message = JSON.generate(protocol: PROTOCOL_VERSION, type: type, payload: payload)
 
           each_socket do |socket|
-            send_message(socket, message)
+            send_message(socket, message, type: type)
           end
 
           true
         end
 
+        # Send one typed payload to a single websocket client.
+        #
+        # @param socket [#send]
+        # @param type [String]
+        # @param payload [Hash]
+        # @return [Boolean] false when websocket backend is unavailable
+        def send_to(socket, type:, payload:)
+          return false unless faye_websocket_class
+
+          message = JSON.generate(protocol: PROTOCOL_VERSION, type: type, payload: payload)
+          send_message(socket, message, type: type)
+          true
+        end
+
         # @return [Integer]
         def connection_count
           mutex.synchronize { sockets.size }
@@ -55,6 +73,11 @@ module Vizcore
           mutex.synchronize { @last_error }
         end
 
+        # @return [Integer]
+        def dropped_frame_count
+          mutex.synchronize { @dropped_frame_count || 0 }
+        end
+
         # Register one inbound message handler for client -> server control messages.
         #
         # @yieldparam message [Hash]
@@ -79,21 +102,44 @@ module Vizcore
           nil
         end
 
-        def send_message(socket, message)
+        def send_message(socket, message, type:)
+          return if drop_for_backpressure?(socket, type)
+
           if event_machine_reactor_running?
-            EventMachine.schedule { safe_send(socket, message) }
+            EventMachine.schedule { safe_send(socket, message, type: type) }
           else
-            safe_send(socket, message)
+            safe_send(socket, message, type: type)
           end
         end
 
-        def safe_send(socket, message)
+        def safe_send(socket, message, type:)
+          return if drop_for_backpressure?(socket, type)
+
           socket.send(message)
         rescue StandardError => e
           set_last_error(e)
           unregister(socket)
         end
 
+        def drop_for_backpressure?(socket, type)
+          return false unless DROPPABLE_MESSAGE_TYPES.include?(type.to_s)
+
+          buffered_amount = socket_buffered_amount(socket)
+          return false unless buffered_amount && buffered_amount > MAX_BUFFERED_FRAME_BYTES
+
+          increment_dropped_frame_count
+          true
+        end
+
+        def socket_buffered_amount(socket)
+          return socket.buffered_amount if socket.respond_to?(:buffered_amount)
+          return socket.bufferedAmount if socket.respond_to?(:bufferedAmount)
+
+          nil
+        rescue StandardError
+          nil
+        end
+
         def event_machine_reactor_running?
           require "eventmachine"
           EventMachine.reactor_running?
@@ -105,9 +151,9 @@ module Vizcore
           [500, json_headers, [JSON.generate(error: "Missing dependency: faye-websocket")]]
         end
 
-        def handle_message(_socket, raw_message)
+        def handle_message(socket, raw_message)
           message = JSON.parse(raw_message)
-          dispatch_message(message)
+          dispatch_message(message, socket)
           message
         rescue JSON::ParserError => e
           set_last_error(e)
@@ -139,12 +185,16 @@ module Vizcore
           mutex.synchronize { @last_error = error }
         end
 
-        def dispatch_message(message)
+        def increment_dropped_frame_count
+          mutex.synchronize { @dropped_frame_count = (@dropped_frame_count || 0) + 1 }
+        end
+
+        def dispatch_message(message, socket)
           handler = mutex.synchronize { @message_handler }
           return unless handler
           return unless message.is_a?(Hash)
 
-          handler.call(message)
+          handler.call(message, socket)
         rescue StandardError => e
           set_last_error(e)
           nil

data/lib/vizcore/server.rb

@@ -7,6 +7,10 @@ module Vizcore
 end
 
 require_relative "server/frame_broadcaster"
+require_relative "server/gallery_page"
+require_relative "server/gallery_app"
+require_relative "server/gallery_runner"
 require_relative "server/rack_app"
+require_relative "server/scene_dependency_watcher"
 require_relative "server/runner"
 require_relative "server/websocket_handler"

data/lib/vizcore/sync/osc_message.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Vizcore
+  module Sync
+    # Minimal OSC 1.0 message parser for control sync.
+    class OscMessage
+      attr_reader :address, :arguments
+
+      # @param data [String]
+      # @return [Vizcore::Sync::OscMessage, nil]
+      def self.parse(data)
+        parser = Parser.new(data)
+        address = parser.read_string
+        return nil unless address&.start_with?("/")
+
+        tags = parser.read_string
+        arguments = parser.read_arguments(tags)
+        new(address: address, arguments: arguments)
+      rescue StandardError
+        nil
+      end
+
+      # @param address [String]
+      # @param arguments [Array]
+      def initialize(address:, arguments: [])
+        @address = address
+        @arguments = Array(arguments)
+      end
+
+      # @api private
+      class Parser
+        # @param data [String]
+        def initialize(data)
+          @data = data.to_s.b
+          @offset = 0
+        end
+
+        # @return [String, nil]
+        def read_string
+          start = @offset
+          @offset += 1 while @offset < @data.bytesize && @data.getbyte(@offset) != 0
+          return nil if @offset >= @data.bytesize
+
+          value = @data.byteslice(start...@offset).to_s.force_encoding(Encoding::UTF_8)
+          @offset += 1
+          align_offset
+          value
+        end
+
+        # @param tags [String, nil]
+        # @return [Array]
+        def read_arguments(tags)
+          return [] if tags.to_s.empty?
+          return [] unless tags.start_with?(",")
+
+          tags[1..].to_s.each_char.map do |tag|
+            read_argument(tag)
+          end
+        end
+
+        private
+
+        def read_argument(tag)
+          case tag
+          when "i"
+            read_int32
+          when "f"
+            read_float32
+          when "s"
+            read_string
+          when "T"
+            true
+          when "F"
+            false
+          else
+            nil
+          end
+        end
+
+        def read_int32
+          value = read_bytes(4).unpack1("N")
+          value >= 0x80000000 ? value - 0x100000000 : value
+        end
+
+        def read_float32
+          read_bytes(4).unpack1("g")
+        end
+
+        def read_bytes(length)
+          raise ArgumentError, "OSC payload truncated" if @offset + length > @data.bytesize
+
+          @data.byteslice(@offset, length).tap do
+            @offset += length
+          end
+        end
+
+        def align_offset
+          @offset += 1 while (@offset % 4).positive?
+        end
+      end
+    end
+  end
+end

data/lib/vizcore/sync/osc_receiver.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "socket"
+require_relative "osc_message"
+
+module Vizcore
+  module Sync
+    # Receives OSC UDP messages on a background thread.
+    class OscReceiver
+      DEFAULT_HOST = "127.0.0.1"
+      MAX_PACKET_SIZE = 65_536
+
+      # @param port [Integer]
+      # @param host [String]
+      # @param handler [#call]
+      # @param error_reporter [#call, nil]
+      def initialize(port:, host: DEFAULT_HOST, handler:, error_reporter: nil)
+        @host = host.to_s
+        @port = Integer(port)
+        @handler = handler
+        @error_reporter = error_reporter
+        @socket = nil
+        @thread = nil
+        @running = false
+      end
+
+      # @return [Vizcore::Sync::OscReceiver]
+      def start
+        return self if @thread&.alive?
+
+        @socket = UDPSocket.new
+        @socket.bind(@host, @port)
+        @running = true
+        @thread = Thread.new { receive_loop }
+        self
+      end
+
+      # @return [nil]
+      def stop
+        @running = false
+        @socket&.close
+        @thread&.join(1)
+        nil
+      rescue StandardError
+        nil
+      ensure
+        @socket = nil
+        @thread = nil
+      end
+
+      private
+
+      def receive_loop
+        while @running
+          begin
+            data, = @socket.recvfrom(MAX_PACKET_SIZE)
+            message = OscMessage.parse(data)
+            @handler.call(message) if message
+          rescue IOError, SystemCallError
+            break unless @running
+          rescue StandardError => e
+            @error_reporter&.call("OSC message ignored: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vizcore/sync.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "sync/osc_message"
+require_relative "sync/osc_receiver"

data/lib/vizcore/templates/midi_control_scene.rb

@@ -2,11 +2,13 @@
 
 # {{project_name}} MIDI mapping example.
 Vizcore.define do
+  set :global_intensity, 0.65
+
   midi :controller, device: :default
 
   scene :warmup do
     layer :warm_bg do
-      shader :neon_grid
+      shader :waveform_ribbon
       map frequency_band(:mid) => :intensity
     end
   end

data/lib/vizcore/templates/plugin_layer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "vizcore"
+
+module {{plugin_module}}
+  LAYER_TYPE = :{{plugin_type}}
+
+  Vizcore.register_layer_capability(
+    type: LAYER_TYPE,
+    aliases: [:{{plugin_name}}],
+    params: {
+      intensity: "Float",
+      color: "CSS color",
+      blend: "Blend mode",
+      opacity: "Float"
+    },
+    mappable_params: %i[intensity opacity],
+    description: "{{plugin_title}} browser-rendered plugin layer."
+  )
+end

data/lib/vizcore/templates/plugin_readme.md

@@ -0,0 +1,23 @@
+# {{plugin_title}}
+
+Vizcore plugin scaffold generated by `vizcore plugin new`.
+
+## Files
+
+- `lib/{{plugin_name}}.rb` registers the Ruby layer capability used by validation and docs.
+- `frontend/{{plugin_name}}-renderer.js` registers a browser renderer through `globalThis.VizcorePlugins`.
+- `examples/{{plugin_name}}_scene.rb` shows the layer type in a scene.
+
+## Try It
+
+```ruby
+require_relative "lib/{{plugin_name}}"
+```
+
+Serve `frontend/{{plugin_name}}-renderer.js` with your Vizcore frontend and load
+it after the built-in app script. The browser runtime exposes
+`globalThis.VizcorePlugins.apiVersion`; this scaffold expects version 1 or
+newer. The browser renderer returns line points, so Vizcore can composite it
+with normal layer `blend` and `opacity` params. Shader plugins can instead
+register with `registerShaderRenderer(type, renderer)` and return a GLSL
+fragment shader string or `{ kind: "shader", fragmentShader }`.

data/lib/vizcore/templates/plugin_renderer.js

@@ -0,0 +1,43 @@
+const layerType = "{{plugin_type}}";
+
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+
+export const {{plugin_renderer}} = ({ audio, time, layer }) => {
+  const params = layer?.params || {};
+  const amplitude = clamp(Number(audio?.amplitude || 0), 0, 1);
+  const intensity = clamp(Number(params.intensity ?? 1), 0, 4);
+  const radius = 0.25 + amplitude * intensity * 0.18;
+  const phase = Number(time || 0) * 0.8;
+  const points = [];
+
+  for (let index = 0; index < 18; index += 1) {
+    const angle = phase + index * Math.PI / 9;
+    const nextAngle = angle + Math.PI * 0.35;
+    points.push(
+      Math.cos(angle) * radius,
+      Math.sin(angle) * radius,
+      Math.cos(nextAngle) * (radius + 0.18),
+      Math.sin(nextAngle) * (radius + 0.18),
+    );
+  }
+
+  return {
+    kind: "lines",
+    color: [0.45 + amplitude * 0.35, 0.9, 1.0],
+    points,
+  };
+};
+
+const register = () => {
+  const runtime = globalThis.VizcorePlugins;
+  if (!runtime?.registerLayerRenderer || Number(runtime.apiVersion || 0) < 1) {
+    return false;
+  }
+
+  runtime.registerLayerRenderer(layerType, {{plugin_renderer}});
+  return true;
+};
+
+if (!register() && typeof globalThis.addEventListener === "function") {
+  globalThis.addEventListener("vizcore:plugins-ready", register, { once: true });
+}

data/lib/vizcore/templates/plugin_scene.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "../lib/{{plugin_name}}"
+
+Vizcore.define do
+  scene :{{plugin_name}}_demo do
+    layer :{{plugin_name}} do
+      type :{{plugin_type}}
+      intensity 1.0
+      fill "#67e8f9"
+      blend :add
+    end
+  end
+end

data/lib/vizcore/templates/project_readme.md

@@ -2,34 +2,18 @@
 
 This project was generated by `vizcore new`.
 
+Template: `{{template_name}}`
+
 ## Start
 
 ```bash
-vizcore start scenes/basic.rb
+vizcore start {{start_scene}}
 ```
 
-## Included Scenes
-
-- `scenes/basic.rb`: Minimal wireframe starter
-- `scenes/intro_drop.rb`: Transition flow with beat trigger
-- `scenes/midi_control.rb`: MIDI note/CC mapping example
-- `scenes/custom_shader.rb`: Custom GLSL + post/VJ effect example
-
-## Custom Shader
-
-`scenes/custom_shader.rb` references `shaders/custom_wave.frag`.
-Edit that file and save to see hot-reload updates.
-
-## MIDI
+## Included Files
 
-List devices:
+{{included_files}}
 
-```bash
-vizcore devices midi
-```
-
-Start MIDI example:
+## Notes
 
-```bash
-vizcore start scenes/midi_control.rb
-```
+{{template_notes}}

data/lib/vizcore/templates/rubykaigi_scene.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# {{project_name}} Ruby conference visual starter.
+Vizcore.define do
+  scene :rubykaigi do
+    layer :ruby_grid do
+      shader :neon_grid
+      opacity 0.72
+      blend :screen
+      map frequency_band(:mid) => :intensity
+    end
+
+    layer :ruby_pulse do
+      type :wireframe_cube
+      blend :add
+      map amplitude => :rotation_speed, range: 0.5..3.2
+      map fft_spectrum => :deform
+      map frequency_band(:high) => :color_shift
+    end
+
+    layer :title do
+      type :text
+      content "{{project_name}}"
+      font_size 88
+      color "#e11d48"
+      glow_strength 0.35
+      map beat? => :flash
+    end
+  end
+end

data/lib/vizcore/version.rb

@@ -2,5 +2,5 @@
 
 module Vizcore
   # Current gem version.
-  VERSION = "0.1.0"
+  VERSION = "1.0.0"
 end

data/lib/vizcore.rb

@@ -2,6 +2,7 @@
 
 require_relative "vizcore/version"
 require_relative "vizcore/errors"
+require_relative "vizcore/layer_catalog"
 require_relative "vizcore/dsl"
 require "pathname"
 
@@ -34,4 +35,30 @@ module Vizcore
   def self.define(&block)
     DSL::Engine.define(&block)
   end
+
+  # Load a Vizcore plugin by Ruby require path.
+  #
+  # @param name [String, Symbol] require path for the plugin
+  # @return [true]
+  def self.plugin(name)
+    require name.to_s
+  end
+
+  # Register a plugin-provided layer capability for validation and docs.
+  #
+  # @param type [Symbol, String] primary layer type
+  # @param aliases [Array<Symbol, String>] supported aliases
+  # @param params [Hash] layer parameter metadata
+  # @param mappable_params [Array<Symbol, String>] params that can be mapped
+  # @param description [String, nil] human-readable docs text
+  # @return [Vizcore::LayerCatalog::Capability]
+  def self.register_layer_capability(type:, aliases: [], params: {}, mappable_params: [], description: nil)
+    LayerCatalog.register_layer_capability(
+      type: type,
+      aliases: aliases,
+      params: params,
+      mappable_params: mappable_params,
+      description: description
+    )
+  end
 end

data/scripts/browser_capture.mjs

@@ -0,0 +1,75 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const options = parseArgs(process.argv.slice(2));
+
+if (!options.url) {
+  console.error("Usage: node scripts/browser_capture.mjs URL --out browser-capture.png [--selector #vizcore-canvas] [--wait 1000]");
+  process.exit(1);
+}
+
+let chromium;
+try {
+  ({ chromium } = await import("playwright"));
+} catch {
+  console.error("Playwright is required for browser capture. Install it with `npm install -D playwright` in the frontend project.");
+  process.exit(2);
+}
+
+const browser = await chromium.launch({ headless: true });
+try {
+  const page = await browser.newPage({ viewport: { width: options.width, height: options.height } });
+  await page.goto(options.url, { waitUntil: "domcontentloaded" });
+  if (options.wait > 0) {
+    await page.waitForTimeout(options.wait);
+  }
+
+  const element = page.locator(options.selector).first();
+  await element.waitFor({ state: "visible", timeout: 10000 });
+  await fs.mkdir(path.dirname(options.out), { recursive: true });
+  await element.screenshot({ path: options.out });
+  console.log(`Browser capture written: ${options.out}`);
+} finally {
+  await browser.close();
+}
+
+function parseArgs(args) {
+  const parsed = {
+    url: null,
+    out: "browser-capture.png",
+    selector: "#vizcore-canvas",
+    wait: 1000,
+    width: 1280,
+    height: 720,
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === "--out") {
+      parsed.out = String(args[index + 1] || parsed.out);
+      index += 1;
+    } else if (value === "--selector") {
+      parsed.selector = String(args[index + 1] || parsed.selector);
+      index += 1;
+    } else if (value === "--wait") {
+      parsed.wait = finiteNumber(args[index + 1], parsed.wait);
+      index += 1;
+    } else if (value === "--width") {
+      parsed.width = finiteNumber(args[index + 1], parsed.width);
+      index += 1;
+    } else if (value === "--height") {
+      parsed.height = finiteNumber(args[index + 1], parsed.height);
+      index += 1;
+    } else if (!parsed.url) {
+      parsed.url = value;
+    }
+  }
+
+  parsed.out = path.resolve(parsed.out);
+  return parsed;
+}
+
+function finiteNumber(value, fallback) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+}