glslkit-webgl 0.1.0.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6ae64d28127a6a9f72c2c3017ba1b7e11739e7f374634be7e2a6a6eecbf663a7
+  data.tar.gz: 152a82f8f5be95b90b2d15a8c9b5976d55737164e7d6b69060b89433cfcb56da
+SHA512:
+  metadata.gz: c97c9dcbd8d95bd2257241915974ee053994659281f49da8e78df7a4a2b594e377587410d31a7008f6ec994a3ee0b8c91be93a05339e93aecce6ad881409053b
+  data.tar.gz: 16c71ae9f9f16e146c5d82b4e4e8fbdab1af3ca6e584ab263576c87a929d88503d02d729758ff5ae18ead15a67dcdb75a627e40fb0ea68e5c0675b0e971ea5a1

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## [Unreleased]
+
+初回リリース (v0.1)。**ruby.wasm 環境専用。** 通常の CRuby/JRuby/TruffleRuby
+にはインストールできるが、`require "js"` に依存するため実行できない。
+
+### 追加
+
+- `Glslkit::WebGL::Context` — `glslkit` の reflection マニフェストから
+  Program/Geometry/Textureを構築。`getActiveUniform`/`getActiveAttrib` を
+  呼ばない。`ctx.loop` は `requestAnimationFrame` へ Ruby の `Proc` を直接渡す
+- `Glslkit::WebGL::Program` — uniform設定は再利用する型付き配列に書き込み、
+  毎フレームの新規確保を避ける。コンパイル/リンクエラーは
+  `Glslkit::WebGL::CompileError`/`LinkError` として、`SourceMap` 経由で
+  元ファイル名・行番号付きで発生する
+- `Glslkit::WebGL::Geometry` — 頂点データは構築時に型付き配列へ一括転送
+  (`Array#to_js` → `Float32Array.from`)。ミューテーションAPIは提供しない
+- `Glslkit::WebGL::Texture`、破壊的更新の行列ヘルパ (`Glslkit::WebGL::Matrix`)
+- `Glslkit::WebGL::Embed`(`rake glslkit:embed`)— `.vert`/`.frag` から
+  マニフェスト・SourceMap込みのデータ専用Rubyモジュールを生成し、ホスト側で
+  wasmに埋め込めるようにする
+- `Context#reload_program` / `#program_for` — 実行中のシェーダを
+  Geometry・uniform値を保ったまま差し替える。attribute locationが変わる等の
+  互換性が無い変更は `ReloadIncompatibleError` を投げる
+- `Glslkit::WebGL::LiveReload`(`require "glslkit/webgl/live_reload"`、
+  明示requireでのみ有効)— `glslkit-rails` のライブリロードエンドポイントを
+  ポーリングし、変更を検知したら自動で `reload_program` を呼ぶ
+- サンプル: 回転する立方体 (`sample/index.html`)、レイマーチングデモ
+  (`sample/neon.html`)、include先のコンパイルエラーが元ファイル名・行番号を
+  指すことを示すデモ (`sample/neon-error.html`)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kyubey1228
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,98 @@
+# glslkit-webgl
+
+`glslkit-webgl` is a WebGL2 runtime for Ruby programs running in a browser with
+ruby.wasm. It consumes a `glslkit` reflection manifest, caches WebGL references,
+and reports shader compiler errors as Ruby exceptions.
+
+## Quick start
+
+Serve this repository over HTTP and open `webgl/sample/index.html`. The sample
+draws a rotating, textured cube without application JavaScript, built from
+`webgl/sample/shaders/cube.{vert,frag}` via `rake glslkit:embed`.
+`webgl/sample/neon.html` is an animated fragment-shader raymarching demo, built
+from `webgl/sample/shaders/neon.*` the same way.
+`webgl/sample/neon-error.html` intentionally breaks `common/sdf.glsl` (an
+`#include`d file, not the top-level shader) to demonstrate that `CompileError`
+reports the original included file and line, with a button to switch back to
+the working shaders and start rendering.
+
+```html
+<canvas id="canvas" width="640" height="480"></canvas>
+<script src="/path/to/glslkit-webgl.js" data-entry="./app.rb"
+        data-ruby-version="4.0" data-wasm-wasi-version="2.10.1"></script>
+```
+
+The shim only starts ruby.wasm. `JS::RequireRemote` fetches Ruby files and all
+rendering logic remains in Ruby. `window.glslkitWebGLReady` settles when the entry
+file finishes loading. Packaged wasm builds should install both gems normally.
+
+## Runtime API
+
+```ruby
+require "glslkit/webgl"
+
+ctx = Glslkit::WebGL.context("#canvas")
+manifest = Glslkit::Manifest.parse(MANIFEST_JSON)
+program = ctx.program(manifest, "main", vertex: VERTEX_SOURCE,
+  fragment: FRAGMENT_SOURCE,
+  source_maps: {vertex: vertex_map, fragment: fragment_map})
+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: rgba_pixels, unit: 0)
+
+matrix = Array.new(16, 0.0)
+ctx.loop do |seconds|
+  Glslkit::WebGL::Matrix.rotation_z!(matrix, seconds)
+  program.set(:u_transform, matrix)
+  program.set(:u_texture, texture.unit)
+  texture.bind
+  ctx.draw(geometry)
+end
+```
+
+Unknown uniforms and incorrect `element_count` values raise immediately.
+Locations optimized away by GLSL are silently ignored. Geometry data is uploaded
+once with typed-array `from`; there is intentionally no mutation API.
+
+## Shader errors and source maps
+
+Pass each stage's `Glslkit::SourceMap` through `source_maps:`. Recognized driver
+line numbers are resolved to the original included file. `CompileError` exposes
+`stage`, `file`, `line`, and `raw_log`. Unknown log formats still raise, with
+`file` and `line` set to `nil`. Link failures raise `LinkError`. JS log values are
+converted with `#to_s` before parsing.
+
+## Debug mode
+
+Set `Glslkit::WebGL.debug = true` to call `getError` once at each frame end. It
+defaults to `false` and should not remain enabled because `getError` synchronizes
+the WebGL command queue.
+
+## Performance and scope limits
+
+The following CPU-side workloads are unsupported in v0.1:
+
+- replacing vertex data every frame;
+- CPU skinning;
+- CPU morph-target interpolation;
+- CPU-updated particle geometry.
+
+Transferring 100,000 floats took 18.8 ms in the design measurements, exceeding a
+60 fps frame budget. Keep geometry static, deform vertices in shaders, and send
+only matrices and weights through uniforms. Per-frame bone-matrix calculation
+cost remains unmeasured.
+
+The runtime is WebGL2-only. It has no WebGL1 fallback, scene graph, material
+system, or glTF/VRM loader.
+
+## JS value safety (R6)
+
+Never call `#class` on a value that may be a `JS::Object`; JavaScript primitives
+can fail in `Reflect.has`. Use `is_a?(JS::Object)` for checks and `#inspect`,
+`#typeof`, or `#to_s` for display. A test scans implementation Ruby files for
+accidental `.class` calls.
+
+Normal CRuby fails immediately with a clear message because ruby.wasm's `js`
+library is required.

data/glslkit-webgl.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "lib/glslkit/webgl/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "glslkit-webgl"
+  spec.version = Glslkit::WebGL::VERSION
+  spec.authors = ["kyubey1228"]
+  spec.email = ["kyuuka1228@gmail.com"]
+
+  spec.summary = "ruby.wasm WebGL2 binding that consumes glslkit reflection manifests"
+  spec.description = "Lets you write WebGL2 rendering code entirely in Ruby, running under " \
+    "ruby.wasm in the browser. Resolves uniform/attribute locations from a glslkit " \
+    "reflection manifest instead of calling getActiveUniform, and surfaces shader " \
+    "compile errors as Ruby exceptions pointing at the original file and line. " \
+    "REQUIRES a ruby.wasm runtime (the `js` gem) to run — it installs under a normal " \
+    "CRuby/JRuby/TruffleRuby, but raises a clear LoadError instead of working there. " \
+    "This gem is meant to be bundled into a ruby.wasm build (see README), not required " \
+    "from a regular Ruby process."
+  spec.homepage = "https://github.com/kyubey1228/glslkit"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "#{spec.homepage}/tree/main/webgl"
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/webgl/CHANGELOG.md"
+
+  spec.files = Dir.glob("lib/**/*.rb") + Dir.glob("shim/**/*.js") + Dir.glob("sample/**/*") +
+    ["glslkit-webgl.gemspec", "README.md", "CHANGELOG.md", "LICENSE.txt"]
+  spec.require_paths = ["lib"]
+
+  # M12c: `~> 0.1.0` は `Gem::Requirement` の仕様上プレリリース版を一切
+  # 満たさない(`"~> 0.1.0".satisfied_by?("0.1.0.pre")` は常にfalse)。
+  # 0.1.0.pre のリリース期間中だけこの範囲にし、正式な0.1.0を切ったら
+  # `~> 0.1.0` に戻すこと。
+  spec.add_dependency "glslkit", ">= 0.1.0.pre", "< 0.2.0"
+end

data/lib/glslkit/webgl/context.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+module Glslkit
+  module WebGL
+    class Context
+      def self.from_selector(selector)
+        document = JS.global[:document]
+        canvas = document.call(:querySelector, selector)
+        if canvas == JS::Null || canvas == JS::Undefined
+          raise UnsupportedError, "canvas not found: #{selector}"
+        end
+        gl = canvas.call(:getContext, "webgl2")
+        if gl == JS::Null || gl == JS::Undefined
+          raise UnsupportedError, "WebGL2 is not available for #{selector}"
+        end
+        new(gl, canvas)
+      end
+
+      # 手書きマニフェスト(M10a前調査5)はglslkitの検証を一切通らずに
+      # ここまで来られてしまう。M10eでそのことに一度だけ気付けるようにする。
+      # 例外にはしない(手書きマニフェストそのものを禁止する話ではない)。
+      # プロセス内で1回だけ出す — Context.debugとは独立の、常時の警告。
+      def self.warn_missing_generator_once
+        return if @warned_missing_generator
+
+        @warned_missing_generator = true
+        warn "manifest has no generator field; hand-written manifests bypass " \
+          "glslkit's validation. Use `rake glslkit:embed`."
+      end
+
+      def initialize(gl, canvas)
+        @gl = gl
+        @canvas = canvas
+        @performance = JS.global[:performance]
+        @request_animation_frame = JS.global
+        @state = {program: nil}
+        # M11d(reload_program、SPEC-livereload.md §4)専用の追跡状態。
+        # development専用の機能であり、リークは許容する
+        # (production相当の環境ではlive_reloadをrequireせず、ここが増え
+        # 続ける経路自体を使わないため実害が無い。§4.1コメント参照)。
+        @programs = {} # name(String) => Program
+        @program_names = {}.compare_by_identity # Program => name(String)
+        @geometries = Hash.new { |h, k| h[k] = [] } # name(String) => [Geometry]
+      end
+
+      def width
+        @canvas[:width].to_i
+      end
+
+      def height
+        @canvas[:height].to_i
+      end
+
+      def program(manifest, name, vertex:, fragment:, source_maps: {})
+        manifest_hash = manifest.respond_to?(:to_h) ? manifest.to_h : manifest
+        self.class.warn_missing_generator_once unless manifest_hash.key?("generator")
+        entry = manifest_hash.fetch("programs").fetch(name.to_s) do
+          raise UnknownProgramError, "program not found in manifest: #{name}"
+        end
+        normalized_maps = source_maps.each_with_object({}) do |(stage, map), maps|
+          maps[stage.to_sym] = map.is_a?(Hash) ? Glslkit::SourceMap.from_h(map) : map
+        end
+        created = Program.new(@gl, entry,
+          vertex: vertex, fragment: fragment, source_maps: normalized_maps, state: @state)
+        register_program(name.to_s, created)
+        @current_program = created
+      end
+
+      # 名前で追跡しているProgramを取り出す(ctx.program/ctx.reload_programが
+      # 登録したもの)。M11e: reload_program自体はProgramオブジェクトを
+      # 返さない(ReloadResultを返す)ため、live_reloadを使う場合はreload後も
+      # 「その名前の現在のProgram」をこれで引き直さないと、毎フレームの
+      # uniform設定(program.set(:u_time, ...)等)が古い(差し替え済みで
+      # 二度と使われない)Programオブジェクトに向いたままになってしまう。
+      # 追跡されていない名前ならnil。
+      def program_for(name)
+        @programs[name.to_s]
+      end
+
+      def geometry(attributes:, indices: nil, program: nil, mode: nil)
+        target = program || @current_program
+        raise UnknownProgramError, "create a program before creating geometry" unless target
+
+        created = Geometry.new(@gl, target, attributes: attributes, indices: indices, mode: mode)
+        program_name = @program_names[target]
+        @geometries[program_name] << created if program_name
+        created
+      end
+
+      # M11d: Program単体ではなくContextの責務(SPEC-livereload.md 決定2)。
+      # 新しいシェーダのコンパイル・リンクが両方成功して初めて内部の
+      # ハンドルを差し替える。失敗時は古いProgramのまま
+      # CompileError/LinkErrorをそのまま投げる(§4.1)。
+      #
+      # attribute locationが新旧で変わっていた場合は、既存のVAOをそのまま
+      # 使うと壊れた描画になるため、ReloadIncompatibleErrorを投げて
+      # ページのリロードを促す(§4.2)。無言で壊れた描画を続けない。
+      #
+      # uniform値は名前ベースで引き継ぐ(§4.3)。名前・type・element_countが
+      # すべて一致するものだけ復元し、それ以外は破棄してdiagnosticsに
+      # 載せる(例外にはしない)。戻り値のResult#ok?はこの診断だけを見る —
+      # コンパイル/リンク/location不一致は例外なので、ここまで来た時点で
+      # 差し替え自体は成功している。
+      def reload_program(name, vertex:, fragment:, manifest:, source_maps: {})
+        key = name.to_s
+        old_program = @programs.fetch(key) do
+          raise UnknownProgramError, "no such program to reload (never created via Context#program): #{name}"
+        end
+
+        manifest_hash = manifest.respond_to?(:to_h) ? manifest.to_h : manifest
+        entry = manifest_hash.fetch("programs").fetch(key) do
+          raise UnknownProgramError, "program not found in manifest: #{name}"
+        end
+        normalized_maps = source_maps.each_with_object({}) do |(stage, map), maps|
+          maps[stage.to_sym] = map.is_a?(Hash) ? Glslkit::SourceMap.from_h(map) : map
+        end
+
+        new_program = Program.new(@gl, entry,
+          vertex: vertex, fragment: fragment, source_maps: normalized_maps, state: @state)
+
+        check_geometry_compatibility!(key, new_program)
+
+        discarded = new_program.restore_uniforms_from(old_program)
+        diagnostics = discarded.map { |info| uniform_discard_diagnostic(key, info) }
+
+        @programs[key] = new_program
+        @program_names.delete(old_program)
+        @program_names[new_program] = key
+        @current_program = new_program if @current_program.equal?(old_program)
+
+        ReloadResult.new(diagnostics: diagnostics)
+      end
+
+      def texture2d(width:, height:, data:, unit: 0)
+        Texture.new(@gl, width: width, height: height, data: data, unit: unit)
+      end
+
+      def viewport(width = nil, height = nil, x: 0, y: 0)
+        @gl.call(:viewport, x, y, width || self.width, height || self.height)
+        self
+      end
+
+      def depth_test=(enabled)
+        @gl.call(enabled ? :enable : :disable, @gl[:DEPTH_TEST])
+      end
+
+      def clear(red: 0.0, green: 0.0, blue: 0.0, alpha: 1.0, depth: true)
+        @gl.call(:clearColor, red, green, blue, alpha)
+        mask = @gl[:COLOR_BUFFER_BIT].to_i
+        mask |= @gl[:DEPTH_BUFFER_BIT].to_i if depth
+        @gl.call(:clear, mask)
+        self
+      end
+
+      def draw(geometry, program: nil)
+        target = program || @current_program
+        raise UnknownProgramError, "no program selected" unless target
+
+        target.use
+        @gl.call(:bindVertexArray, geometry.vao)
+        if geometry.indexed
+          @gl.call(:drawElements, geometry.mode, geometry.count, geometry.index_type, 0)
+        else
+          @gl.call(:drawArrays, geometry.mode, 0, geometry.count)
+        end
+        self
+      end
+
+      def loop(&block)
+        raise ArgumentError, "block required" unless block
+
+        start = @performance.call(:now).to_f
+        tick = nil
+        tick = proc do |timestamp|
+          block.call((timestamp.to_f - start) / 1000.0)
+          check_error if Glslkit::WebGL.debug
+          @request_animation_frame.call(:requestAnimationFrame, tick)
+        end
+        @request_animation_frame.call(:requestAnimationFrame, tick)
+        tick
+      end
+
+      private
+
+      def register_program(name, created)
+        @programs[name] = created
+        @program_names[created] = name
+      end
+
+      # このプログラム名で作られた全Geometryについて、構築時に使った
+      # attribute locationが新Programでも変わっていないかを確認する。
+      # 1つでも変わっていればReloadIncompatibleError。
+      def check_geometry_compatibility!(key, new_program)
+        @geometries[key].each do |geometry|
+          geometry.attribute_locations.each do |attribute_name, old_location|
+            new_location = new_program.attribute_locations[attribute_name]
+            next if new_location == old_location
+
+            raise ReloadIncompatibleError,
+              "attribute #{attribute_name} location changed (#{old_location.inspect} -> " \
+                "#{new_location.inspect}) while reloading #{key}; reload the page"
+          end
+        end
+      end
+
+      def uniform_discard_diagnostic(program_name, discarded)
+        message = case discarded.fetch(:reason)
+        when :removed
+          "uniform #{discarded.fetch(:name)} no longer exists in the reloaded shader; discarding its previous value"
+        when :type_changed
+          "uniform #{discarded.fetch(:name)} changed type (#{discarded.fetch(:from)} -> " \
+            "#{discarded.fetch(:to)}); discarding its previous value"
+        end
+        Glslkit::Diagnostic.new(
+          severity: :warning, code: "W101", message: message,
+          program: program_name, stage: nil, name: discarded.fetch(:name).to_s, file: nil, line: nil
+        )
+      end
+
+      def check_error
+        error = @gl.call(:getError).to_i
+        return if error == @gl[:NO_ERROR].to_i
+
+        raise Error, "WebGL error: #{error}"
+      end
+    end
+  end
+end

data/lib/glslkit/webgl/embed.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# 開発機(通常のCRuby)で実行するホスト側の生成ツール(M10a)。
+# File/Dir、Preprocessor/Reflection/Validator/digestなどcoreのフル機能を使う。
+# **`glslkit/webgl`(ブラウザ側ランタイムの入口)からは絶対にrequireしないこと。
+# ruby.wasm上では実行しない。** `rake glslkit:embed` からのみ使う想定。
+require "glslkit"
+require "pp"
+require "fileutils"
+
+module Glslkit
+  module WebGL
+    module Embed
+      # 冪等性のための固定値(実際の生成時刻ではない)。generated_atが実行の
+      # たびに変わるとgit diffがノイズになるため、実時刻の代わりにこれを使う。
+      EMBEDDED_TIMESTAMP = Time.at(0).utc
+
+      class ValidationError < StandardError; end
+      class InvalidProgramNameError < StandardError; end
+
+      # 有効なRubyの定数名(1つの識別子として)であることを要求する。
+      MODULE_NAME_PATTERN = /\A[A-Z][A-Za-z0-9_]*\z/
+
+      module_function
+
+      # shaders_dir配下の.vert/.fragペアごとに1つの.rbファイルをout_dirへ書き出す。
+      # 戻り値は [{name:, path:, warnings: [Glslkit::Diagnostic]}, ...]。
+      # Validatorでエラーがあれば書き出さず ValidationError を投げる
+      # (SPEC.md §8.6: Validator#validate は必ず Manifest.build より前)。
+      def generate(shaders_dir:, out_dir:)
+        root = File.expand_path(shaders_dir)
+        FileUtils.mkdir_p(out_dir)
+        resolver = Glslkit::Resolvers::FileSystem.new(load_paths: [root])
+
+        program_stage_paths(root).sort.map do |name, stages|
+          write_program(resolver, name, stages, out_dir)
+        end
+      end
+
+      # 実体(前処理→Program化→検証→Manifest組み立て)は Glslkit::Bundle が
+      # 持つ(M11b)。ここは Bundle の結果を見て、生成物として書き出すか
+      # 例外を投げるかを判断するだけの薄いラッパー。
+      def write_program(resolver, name, stages, out_dir)
+        module_name_for(name) # 実際にBundleを呼ぶ前に名前だけ先に検証する(fail fast)。
+        result = Glslkit::Bundle.build(
+          resolver: resolver, name: name, vertex: stages.fetch(:vertex), fragment: stages.fetch(:fragment),
+          line_directives: false, now: EMBEDDED_TIMESTAMP
+        )
+
+        case result.kind
+        when :preprocess
+          raise result.error
+        when :validation
+          errors = result.diagnostics.select(&:error?)
+          raise ValidationError, "glslkit:embed validation failed for #{name}:\n#{errors.join("\n")}"
+        end
+
+        # 警告は生成を止めない(エラーと違う)が、握り潰さず必ず標準エラーに出す。
+        # rakeタスク経由でなく Embed.generate を直接呼んだ場合でも見えるように、
+        # ここ(ライブラリ側)で出す。呼び出し側での二重出力は行わない。
+        warnings = result.diagnostics.select(&:warning?)
+        warnings.each { |warning| warn "[glslkit:embed] #{name}: #{warning}" }
+
+        out_path = File.join(out_dir, "#{name}_shaders.rb")
+        File.write(out_path, render(name: name, manifest: result.manifest, vertex: result.vertex, fragment: result.fragment))
+        {name: name, path: out_path, warnings: warnings}
+      end
+
+      # {"hello" => {vertex: "hello.vert", fragment: "hello.frag"}, ...} を返す。
+      # 同名の相方が無い.vert/.fragはスキップする(rails側のManifestBuilderと同じ扱い)。
+      def program_stage_paths(root)
+        by_name = Hash.new { |h, k| h[k] = {} }
+        Dir.glob("**/*.{vert,frag}", base: root).each do |relative|
+          ext = File.extname(relative)
+          stage = (ext == ".vert") ? :vertex : :fragment
+          by_name[relative.delete_suffix(ext)][stage] = relative
+        end
+        by_name.select { |_, stages| stages.key?(:vertex) && stages.key?(:fragment) }
+      end
+
+      def render(name:, manifest:, vertex:, fragment:)
+        module_name = module_name_for(name)
+        vertex_tag = unique_tag(vertex.code, "GLSLKIT_VERTEX_SRC")
+        fragment_tag = unique_tag(fragment.code, "GLSLKIT_FRAGMENT_SRC")
+
+        <<~RUBY
+          # frozen_string_literal: true
+
+          # 自動生成 (rake glslkit:embed)。手で編集しない。
+          # 再生成するには: bundle exec rake glslkit:embed[shaders_dir,out_dir]
+          #
+          # MANIFESTのgenerated_atが1970-01-01なのはバグではない。生成の
+          # 冪等性(同じ入力から同じ出力になること)のための固定値であり、
+          # 実行時刻を使うと同じ入力でも実行のたびにgit diffが出てしまう。
+          # 再現性はstages.*.digest(実データから計算される)が担保している。
+
+          module #{module_name}
+            VERTEX = #{heredoc_literal(vertex.code, vertex_tag, suffix: ".freeze")}
+
+            FRAGMENT = #{heredoc_literal(fragment.code, fragment_tag, suffix: ".freeze")}
+
+            MANIFEST = #{pp_literal(manifest)}.freeze
+
+            SOURCE_MAPS = {
+              vertex: #{pp_literal(vertex.source_map.to_h)},
+              fragment: #{pp_literal(fragment.source_map.to_h)}
+            }.freeze
+          end
+        RUBY
+      end
+
+      # 非squiggly(`<<~`ではなく`<<`)のシングルクォートヒアドキュメントを使う。
+      # `<<~`は最小共通インデントを削るため、code側の行のインデントが
+      # 想定と揃っていないとsource.codeとバイト一致しなくなる
+      # (例: 全行が2スペース下がっているとsource.codeの2スペースが
+      # 削られてしまう)。`<<`は一切ディデントしないため常にバイト一致する。
+      def heredoc_literal(code, tag, suffix: "")
+        "<<'#{tag}'#{suffix}\n#{code.chomp}\n#{tag}"
+      end
+
+      # codeの中に偶然tagと同じ行が現れても壊れないよう、衝突する限りtagをずらす。
+      # 冪等性のため決定的な連番だけを使う(object_idやSecureRandom等は不可)。
+      def unique_tag(code, base)
+        tag = base
+        suffix = 2
+        while code.lines.any? { |line| line.strip == tag }
+          tag = "#{base}_#{suffix}"
+          suffix += 1
+        end
+        tag
+      end
+
+      def pp_literal(value)
+        PP.pp(value, +"", 80).chomp
+      end
+
+      # 規則(修正4): プログラム名を非英数字(`_` `-` `.` 等、任意の連続)で
+      # 単語に分割し、各単語の先頭だけ大文字化して連結、末尾に "Shaders" を
+      # 付ける。例: "neon" -> "NeonShaders"、"pbr_lighting" -> "PbrLightingShaders"、
+      # "common.glsl" -> "CommonGlslShaders"(`.`も区切り文字として扱う)。
+      #
+      # 結果が有効なRubyの定数名でなければ(例: "2d-post" -> "2dPostShaders" は
+      # 数字始まりで無効)、無言で辻褄を合わせようとせず例外を投げる。
+      def module_name_for(name)
+        words = name.to_s.split(/[^a-zA-Z0-9]+/).reject(&:empty?)
+        camelized = words.map { |word| word[0].upcase + word[1..] }.join
+        module_name = "#{camelized}Shaders"
+        unless MODULE_NAME_PATTERN.match?(module_name)
+          raise InvalidProgramNameError,
+            "cannot derive a valid Ruby module name from program #{name.inspect} " \
+            "(got #{module_name.inspect}). Rename the .vert/.frag pair so the shared " \
+            "basename starts with a letter."
+        end
+        module_name
+      end
+    end
+  end
+end

data/lib/glslkit/webgl/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Glslkit
+  module WebGL
+    class Error < StandardError; end
+    class UnsupportedError < Error; end
+    class UnknownProgramError < Error; end
+    class UnknownUniformError < Error; end
+    class UniformLengthError < Error; end
+    class ShaderError < Error; end
+    # M11d: reload_program(SPEC-livereload.md §4.2)で新旧のattribute location
+    # が一致しない場合に投げる。既存のVAOをそのまま使い続けると壊れた描画に
+    # なるため、無言で続行せずページのリロードを促す。
+    class ReloadIncompatibleError < Error; end
+
+    class CompileError < ShaderError
+      attr_reader :stage, :file, :line, :raw_log
+
+      def initialize(stage:, raw_log:, file: nil, line: nil, detail: nil)
+        @stage = stage
+        @file = file
+        @line = line
+        @raw_log = raw_log.to_s
+        message = detail || @raw_log
+        message = "#{file}:#{line}: #{message}" if file && line
+        super(message)
+      end
+    end
+
+    class LinkError < ShaderError
+      attr_reader :raw_log
+
+      def initialize(raw_log)
+        @raw_log = raw_log.to_s
+        super(@raw_log)
+      end
+    end
+  end
+end