glslkit-webgl 0.1.0.pre

data/lib/glslkit/webgl/geometry.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Glslkit
+  module WebGL
+    class Geometry
+      attr_reader :vao, :count, :indexed, :index_type, :mode, :attribute_locations
+
+      def initialize(gl, program, attributes:, indices: nil, mode: nil)
+        @gl = gl
+        @vao = gl.call(:createVertexArray)
+        @mode = mode || gl[:TRIANGLES]
+        # M11d: 構築時に実際に使ったattributeのlocationを保持する
+        # (SPEC-livereload.md §4.2)。reload時、Contextがこれと新Programの
+        # locationを突き合わせ、このGeometryのVAOがそのまま使えるかを判断する。
+        @attribute_locations = {}
+        gl.call(:bindVertexArray, @vao)
+        build_attributes(program, attributes)
+        build_indices(indices)
+        gl.call(:bindVertexArray, JS::Null)
+      end
+
+      private
+
+      def build_attributes(program, attributes)
+        float32 = JS.global[:Float32Array]
+        counts = []
+        attributes.each do |name, config|
+          location = program.attribute_locations.fetch(name.to_sym) do
+            raise KeyError, "attribute not found in manifest: #{name}"
+          end
+          @attribute_locations[name.to_sym] = location
+          next if location.to_i < 0
+
+          components = config.fetch(:components)
+          data = float32.call(:from, config.fetch(:data).to_js)
+          buffer = @gl.call(:createBuffer)
+          @gl.call(:bindBuffer, @gl[:ARRAY_BUFFER], buffer)
+          @gl.call(:bufferData, @gl[:ARRAY_BUFFER], data, @gl[:STATIC_DRAW])
+          @gl.call(:enableVertexAttribArray, location)
+          @gl.call(:vertexAttribPointer, location, components, @gl[:FLOAT], false, 0, 0)
+          counts << data[:length].to_i / components
+        end
+        @count = counts.min || 0
+      end
+
+      def build_indices(indices)
+        @indexed = !indices.nil?
+        return unless @indexed
+
+        max = indices.max || 0
+        constructor, @index_type = if max > 65_535
+          [JS.global[:Uint32Array], @gl[:UNSIGNED_INT]]
+        else
+          [JS.global[:Uint16Array], @gl[:UNSIGNED_SHORT]]
+        end
+        data = constructor.call(:from, indices.to_js)
+        buffer = @gl.call(:createBuffer)
+        @gl.call(:bindBuffer, @gl[:ELEMENT_ARRAY_BUFFER], buffer)
+        @gl.call(:bufferData, @gl[:ELEMENT_ARRAY_BUFFER], data, @gl[:STATIC_DRAW])
+        @count = data[:length].to_i
+      end
+    end
+  end
+end

data/lib/glslkit/webgl/live_reload.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+# M11e: development専用のライブリロード監視ループ(SPEC-livereload.md §4.4)。
+# `glslkit/webgl` からは自動でrequireされない — 使う側が明示的に
+# `require "glslkit/webgl/live_reload"` すること(決定3)。production相当の
+# 環境ではこのファイル自体をrequireしないことで対処する。エンドポイントが
+# 存在しない場合の404ハンドリングは不要(そもそも呼ばれない)。
+#
+# spike/09-fetch.htmlの実機確認(SPEC-livereload.md §4.4)により、
+# `JS::Object#await` はここでは使えないことが分かっている。`.then` + Proc
+# だけで組む。
+require "json"
+
+module Glslkit
+  module WebGL
+    class Context
+      LIVE_RELOAD_POLL_INTERVAL_MS = 500
+      LIVE_RELOAD_DIGESTS_PATH = "/glslkit/digests.json"
+
+      # ctx.live_reload("neon", on_error: ->(e) { ... }, on_reload: -> { ... })
+      #
+      # 決定4: 1ページにつきsetIntervalは1本。2回目以降の呼び出しは監視対象の
+      # リストに追加するだけで、既存のポーリングに乗せる。
+      def live_reload(name, on_error: nil, on_reload: nil)
+        @live_reload_watches ||= {}
+        @live_reload_watches[name.to_s] = {digest: nil, on_error: on_error, on_reload: on_reload}
+        start_live_reload_polling unless @live_reload_interval_id
+        self
+      end
+
+      private
+
+      def start_live_reload_polling
+        tick = proc { poll_live_reload_digests }
+        @live_reload_interval_id = JS.global.call(:setInterval, tick, LIVE_RELOAD_POLL_INTERVAL_MS)
+      end
+
+      def poll_live_reload_digests
+        fetch_json(LIVE_RELOAD_DIGESTS_PATH,
+          on_success: ->(digests) { apply_live_reload_digests(digests) },
+          on_error: ->(error) { @live_reload_watches.each_value { |watch| watch[:on_error]&.call(error) } })
+      end
+
+      # digestが変わっていないプログラムは本体を取得しない。
+      def apply_live_reload_digests(digests)
+        @live_reload_watches.each do |name, watch|
+          new_digest = digests[name]
+          next if new_digest.nil? || new_digest == watch[:digest]
+
+          fetch_and_reload_program(name, watch)
+        end
+      end
+
+      def fetch_and_reload_program(name, watch)
+        fetch_json("/glslkit/programs/#{name}.json",
+          on_success: ->(payload) { apply_live_reload_payload(name, watch, payload) },
+          on_error: ->(error) { watch[:on_error]&.call(error) })
+      end
+
+      # 失敗時に既存の状態を壊さないこと(§4.1)。reload_programが
+      # CompileError/LinkError/ReloadIncompatibleErrorを投げても、ここで
+      # 捕まえてon_errorへ回すだけで、監視ループ自体は止めない。
+      def apply_live_reload_payload(name, watch, payload)
+        watch[:digest] = payload["source_digest"]
+
+        if payload.key?("error")
+          watch[:on_error]&.call(payload.fetch("error"))
+          return
+        end
+
+        source_maps = payload.fetch("source_maps")
+        result = reload_program(name,
+          vertex: payload.fetch("vertex"), fragment: payload.fetch("fragment"),
+          manifest: payload.fetch("manifest"),
+          source_maps: {vertex: source_maps.fetch("vertex"), fragment: source_maps.fetch("fragment")})
+        watch[:on_reload]&.call(result)
+      rescue => e
+        watch[:on_error]&.call(e)
+      end
+
+      # fetch → .then(response) → text() → .then(text) → JSON.parse という
+      # 定型処理をまとめる。ok?がfalseの応答も、rejectされたPromiseと同様に
+      # on_errorへ回す。
+      def fetch_json(path, on_success:, on_error:)
+        on_response = proc do |response|
+          if response[:ok] == JS::True
+            response.call(:text)
+          else
+            on_error.call("fetch #{path} failed: status=#{response[:status]}")
+            nil
+          end
+        end
+        on_text = proc do |text|
+          next if text.nil?
+
+          begin
+            on_success.call(JSON.parse(text.to_s))
+          rescue => e
+            on_error.call(e)
+          end
+        end
+        on_rejected = proc { |error| on_error.call(error) }
+        JS.global.fetch(path).call(:then, on_response).call(:then, on_text).call(:catch, on_rejected)
+      end
+    end
+  end
+end

data/lib/glslkit/webgl/matrix.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Glslkit
+  module WebGL
+    module Matrix
+      module_function
+
+      def identity!(out)
+        16.times { |i| out[i] = 0.0 }
+        out[0] = out[5] = out[10] = out[15] = 1.0
+        out
+      end
+
+      def rotation_z!(out, radians)
+        cosine = Math.cos(radians)
+        sine = Math.sin(radians)
+        identity!(out)
+        out[0] = cosine
+        out[1] = sine
+        out[4] = -sine
+        out[5] = cosine
+        out
+      end
+
+      def rotation_y!(out, radians)
+        cosine = Math.cos(radians)
+        sine = Math.sin(radians)
+        identity!(out)
+        out[0] = cosine
+        out[2] = -sine
+        out[8] = sine
+        out[10] = cosine
+        out
+      end
+
+      def translation!(out, x, y, z)
+        identity!(out)
+        out[12] = x
+        out[13] = y
+        out[14] = z
+        out
+      end
+
+      def multiply!(out, left, right)
+        4.times do |column|
+          offset = column * 4
+          r0 = right[offset].to_f
+          r1 = right[offset + 1].to_f
+          r2 = right[offset + 2].to_f
+          r3 = right[offset + 3].to_f
+          out[offset] = left[0].to_f * r0 + left[4].to_f * r1 + left[8].to_f * r2 + left[12].to_f * r3
+          out[offset + 1] = left[1].to_f * r0 + left[5].to_f * r1 + left[9].to_f * r2 + left[13].to_f * r3
+          out[offset + 2] = left[2].to_f * r0 + left[6].to_f * r1 + left[10].to_f * r2 + left[14].to_f * r3
+          out[offset + 3] = left[3].to_f * r0 + left[7].to_f * r1 + left[11].to_f * r2 + left[15].to_f * r3
+        end
+        out
+      end
+
+      def perspective!(out, fovy, aspect, near, far)
+        f = 1.0 / Math.tan(fovy / 2.0)
+        16.times { |i| out[i] = 0.0 }
+        out[0] = f / aspect
+        out[5] = f
+        out[11] = -1.0
+        if far
+          nf = 1.0 / (near - far)
+          out[10] = (far + near) * nf
+          out[14] = 2.0 * far * near * nf
+        else
+          out[10] = -1.0
+          out[14] = -2.0 * near
+        end
+        out
+      end
+    end
+  end
+end

data/lib/glslkit/webgl/program.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Glslkit
+  module WebGL
+    class Program
+      LOG_LINE_PATTERNS = [
+        /(?:ERROR|WARNING):\s*\d+:(\d+):\s*(.*)/,
+        /\b\d+\((\d+)\)\s*:\s*(?:error|warning)?\s*(.*)/i
+      ].freeze
+
+      attr_reader :handle, :attribute_locations
+
+      def initialize(gl, manifest_program, vertex:, fragment:, source_maps: {}, state: nil)
+        @gl = gl
+        @state = state || {program: nil}
+        @manifest_program = manifest_program
+        @source_maps = source_maps
+        @handle = build(vertex, fragment)
+        @uniform_indices = {}
+        @uniform_locations = []
+        @uniform_setters = []
+        @uniform_matrix = []
+        @uniform_lengths = []
+        @uniform_buffers = []
+        prepare_uniforms
+        prepare_attributes
+      end
+
+      def use
+        unless @state[:program].equal?(@handle)
+          @gl.call(:useProgram, @handle)
+          @state[:program] = @handle
+        end
+        self
+      end
+
+      def set(name, value)
+        index = @uniform_indices[name.to_sym]
+        raise UnknownUniformError, "uniform not found in manifest: #{name}" unless index
+
+        location = @uniform_locations[index]
+        return self if null_location?(location)
+
+        use
+        buffer = @uniform_buffers[index]
+        expected = @uniform_lengths[index]
+        copy_value(buffer, value, expected, name)
+        setter = @uniform_setters[index]
+        if @uniform_matrix[index]
+          @gl.call(setter, location, false, buffer)
+        else
+          @gl.call(setter, location, buffer)
+        end
+        self
+      end
+
+      # M11d: reload時にuniform値を引き継ぐため(SPEC-livereload.md §4.3)の、
+      # 名前ごとの現在値スナップショット。{name_sym => {type:, element_count:, values:}}。
+      # typeは互換性判定にのみ使う(値そのものには使わない)。
+      def uniform_snapshot
+        @manifest_program.fetch("uniforms").each_with_object({}) do |uniform, snapshot|
+          name = uniform.fetch("name").to_sym
+          index = @uniform_indices.fetch(name)
+          count = @uniform_lengths[index]
+          buffer = @uniform_buffers[index]
+          snapshot[name] = {
+            type: uniform.fetch("type"),
+            element_count: count,
+            values: Array.new(count) { |i| buffer[i].to_f }
+          }
+        end
+      end
+
+      # reload後、旧Program(old_program)が持っていたuniform値を自分自身に
+      # 復元する。名前・type・element_countがすべて一致するものだけを復元し、
+      # 一致しないものは戻り値に集めて呼び出し側(Context)に返す。R4には
+      # 反しない(初期化時1回の書き込みであり、毎フレームの再確保ではない)。
+      def restore_uniforms_from(old_program)
+        new_snapshot = uniform_snapshot
+        discarded = []
+
+        old_program.uniform_snapshot.each do |name, old_entry|
+          new_entry = new_snapshot[name]
+          if new_entry.nil?
+            discarded << {name: name, reason: :removed}
+          elsif new_entry[:type] != old_entry[:type] || new_entry[:element_count] != old_entry[:element_count]
+            discarded << {name: name, reason: :type_changed, from: old_entry[:type], to: new_entry[:type]}
+          else
+            set(name, old_entry[:values])
+          end
+        end
+
+        discarded
+      end
+
+      private
+
+      def build(vertex_source, fragment_source)
+        vertex = compile(:vertex, vertex_source, @gl[:VERTEX_SHADER])
+        fragment = compile(:fragment, fragment_source, @gl[:FRAGMENT_SHADER])
+        program = @gl.call(:createProgram)
+        @gl.call(:attachShader, program, vertex)
+        @gl.call(:attachShader, program, fragment)
+        @gl.call(:linkProgram, program)
+        linked = @gl.call(:getProgramParameter, program, @gl[:LINK_STATUS])
+        unless js_truthy?(linked)
+          raw_log = @gl.call(:getProgramInfoLog, program).to_s
+          @gl.call(:deleteProgram, program)
+          raise LinkError, raw_log
+        end
+        @gl.call(:deleteShader, vertex)
+        @gl.call(:deleteShader, fragment)
+        program
+      end
+
+      def compile(stage, source, shader_type)
+        shader = @gl.call(:createShader, shader_type)
+        @gl.call(:shaderSource, shader, source)
+        @gl.call(:compileShader, shader)
+        compiled = @gl.call(:getShaderParameter, shader, @gl[:COMPILE_STATUS])
+        return shader if js_truthy?(compiled)
+
+        raw_log = @gl.call(:getShaderInfoLog, shader).to_s
+        @gl.call(:deleteShader, shader)
+        line, detail = parse_log(raw_log)
+        resolved = line && @source_maps[stage]&.resolve(line)
+        file, original_line = resolved if resolved
+        raise CompileError.new(
+          stage: stage,
+          raw_log: raw_log,
+          file: file,
+          line: original_line,
+          detail: detail
+        )
+      end
+
+      def parse_log(raw_log)
+        raw_log.each_line do |line|
+          LOG_LINE_PATTERNS.each do |pattern|
+            match = pattern.match(line)
+            return [match[1].to_i, match[2].to_s.strip] if match
+          end
+        end
+        [nil, nil]
+      end
+
+      def prepare_uniforms
+        float32 = JS.global[:Float32Array]
+        int32 = JS.global[:Int32Array]
+        uint32 = JS.global[:Uint32Array]
+        @manifest_program.fetch("uniforms").each_with_index do |uniform, index|
+          name = uniform.fetch("name")
+          @uniform_indices[name.to_sym] = index
+          @uniform_locations[index] = @gl.call(:getUniformLocation, @handle, name)
+          setter = uniform.fetch("setter").to_sym
+          @uniform_setters[index] = setter
+          @uniform_matrix[index] = uniform.fetch("matrix")
+          @uniform_lengths[index] = uniform.fetch("element_count")
+          constructor =
+            if setter.to_s.end_with?("uiv")
+              uint32
+            elsif setter.to_s.end_with?("iv")
+              int32
+            else
+              float32
+            end
+          @uniform_buffers[index] = constructor.new(@uniform_lengths[index])
+        end
+      end
+
+      def prepare_attributes
+        @attribute_locations = {}
+        @manifest_program.fetch("attributes").each do |attribute|
+          name = attribute.fetch("name")
+          location = attribute["location"]
+          location = @gl.call(:getAttribLocation, @handle, name).to_i if location.nil?
+          @attribute_locations[name.to_sym] = location
+        end
+      end
+
+      def copy_value(buffer, value, expected, name)
+        if expected == 1 && !value.respond_to?(:length)
+          buffer[0] = value
+          return
+        end
+
+        actual = value[:length].to_i if value.is_a?(JS::Object)
+        actual ||= value.length
+        unless actual == expected
+          raise UniformLengthError,
+            "uniform #{name} expects #{expected} elements, got #{actual} from #{value}"
+        end
+        expected.times { |i| buffer[i] = value[i] }
+      end
+
+      def null_location?(location)
+        location.nil? || location == JS::Null || location == JS::Undefined
+      end
+
+      def js_truthy?(value)
+        value == true || value == JS::True
+      end
+    end
+  end
+end

data/lib/glslkit/webgl/reload_result.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Glslkit
+  module WebGL
+    # Context#reload_program(M11d、SPEC-livereload.md §4)の戻り値。
+    # コンパイル/リンクの失敗(CompileError/LinkError)とattribute locationの
+    # 不一致(ReloadIncompatibleError)は例外として投げる — これらは
+    # 「差し替え自体が起きなかった」ことを意味し、呼び出し側が旧Programを
+    # 使い続けるという単純な話で終わるため。
+    #
+    # ReloadResultが表すのは、差し替え自体は成功したが、一部のuniform値を
+    # 引き継げなかった(名前が消えた/型やelement_countが変わった)という、
+    # 差し替え後も動作は継続する軽微な話(§4.3)。診断はerrorにはならない
+    # ため、ok?は常にtrueになる想定だが、将来の拡張に備えて診断のseverityを
+    # 見て判定する形にしている。
+    class ReloadResult
+      attr_reader :diagnostics
+
+      def initialize(diagnostics: [])
+        @diagnostics = diagnostics
+      end
+
+      def ok?
+        diagnostics.none? { |d| d.severity == :error }
+      end
+    end
+  end
+end

data/lib/glslkit/webgl/texture.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Glslkit
+  module WebGL
+    class Texture
+      attr_reader :unit
+
+      def initialize(gl, width:, height:, data:, unit: 0)
+        @gl = gl
+        @unit = unit
+        @handle = gl.call(:createTexture)
+        pixels = JS.global[:Uint8Array].call(:from, data.to_js)
+        bind
+        gl.call(:texImage2D, gl[:TEXTURE_2D], 0, gl[:RGBA], width, height, 0,
+          gl[:RGBA], gl[:UNSIGNED_BYTE], pixels)
+        gl.call(:texParameteri, gl[:TEXTURE_2D], gl[:TEXTURE_MIN_FILTER], gl[:NEAREST])
+        gl.call(:texParameteri, gl[:TEXTURE_2D], gl[:TEXTURE_MAG_FILTER], gl[:NEAREST])
+      end
+
+      def bind
+        @gl.call(:activeTexture, @gl[:TEXTURE0].to_i + @unit)
+        @gl.call(:bindTexture, @gl[:TEXTURE_2D], @handle)
+        self
+      end
+    end
+  end
+end

data/lib/glslkit/webgl/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Glslkit
+  module WebGL
+    VERSION = "0.1.0.pre"
+  end
+end

data/lib/glslkit/webgl.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "webgl/version"
+
+begin
+  require "js"
+rescue LoadError => error
+  raise LoadError,
+    "glslkit-webgl requires a ruby.wasm runtime (the `js` gem, which ships with " \
+    "ruby.wasm's browser builds, could not be loaded). This gem cannot run under " \
+    "a normal CRuby/JRuby/TruffleRuby install — it only runs inside a browser " \
+    "via ruby.wasm. See https://github.com/ruby/ruby.wasm for how to set that up.",
+    error.backtrace
+end
+
+# glslkit-webgl は core の狭い入口(digestをロードしない)を使う。
+# 前処理・解析・digest計算が要る `require "glslkit"` は使わないこと(M8g)。
+begin
+  require "glslkit/runtime"
+rescue LoadError => error
+  raise unless error.path == "glslkit/runtime"
+
+  # Source-tree browser samples are loaded by JS::RequireRemote rather than an
+  # installed gem. Packaged users take the normal require path above.
+  require_relative "../../../core/lib/glslkit/runtime"
+end
+
+require_relative "webgl/errors"
+require_relative "webgl/matrix"
+require_relative "webgl/reload_result"
+require_relative "webgl/program"
+require_relative "webgl/geometry"
+require_relative "webgl/texture"
+require_relative "webgl/context"
+
+module Glslkit
+  module WebGL
+    class << self
+      attr_accessor :debug
+
+      def context(selector)
+        Context.from_selector(selector)
+      end
+    end
+
+    self.debug = false
+  end
+end

data/sample/app.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "../lib/glslkit/webgl"
+require_relative "generated/cube_shaders"
+
+POSITIONS = [
+  -1, -1, -1, 1, -1, -1, 1, 1, -1, -1, 1, -1,
+  -1, -1, 1, 1, -1, 1, 1, 1, 1, -1, 1, 1
+].freeze
+UVS = [0, 0, 1, 0, 1, 1, 0, 1, 0, 0, 1, 0, 1, 1, 0, 1].freeze
+INDICES = [
+  0, 1, 2, 0, 2, 3, 4, 6, 5, 4, 7, 6,
+  0, 4, 5, 0, 5, 1, 3, 2, 6, 3, 6, 7,
+  1, 5, 6, 1, 6, 2, 0, 3, 7, 0, 7, 4
+].freeze
+PIXELS = [
+  255, 80, 120, 255, 40, 210, 255, 255,
+  40, 210, 255, 255, 255, 80, 120, 255
+].freeze
+
+ctx = Glslkit::WebGL.context("#canvas")
+program = ctx.program(Glslkit::Manifest.parse(CubeShaders::MANIFEST), "cube",
+  vertex: CubeShaders::VERTEX, fragment: CubeShaders::FRAGMENT,
+  source_maps: {
+    vertex: Glslkit::SourceMap.from_h(CubeShaders::SOURCE_MAPS[:vertex]),
+    fragment: Glslkit::SourceMap.from_h(CubeShaders::SOURCE_MAPS[:fragment])
+  })
+geometry = ctx.geometry(program: program, attributes: {
+  a_position: {data: POSITIONS, components: 3}, a_uv: {data: UVS, components: 2}
+}, indices: INDICES)
+texture = ctx.texture2d(width: 2, height: 2, data: PIXELS, unit: 0)
+
+projection = Array.new(16, 0.0)
+view = Array.new(16, 0.0)
+model = Array.new(16, 0.0)
+view_model = Array.new(16, 0.0)
+mvp = Array.new(16, 0.0)
+Glslkit::WebGL::Matrix.perspective!(projection, Math::PI / 3.0, 1.0, 0.1, 100.0)
+Glslkit::WebGL::Matrix.translation!(view, 0.0, 0.0, -4.0)
+
+ctx.viewport
+ctx.depth_test = true
+program.set(:u_texture, texture.unit)
+ctx.loop do |seconds|
+  Glslkit::WebGL::Matrix.rotation_y!(model, seconds)
+  Glslkit::WebGL::Matrix.multiply!(view_model, view, model)
+  Glslkit::WebGL::Matrix.multiply!(mvp, projection, view_model)
+  program.set(:u_mvp, mvp)
+  texture.bind
+  ctx.clear(red: 0.04, green: 0.05, blue: 0.09)
+  ctx.draw(geometry)
+end

data/sample/error_panel.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# Glslkit::WebGL::CompileErrorから画面表示用のデータを組み立てる。DOMには
+# 一切触れない(webgl/test でDOM無しにユニットテストできるようにするため)。
+# `file`/`line`はresolveできなかった場合nilになりうる(M10a修正2)。
+# ここで必ずフォールバック文字列に変換し、呼び出し側(neon-error.rb)が
+# nilを直接扱わなくて済むようにする。
+module NeonErrorPanel
+  UNRESOLVED_FILE = "(unresolved — driver did not report a line inside a mapped segment)"
+  UNRESOLVED_LINE = "(unresolved)"
+
+  module_function
+
+  def describe(error)
+    {
+      stage: error.stage.to_s,
+      file: error.file || UNRESOLVED_FILE,
+      resolved: !error.file.nil?,
+      line: error.line ? error.line.to_s : UNRESOLVED_LINE,
+      message: error.message.to_s,
+      raw_log: error.raw_log.to_s
+    }
+  end
+
+  # M11f: ctx.live_reload の on_error に渡ってくる値は一様ではない
+  # (SPEC-livereload.md §4.4/§4.5)。
+  #   - Glslkit::WebGL::CompileError / LinkError / ReloadIncompatibleError
+  #     (クライアント側でreload_programが投げた例外)
+  #   - Hash({"kind" => "preprocess" | "validation", ...}、サーバ側の
+  #     programs/:name.json がコンパイル前に落ちたことを報告するペイロード。
+  #     M11cの§3.4参照)
+  #   - それ以外(ネットワーク断など、文字列やJSの値)
+  # これらを1つの表示用ハッシュに正規化する。DOMには一切触れない
+  # (describeと同じ理由)。
+  def describe_live_reload_error(error)
+    case error
+    when Glslkit::WebGL::CompileError
+      describe(error).merge(kind: "compile")
+    when Glslkit::WebGL::LinkError
+      {kind: "link", message: "shader link failed", raw_log: error.raw_log.to_s}
+    when Glslkit::WebGL::ReloadIncompatibleError
+      {kind: "incompatible", message: error.message.to_s}
+    when Hash
+      describe_server_payload(error)
+    else
+      {kind: "unknown", message: error.to_s}
+    end
+  end
+
+  def describe_server_payload(payload)
+    case payload["kind"]
+    when "validation"
+      diagnostics = payload.fetch("diagnostics", []).map { |d| describe_diagnostic(d) }
+      {kind: "validation", diagnostics: diagnostics}
+    when "preprocess"
+      {kind: "preprocess", message: payload["message"].to_s, error_class: payload["class"].to_s}
+    else
+      {kind: "unknown", message: payload.inspect}
+    end
+  end
+
+  def describe_diagnostic(diagnostic)
+    {
+      severity: diagnostic["severity"].to_s, code: diagnostic["code"].to_s, message: diagnostic["message"].to_s,
+      file: diagnostic["file"] || UNRESOLVED_FILE, line: diagnostic["line"] ? diagnostic["line"].to_s : UNRESOLVED_LINE
+    }
+  end
+end