glslkit-rails 0.1.0.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d51a2bdc32253c7b684bee4903f3b0153631fa67be1e0cb440d70a51de043c51
+  data.tar.gz: 5352b0f62770e5914db0de3bbe4f1e38d6f0dddc6dd835f1e1bd0e713b091b5b
+SHA512:
+  metadata.gz: 93af6788fe949b71df49fe5d43a326123808e5d3a6a2621aac6f9c8d9e4ff91075caced01bdff0910dd22e9ee311013623fc4c5827a603cea0acc9328e783025
+  data.tar.gz: 4de7818cab7bb89ce2aed399c4b83130f3b43ab7b68f8ce525080135d2823e9c3ac4cafc8b95d828e366884f2f9b2898beae1c471fa5c024d1e44b62412f7458

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## [Unreleased]
+
+初回リリース (v0.1)。
+
+### 追加
+
+- `.glsl` / `.vert` / `.frag` をPropshaftのアセットとして登録
+  (content_type: `x-shader/x-vertex` / `x-shader/x-fragment` / `text/plain`)
+- `Glslkit::Rails::Compiler` — Propshaft経由で `#include` を解決した内容を配信
+  (developmentは毎リクエスト再処理、productionは`assets:precompile`時に1回)
+- `rake glslkit:reflect` と `assets:precompile` フックによる
+  `glsl-manifest.json` の自動生成
+- `Glslkit::Rails.manifest` — Ruby側からの読み取り窓口 (productionはメモ化)
+- `glsl_script_tag` / `glsl_manifest_tag` ビューヘルパー
+  (`</script>`エスケープ、CSP nonce対応)
+- `config.glslkit.validate` / `fail_on_warning` / `disabled_checks` —
+  `Glslkit::Validator` を `ManifestBuilder` に配線。development では検証結果を
+  ログに出すだけで失敗させないが、`assets:precompile` は検証エラーがあれば
+  `Glslkit::ValidationFailed` を投げてマニフェストを書き出す前に止める。
+  `rake glslkit:check` は設定に関わらず常に検証し、終了コードで判定できる
+- development専用のライブリロードエンドポイント(`ActionController::API`
+  ベースのEngine、決定7)。`GET /glslkit/digests.json`(ソースdigestのみ)と
+  `GET /glslkit/programs/:name.json`(シェーダ本文・マニフェスト・SourceMap
+  ・診断)。production相当の環境ではミドルウェア自体を挿入しないため一切
+  存在しない。`glslkit-webgl`側の`Context#reload_program`/`live_reload`と
+  組み合わせて使う(0.1.0の看板機能)

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,222 @@
+# glslkit-rails
+
+[`glslkit`](../core) を Rails (Propshaft) のアセットパイプラインに統合する gem。
+`.glsl` / `.vert` / `.frag` をアセットとして登録し、`#include` を解決した内容を
+配信し、`assets:precompile` 時にリフレクションマニフェストを書き出す。
+
+## インストール
+
+```ruby
+gem "glslkit-rails"
+```
+
+`glslkit`・`railties >= 7.1`・`propshaft >= 1.3.2` に依存する。
+
+## 設定
+
+```ruby
+# config/application.rb
+config.glslkit.paths = ["app/shaders"]          # デフォルト: app/shaders
+config.glslkit.minify = Rails.env.production?
+config.glslkit.line_directives = !Rails.env.production?
+config.glslkit.manifest_path = "glsl-manifest.json"
+```
+
+## アセットとしての配信
+
+`config.glslkit.paths` 配下のファイルはPropshaftのload_pathに追加され、
+`#include` を解決した内容がcontent_type `x-shader/x-vertex` /
+`x-shader/x-fragment` / `text/plain` で配信される。developmentでは
+毎リクエスト再処理し、productionでは `assets:precompile` 時に1回だけ処理する。
+
+## マニフェスト
+
+`rake assets:precompile` を実行すると、自動的に
+`public/assets/<config.glslkit.manifest_path>` (デフォルト `glsl-manifest.json`)
+にリフレクションマニフェストを書き出す。単体で実行する場合:
+
+```
+rake glslkit:reflect
+```
+
+Ruby側から読む場合:
+
+```ruby
+Glslkit::Rails.manifest # => Hash (productionでは読み込み結果をメモ化する)
+```
+
+## ビューヘルパー
+
+```erb
+<%= glsl_script_tag "pbr.vert" %>
+<%# => <script type="x-shader/x-vertex" id="pbr-vert">...</script> （インライン埋め込み） %>
+
+<%= glsl_manifest_tag %>
+<%# => <script type="application/json" id="glsl-manifest">...</script> %>
+```
+
+- インライン埋め込みの内容は `</script` をエスケープしている
+- そのリクエストでCSPが実際に有効な場合(`content_security_policy?`)、
+  自動的に `nonce` 属性を付与する。`nonce: true`/`false` で強制・抑止も
+  できる
+
+## 実践的な例
+
+`app/shaders/` にPBR風のマテリアルシェーダーを置く。共有partialの
+uniform block、複数テクスチャ、uniform配列を含む、より現実的な構成:
+
+```glsl
+# app/shaders/common/camera.glsl
+layout(std140, binding = 0) uniform Camera {
+  mat4 view;
+  mat4 projection;
+  vec3 eye_position;
+};
+```
+
+```glsl
+# app/shaders/material.vert
+#version 300 es
+#include "common/camera.glsl"
+
+layout(location = 0) in vec3 a_position;
+layout(location = 1) in vec3 a_normal;
+layout(location = 2) in vec2 a_uv;
+
+uniform mat4 u_model;
+
+out vec3 v_world_position;
+out vec3 v_normal;
+out vec2 v_uv;
+
+void main() {
+  vec4 world_position = u_model * vec4(a_position, 1.0);
+  v_world_position = world_position.xyz;
+  v_normal = mat3(u_model) * a_normal;
+  v_uv = a_uv;
+  gl_Position = projection * view * world_position;
+}
+```
+
+```glsl
+# app/shaders/material.frag
+#version 300 es
+precision highp float;
+#include "common/camera.glsl"
+
+in vec3 v_world_position;
+in vec3 v_normal;
+in vec2 v_uv;
+
+uniform sampler2D u_albedo_map;
+uniform vec4 u_base_color;
+uniform vec3 u_light_positions[4];
+uniform vec3 u_light_colors[4];
+uniform int u_light_count;
+
+out vec4 fragColor;
+
+void main() {
+  vec3 albedo = texture(u_albedo_map, v_uv).rgb * u_base_color.rgb;
+  vec3 n = normalize(v_normal);
+
+  vec3 total = vec3(0.0);
+  for (int i = 0; i < u_light_count; i++) {
+    vec3 to_light = normalize(u_light_positions[i] - v_world_position);
+    total += albedo * u_light_colors[i] * max(dot(n, to_light), 0.0);
+  }
+
+  fragColor = vec4(total, u_base_color.a);
+}
+```
+
+ビューでは平坦化済みシェーダーとマニフェストをまとめて埋め込む:
+
+```erb
+<%# app/views/scenes/show.html.erb %>
+<%= glsl_script_tag "material.vert" %>
+<%= glsl_script_tag "material.frag" %>
+<%= glsl_manifest_tag %>
+```
+
+`glsl_script_tag "material.vert"` は `#include "common/camera.glsl"` を
+解決した平坦化済みGLSLを `id="material-vert"` として埋め込み、
+`glsl_manifest_tag` は attribute の location・uniform の型/setter/配列サイズ・
+uniform blockのlayout/bindingを持つJSONを `id="glsl-manifest"` として埋め込む。
+
+JS側は、このマニフェストを消費するだけでWebGLプログラムをセットアップできる。
+**`gl.getActiveUniform`/`gl.getActiveAttrib` でイントロスペクションするループが
+不要になる**のがglslkitの狙い:
+
+```js
+function compileProgram(gl, manifestProgram, shaderElementIds) {
+  const vertexShader = compileShader(gl, gl.VERTEX_SHADER,
+    document.getElementById(shaderElementIds.vertex).textContent);
+  const fragmentShader = compileShader(gl, gl.FRAGMENT_SHADER,
+    document.getElementById(shaderElementIds.fragment).textContent);
+
+  const program = gl.createProgram();
+  gl.attachShader(program, vertexShader);
+  gl.attachShader(program, fragmentShader);
+  gl.linkProgram(program);
+  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+    throw new Error(gl.getProgramInfoLog(program));
+  }
+
+  const attributes = {};
+  for (const attr of manifestProgram.attributes) {
+    // location: null の場合だけ getAttribLocation を引けばよい
+    attributes[attr.name] = attr.location ?? gl.getAttribLocation(program, attr.name);
+  }
+
+  const uniforms = {};
+  let textureUnit = 0;
+  for (const uniform of manifestProgram.uniforms) {
+    const location = gl.getUniformLocation(program, uniform.name);
+    if (!location) continue; // 未使用uniformはコンパイラに削除されうる
+
+    if (uniform.sampler) {
+      const unit = textureUnit++;
+      uniforms[uniform.name] = (texture) => {
+        gl.activeTexture(gl.TEXTURE0 + unit);
+        gl.bindTexture(gl.TEXTURE_2D, texture);
+        gl.uniform1i(location, unit);
+      };
+    } else if (uniform.matrix) {
+      uniforms[uniform.name] = (value) => gl[uniform.setter](location, false, value);
+    } else {
+      uniforms[uniform.name] = (value) => gl[uniform.setter](location, value);
+    }
+  }
+
+  return {program, attributes, uniforms};
+}
+
+function compileShader(gl, type, source) {
+  const shader = gl.createShader(type);
+  gl.shaderSource(shader, source);
+  gl.compileShader(shader);
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    throw new Error(gl.getShaderInfoLog(shader));
+  }
+  return shader;
+}
+
+const manifest = JSON.parse(document.getElementById("glsl-manifest").textContent);
+const material = compileProgram(gl, manifest.programs.material, {
+  vertex: "material-vert",
+  fragment: "material-frag",
+});
+
+material.uniforms.u_model(modelMatrix);
+material.uniforms.u_base_color(new Float32Array([1, 1, 1, 1]));
+material.uniforms.u_albedo_map(albedoTexture);
+```
+
+`uniform.setter`/`uniform.matrix`/`uniform.sampler`はすべて
+[`Glslkit::Types`](../core#マニフェスト生成)由来で、`spec/schema/reflection-v1.json`
+に準拠する。
+
+## ライセンス
+
+[MIT](LICENSE.txt)

data/config/routes.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Glslkit::Rails::LiveReload::Engine 自身のルート(M11c、SPEC-livereload.md §3.3)。
+# このファイルは `Rails::Engine.root` が glslkit-rails 自体になるため、
+# ホストアプリの config/routes.rb とは無関係。ホストアプリへの接続は
+# glslkit-rails/lib/glslkit/rails/live_reload/mount.rb がミドルウェアとして
+# 行う(理由はそちらのコメントを参照)。
+Glslkit::Rails::LiveReload::Engine.routes.draw do
+  get "digests.json", to: "programs#digests"
+  get "programs/:name", to: "programs#show"
+end

data/glslkit-rails.gemspec

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "lib/glslkit/rails/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "glslkit-rails"
+  spec.version = Glslkit::Rails::VERSION
+  spec.authors = ["kyubey1228"]
+  spec.email = ["kyuuka1228@gmail.com"]
+
+  spec.summary = "Rails (Propshaft) integration for glslkit"
+  spec.description = "Registers .glsl/.vert/.frag assets with Propshaft, resolves " \
+    "#include directives at request/precompile time, and publishes a shader " \
+    "reflection manifest for consumption by views and JS at runtime."
+  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/rails"
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/rails/CHANGELOG.md"
+
+  spec.files = Dir.glob("lib/**/*.{rb,rake}") + Dir.glob("config/**/*.rb") +
+    ["glslkit-rails.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"
+  # M12b: `gem build`は無制限の">= 7.1"を非推奨としてwarnする。上限を
+  # 付ける案(CIで検証済みの範囲に基づき`< 9`等)も検討したが、採用しない。
+  # 上限は「まだ検証していない将来のメジャーバージョン」を無条件で締め出す
+  # ため、Rails側が実際には互換性を保ったままリリースしても、こちらが
+  # gemを更新するまで利用者は新しいRailsに上げられなくなる。CIで検証
+  # しているのはRuby 3.1→Rails 7.2、既定→Rails 8.1の範囲だが、それを
+  # 「動作保証の上限」と誤解させたくない。`gem build`の警告は許容する。
+  spec.add_dependency "railties", ">= 7.1"
+  # railties >= 7.1に推移的に含まれるため追加インストールは発生しないが、
+  # M11でActionController::APIベースのライブリロードEngineを提供するため
+  # 明示的に宣言する(SPEC-livereload.md 決定7)。
+  spec.add_dependency "actionpack", ">= 7.1"
+  # 実際にインストールされた1.3.2で確認したCompiler API
+  # (Propshaft::Compiler#compile(asset, input), #referenced_by(asset),
+  # Propshaft::Compilers#register(mime_type, klass)) に合わせて固定している。
+  # それより古い1.x系では確認していないため、より広い範囲は主張しない。
+  # 上限を付けない理由はrailties/actionpackと同じ。
+  spec.add_dependency "propshaft", ">= 1.3.2"
+end

data/lib/glslkit/rails/compiler.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "set"
+require "propshaft/compiler"
+
+module Glslkit
+  module Rails
+    # x-shader/x-vertex, x-shader/x-fragment, text/plain (§4.1) の3つに
+    # 登録される。前者2つは我々専用だが、text/plainはPropshaftが配信しうる
+    # 他のあらゆるプレーンテキストアセットと共有される — Propshaftはcompiler
+    # の登録をcontent_typeで紐付ける(拡張子ではない)ため、これが無いと
+    # このcompilerが無関係なtext/plainアセットにまで作用してしまう。
+    # 以下の拡張子ガードがそれを防いでいる。
+    class Compiler < ::Propshaft::Compiler
+      RELEVANT_EXTENSIONS = %w[.glsl .vert .frag].freeze
+
+      def compile(asset, input)
+        return input unless relevant?(asset)
+
+        source = preprocess(asset)
+        minify? ? Glslkit::Minifier.minify(source.code) : source.code
+      end
+
+      def referenced_by(asset)
+        return Set.new unless relevant?(asset)
+
+        source = preprocess(asset)
+        source.source_map.files.drop(1).filter_map { |path| load_path.find(path) }.to_set
+      end
+
+      private
+
+      def relevant?(asset)
+        RELEVANT_EXTENSIONS.include?(asset.logical_path.extname)
+      end
+
+      def preprocess(asset)
+        resolver = Glslkit::Resolvers::FileSystem.new(load_paths: load_path.paths.map(&:to_s))
+        Glslkit::Preprocessor.new(resolver: resolver, line_directives: line_directives?).process(asset.logical_path.to_s)
+      end
+
+      def glslkit_config
+        ::Rails.application.config.glslkit
+      end
+
+      def minify?
+        glslkit_config.minify
+      end
+
+      def line_directives?
+        glslkit_config.line_directives
+      end
+    end
+  end
+end

data/lib/glslkit/rails/helper.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Glslkit
+  module Rails
+    # ActionView上でincludeされるビューヘルパー (§4.3)。
+    module Helper
+      # <%= glsl_script_tag "pbr.vert" %>
+      # => <script type="x-shader/x-vertex" id="pbr-vert">...</script>
+      def glsl_script_tag(logical_path, **html_options)
+        asset = find_glsl_asset(logical_path)
+        html_options[:id] ||= glsl_script_id(logical_path.to_s)
+        html_options[:type] = asset.content_type.to_s
+        apply_glsl_nonce!(html_options)
+
+        content_tag(:script, escape_closing_script_tags(asset.compiled_content).html_safe, html_options)
+      end
+
+      # <%= glsl_manifest_tag %>
+      # => <script type="application/json" id="glsl-manifest">...</script>
+      def glsl_manifest_tag(**html_options)
+        html_options[:id] ||= "glsl-manifest"
+        html_options[:type] = "application/json"
+        apply_glsl_nonce!(html_options)
+
+        content_tag(:script, escape_closing_script_tags(Glslkit::Rails.manifest.to_json).html_safe, html_options)
+      end
+
+      private
+
+      def find_glsl_asset(logical_path)
+        ::Rails.application.assets.load_path.find(logical_path.to_s) ||
+          raise(ArgumentError, "no such glslkit asset: #{logical_path.inspect}")
+      end
+
+      # "pbr.vert" => "pbr-vert", "effects/glow.frag" => "effects-glow-frag"
+      def glsl_script_id(logical_path)
+        base = logical_path.sub(/\.(vert|frag|glsl)\z/, "")
+        "#{base.tr("/", "-")}-#{Regexp.last_match(1)}"
+      end
+
+      # Rails自身のjavascript_tagがJS_ESCAPE_MAPで"</" => '<\/'として行っている
+      # のと同じ理由・同じエスケープ: script要素の中身に文字通り"</"が現れると、
+      # 中身がJS/JSONとして妥当かどうかに関わらずHTMLパーサがそこでタグを
+      # 閉じてしまう。
+      def escape_closing_script_tags(content)
+        content.gsub("</", '<\/')
+      end
+
+      # true=強制、false=抑止、未指定ならこのリクエストでCSPが実際に有効な
+      # 場合だけ自動付与する。
+      #
+      # 当初は javascript_tag と全く同じ規約
+      # (ActionView::Helpers::JavaScriptHelper.auto_include_nonce)に合わせて
+      # いたが、これは config.content_security_policy_nonce_auto という
+      # Rails 8.1で新規追加された設定に依存しており、railties >= 7.1という
+      # このgemの依存下限では単純にメソッドが存在せずNoMethodErrorになる
+      # (CIでRuby 3.1 → Rails 7.2に解決された際に発覚)。content_security_policy?
+      # はRails 7.1時点から存在するので、こちらを使う。
+      def apply_glsl_nonce!(html_options)
+        if html_options[:nonce] == false
+          html_options.delete(:nonce)
+        elsif html_options[:nonce] == true ||
+            (!html_options.key?(:nonce) && respond_to?(:content_security_policy?) && content_security_policy?)
+          html_options[:nonce] = content_security_policy_nonce
+        end
+      end
+    end
+  end
+end

data/lib/glslkit/rails/live_reload/engine.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Glslkit
+  module Rails
+    module LiveReload
+      # ライブリロード用の2エンドポイント(§3.3)を提供するEngine。
+      # `isolate_namespace` によりホストアプリの `ProgramsController` 等と
+      # 衝突しない。マウントは `Railtie` が `config.glslkit.live_reload` を
+      # 見て判断する — このEngineが定義されていること自体は production でも
+      # 構わない(未マウントならルートは一切生成されない)。
+      #
+      # ルートは `rails/config/routes.rb`(このEngineの root 直下)に書いて
+      # いる。クラス本体で直接 `routes.draw do ... end` する形も動くが、
+      # それは一度きりの実行にしかならない。Rails::Engineは自身のroute_setを
+      # `app.routes_reloader.route_sets` に登録し、アプリのルートリロード
+      # サイクルで一緒に clear!/reload される — Rails 7.2ではこの
+      # サイクルで実際に一度 clear! されるため、クラス本体に書いた内容は
+      # 再度描画されず空になって消える(Rails 8.1では起きなかったため
+      # 実機検証で気づくまで見逃していた)。`config/routes.rb` ファイルに
+      # すればreload時に毎回 `load` され直すため、バージョンに関わらず安定する。
+      class Engine < ::Rails::Engine
+        isolate_namespace Glslkit::Rails::LiveReload
+      end
+    end
+  end
+end

data/lib/glslkit/rails/live_reload/known_files.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Glslkit
+  module Rails
+    module LiveReload
+      # プログラム名ごとに「最後に成功したビルドの files」をプロセス内メモリで
+      # 保持する。Glslkit::Bundle.build の `known_files:` に渡すためのもので、
+      # 前処理が失敗した回でも意味のある source_digest を計算できるようにする
+      # (SPEC-livereload.md §3.2 決定1)。development専用の機能なので永続化は
+      # 不要（プロセスを跨いだ保持は求めない）。
+      #
+      # development でも Puma は複数スレッドで動くため、単純な Hash への
+      # 読み書きではレースの余地がある。Mutex で保護する。
+      module KnownFiles
+        MUTEX = Mutex.new
+        @files_by_name = {}
+
+        module_function
+
+        def fetch(name)
+          MUTEX.synchronize { @files_by_name.fetch(name, []) }
+        end
+
+        def remember(name, files)
+          MUTEX.synchronize { @files_by_name[name] = files }
+        end
+      end
+    end
+  end
+end

data/lib/glslkit/rails/live_reload/mount.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Glslkit
+  module Rails
+    module LiveReload
+      # `/glslkit/*` へのリクエストをEngineへ振り分ける薄いミドルウェア。
+      #
+      # 当初は `app.routes.append { mount Engine => "/glslkit" }` を
+      # Railtieのinitializerから呼ぶ形にしていたが、これは
+      # `ActionDispatch::Routing::RouteSet#finalize!`(`@append`ブロックの
+      # 反映はここでしか起きない)が、そのinitializerより先に一度でも
+      # 走っているかどうかに依存してしまい、Railtie初期化順序次第で
+      # 再現性なく404になることが実機検証で判明した(finalize!後に
+      # appendしても再finalizeされない)。
+      #
+      # ミドルウェアスタックは全initializerが完了した後に一度だけ構築される
+      # ため、`config.middleware.use`によるこの登録はタイミング非依存で
+      # 安定して動く。Engine自体は本物のRails::Engineであり、内部の
+      # ルーティング(digests.json / programs/:name)は変更していない。
+      class Mount
+        PREFIX = "/glslkit"
+
+        def initialize(app, engine)
+          @app = app
+          @engine = engine
+        end
+
+        def call(env)
+          path = env["PATH_INFO"]
+          return @app.call(env) unless path == PREFIX || path.start_with?("#{PREFIX}/")
+
+          # 通常の `mount` がやるのと同じ書き換え(SCRIPT_NAME/PATH_INFOの
+          # 付け替え)を自分で行う。Engine自身のルート(`digests.json` /
+          # `programs/:name`)はプレフィックス無しのパスとして定義している
+          # ため、これをしないとEngine内のルーティングが一致しない。
+          rest = path.delete_prefix(PREFIX)
+          rest = "/#{rest}".squeeze("/")
+
+          env = env.merge(
+            "SCRIPT_NAME" => "#{env["SCRIPT_NAME"]}#{PREFIX}",
+            "PATH_INFO" => rest
+          )
+          @engine.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/glslkit/rails/live_reload/programs_controller.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "action_controller/api"
+
+module Glslkit
+  module Rails
+    module LiveReload
+      # ライブリロードのポーリング対象になる2つのエンドポイント(§3.3)。
+      # ActionController::API を使う(SPEC-livereload.md 決定7)。development
+      # でのみマウントされる(Engine#config.glslkit.live_reload が false の
+      # 場合は Railtie が一切マウントしないため、production ではこの
+      # コントローラ自体にルーティングで到達できない)。
+      #
+      # Preprocessor/Validator の失敗は200 + ペイロードで返す(§3.4)。それ以外の
+      # 想定外の例外はここで握り潰さず、素通しして500にする。
+      class ProgramsController < ActionController::API
+        # GET /glslkit/digests.json => {"neon" => "5059f642...", ...}
+        # ソースdigest(決定1)のみを返す軽量エンドポイント。
+        def digests
+          digests = ShaderPrograms.discover(rails_app).each_with_object({}) do |(name, stages), acc|
+            acc[name] = build(name, stages).source_digest
+          end
+          render json: digests
+        end
+
+        # GET /glslkit/programs/:name.json => §3.2 のJSON(失敗時は§3.4)。
+        def show
+          programs = ShaderPrograms.discover(rails_app)
+          stages = programs[params[:name]]
+          return head :not_found unless stages
+
+          render json: payload_for(build(params[:name], stages))
+        end
+
+        private
+
+        def rails_app
+          ::Rails.application
+        end
+
+        def glslkit_config
+          rails_app.config.glslkit
+        end
+
+        def build(name, stages)
+          resolver = Glslkit::Resolvers::FileSystem.new(load_paths: ShaderPrograms.roots(rails_app))
+          result = Glslkit::Bundle.build(
+            resolver: resolver, name: name, vertex: stages.fetch(:vertex), fragment: stages.fetch(:fragment),
+            line_directives: glslkit_config.line_directives, disabled_checks: glslkit_config.disabled_checks,
+            known_files: KnownFiles.fetch(name)
+          )
+          KnownFiles.remember(name, (result.vertex.source_map.files + result.fragment.source_map.files).uniq) if result.ok?
+          result
+        end
+
+        def payload_for(result)
+          return success_payload(result) if result.ok?
+
+          error_payload(result)
+        end
+
+        def success_payload(result)
+          {
+            name: result.name,
+            source_digest: result.source_digest,
+            vertex: result.vertex.code,
+            fragment: result.fragment.code,
+            manifest: result.manifest,
+            source_maps: {vertex: result.vertex.source_map.to_h, fragment: result.fragment.source_map.to_h},
+            diagnostics: result.diagnostics.map { |d| diagnostic_hash(d) }
+          }
+        end
+
+        def error_payload(result)
+          error = (result.kind == :validation) ? {diagnostics: result.diagnostics.map { |d| diagnostic_hash(d) }} : {message: result.error.message, class: result.error.class.name}
+
+          {name: result.name, source_digest: result.source_digest, error: {kind: result.kind.to_s, **error}}
+        end
+
+        def diagnostic_hash(diagnostic)
+          {
+            severity: diagnostic.severity, code: diagnostic.code, message: diagnostic.message,
+            program: diagnostic.program, stage: diagnostic.stage, name: diagnostic.name,
+            file: diagnostic.file, line: diagnostic.line
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/glslkit/rails/manifest_builder.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Glslkit
+  module Rails
+    # config.glslkit.paths 配下からvertex/fragmentのペアを検出し、その
+    # すべてについて reflection-v1.json のマニフェスト(Glslkit::Manifest, M4)
+    # を組み立てる。stage.urlは Rails.application.assets.resolver 経由で
+    # 解決する。これはasset_path/asset_urlが内部で使っているのとまさに同じ
+    # 経路であり、developmentではDynamic、assets:precompile実行後はStatic
+    # (Propshaftが直前に書いた.manifest.jsonを読む)になる。
+    class ManifestBuilder
+      attr_reader :diagnostics
+
+      def initialize(app)
+        @app = app
+        @diagnostics = []
+      end
+
+      # Validatorは常に実行し、@diagnosticsに集める(config.glslkit.validateの
+      # 値によらない)。`config.glslkit.validate`は「診断を集めるかどうか」
+      # ではなく「その診断を理由にビルド/リクエストを失敗させるかどうか」を
+      # 制御する。呼び出し側(Glslkit::Rails.manifest / rake glslkit:reflect /
+      # rake glslkit:check)がそれぞれの文脈でdiagnostics/failing?を見て
+      # 反応を決める(SPEC.md §8.6)。
+      def build
+        @diagnostics = []
+        manifest = Glslkit::Manifest.new(generated_at: Time.now.utc.iso8601)
+        programs.each do |name, stages|
+          vertex_source = preprocessor.process(stages.fetch(:vertex))
+          fragment_source = preprocessor.process(stages.fetch(:fragment))
+          validate(name, vertex_source, fragment_source)
+
+          manifest.add_program(
+            name,
+            vertex: {path: stages.fetch(:vertex), source: vertex_source, url: asset_url(stages.fetch(:vertex))},
+            fragment: {path: stages.fetch(:fragment), source: fragment_source, url: asset_url(stages.fetch(:fragment))}
+          )
+        end
+        manifest.to_h
+      end
+
+      # エラーが1件でもあれば真。`fail_on_warning`が有効なら警告のみでも真。
+      # config.glslkit.validateがfalseなら常に偽(検証結果があっても
+      # ビルド/リクエストを失敗させない)。
+      def failing?
+        return false unless glslkit_config.validate
+
+        return true if @diagnostics.any?(&:error?)
+
+        glslkit_config.fail_on_warning && @diagnostics.any?(&:warning?)
+      end
+
+      private
+
+      # Validator#validate は必ず Manifest.build(ここでは manifest.add_program)
+      # より前に呼ぶこと(SPEC.md §8.4/§8.6)。同一ステージ内の重複などは
+      # マージ後には検出できないため。
+      def validate(name, vertex_source, fragment_source)
+        program = Glslkit::Program.new(name: name, sources: {vertex: vertex_source, fragment: fragment_source})
+        result = Glslkit::Validator.new(disabled: glslkit_config.disabled_checks).validate(program)
+        @diagnostics.concat(result.diagnostics)
+      end
+
+      def glslkit_config
+        @app.config.glslkit
+      end
+
+      # 発見ロジック本体はShaderProgramsに集約している(LiveReload::ProgramsController
+      # と共有するため、M11c)。
+      def shader_roots
+        ShaderPrograms.roots(@app)
+      end
+
+      def programs
+        ShaderPrograms.discover(@app)
+      end
+
+      def stage_input(relative_path)
+        {path: relative_path, source: preprocessor.process(relative_path), url: asset_url(relative_path)}
+      end
+
+      def preprocessor
+        @preprocessor ||= Glslkit::Preprocessor.new(
+          resolver: Glslkit::Resolvers::FileSystem.new(load_paths: shader_roots),
+          line_directives: glslkit_config.line_directives
+        )
+      end
+
+      def asset_url(relative_path)
+        @app.assets.resolver.resolve(relative_path)
+      end
+    end
+  end
+end

data/lib/glslkit/rails/manifest_reader.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Glslkit
+  module Rails
+    class << self
+      # productionでは `rake assets:precompile` が書き出したマニフェストを
+      # 読むだけ(メモ化する: プロセスが生きている間、ファイルは変化しない
+      # ため)。development/testでは呼び出すたびに現在のシェーダソースから
+      # 再構築する。これは config.glslkit.line_directives/minify の
+      # dev-vs-production の使い分け方針(SPEC.md §4.1, §4.4)と同じ考え方。
+      def manifest
+        if ::Rails.env.production?
+          @manifest ||= read_precompiled_manifest
+        else
+          build_and_log_diagnostics
+        end
+      end
+
+      private
+
+      # developmentでは検証結果をログに出すが、決して例外を投げない
+      # (SPEC.md §8.6: 「development では検証するが失敗させない」)。
+      # 失敗させるのは `assets:precompile` フック(rails/lib/tasks/glslkit.rake)
+      # と `rake glslkit:check` の役目。
+      def build_and_log_diagnostics
+        builder = ManifestBuilder.new(::Rails.application)
+        result = builder.build
+        if ::Rails.application.config.glslkit.validate
+          builder.diagnostics.each { |diagnostic| ::Rails.logger.warn("[glslkit] #{diagnostic}") }
+        end
+        result
+      end
+
+      def read_precompiled_manifest
+        JSON.parse(File.read(manifest_path))
+      end
+
+      def manifest_path
+        config = ::Rails.application.config
+        config.assets.output_path.join(config.glslkit.manifest_path)
+      end
+    end
+  end
+end

data/lib/glslkit/rails/railtie.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Glslkit
+  module Rails
+    class Railtie < ::Rails::Railtie
+      config.glslkit = ActiveSupport::OrderedOptions.new
+      config.glslkit.paths = ["app/shaders"]
+      config.glslkit.minify = ::Rails.env.production?
+      config.glslkit.line_directives = !::Rails.env.production?
+      config.glslkit.manifest_path = "glsl-manifest.json"
+      # M11a: SPEC.md §8.6。デフォルトで検証は有効、警告での失敗は無効。
+      config.glslkit.validate = true
+      config.glslkit.fail_on_warning = false
+      config.glslkit.disabled_checks = []
+      # M11c: SPEC-livereload.md §3.3。既定はdevelopmentでのみ有効。
+      config.glslkit.live_reload = ::Rails.env.development?
+
+      # Mime::Type.register を使う (Propshaft::Asset#content_type 自身が
+      # 実際に使っている経路)。Marcelを直接使うことはしない — MarcelはPropshaft
+      # の内部的・推移的な実装詳細に過ぎず、そこに結合すべきではない。
+      initializer "glslkit.register_mime_types" do
+        ::Mime::Type.register "x-shader/x-vertex", :vert unless ::Mime::Type.lookup_by_extension("vert")
+        ::Mime::Type.register "x-shader/x-fragment", :frag unless ::Mime::Type.lookup_by_extension("frag")
+        # register ではなく register_alias を使う: "text/plain" は既に
+        # :text として登録済みなので、同じ文字列を :glsl として register で
+        # 再登録するとそのlookupエントリを上書きしてしまう。
+        ::Mime::Type.register_alias "text/plain", :glsl unless ::Mime::Type.lookup_by_extension("glsl")
+      end
+
+      initializer "glslkit.configure_propshaft", before: "propshaft.assets_middleware" do |app|
+        app.config.glslkit.paths.each do |path|
+          app.config.assets.paths << ::Rails.root.join(path).to_s
+        end
+
+        %w[x-shader/x-vertex x-shader/x-fragment text/plain].each do |mime_type|
+          app.config.assets.compilers << [mime_type, Glslkit::Rails::Compiler]
+        end
+      end
+
+      rake_tasks do
+        load File.expand_path("../../tasks/glslkit.rake", __dir__)
+      end
+
+      # M11c: SPEC-livereload.md §3.3。利用者のroutes.rb編集を要求しないため、
+      # ミドルウェアとして直接差し込む(`app.routes.append`によるmountは
+      # RouteSetのfinalize!タイミングに対してrace conditionがあり、
+      # 実機検証で再現性なく404になることが判明したため採用しなかった。
+      # 詳細はLiveReload::Mountのコメントを参照)。config.glslkit.live_reload
+      # が false(既定でproduction)ならミドルウェア自体を挿入しないため、
+      # `/glslkit/*` は通常のルーティングに委ねられ存在しない扱いになる。
+      initializer "glslkit.mount_live_reload" do |app|
+        next unless app.config.glslkit.live_reload
+
+        app.middleware.use Glslkit::Rails::LiveReload::Mount, Glslkit::Rails::LiveReload::Engine
+      end
+
+      initializer "glslkit.view_helpers" do
+        ActiveSupport.on_load(:action_view) { include Glslkit::Rails::Helper }
+      end
+    end
+  end
+end

data/lib/glslkit/rails/shader_programs.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Glslkit
+  module Rails
+    # `config.glslkit.paths` 配下の .vert/.frag ペアを名前ごとに集める。
+    # `ManifestBuilder`(静的な precompile)と `LiveReload::ProgramsController`
+    # (M11c、ポーリング用のエンドポイント)の両方が全く同じ発見ロジックを
+    # 必要とするため、ここに1箇所へ集約する。
+    module ShaderPrograms
+      module_function
+
+      def roots(app)
+        app.config.glslkit.paths.map { |path| app.root.join(path).to_s }
+      end
+
+      # {"pbr" => {vertex: "pbr.vert", fragment: "pbr.frag"}, ...} を返す。
+      # 同名の相方が無い .vert/.frag はスキップする(共有partialの可能性が
+      # あるため。SPEC.md §2.4/§3の「プログラムは両ステージ必須」の決定)。
+      def discover(app)
+        by_name = Hash.new { |h, k| h[k] = {} }
+
+        roots(app).each do |root|
+          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
+        end
+
+        by_name.select { |_, stages| stages.key?(:vertex) && stages.key?(:fragment) }
+      end
+    end
+  end
+end

data/lib/glslkit/rails/version.rb

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

data/lib/glslkit/rails.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "glslkit"
+require "propshaft"
+require_relative "rails/version"
+require_relative "rails/shader_programs"
+require_relative "rails/compiler"
+require_relative "rails/manifest_builder"
+require_relative "rails/manifest_reader"
+require_relative "rails/helper"
+require_relative "rails/live_reload/known_files"
+require_relative "rails/live_reload/programs_controller"
+require_relative "rails/live_reload/engine"
+require_relative "rails/live_reload/mount"
+require_relative "rails/railtie"
+
+module Glslkit
+  module Rails
+    # 注意: この名前空間の中では、素の定数`Rails`は`Glslkit::Rails`自身に
+    # 解決される。トップレベルのRailsフレームワークではない。フレームワーク
+    # を指すときは常に `::Rails` と書くこと (例: `::Rails::Engine`)。
+  end
+end

data/lib/tasks/glslkit.rake

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+namespace :glslkit do
+  desc "Generate the glslkit reflection manifest (config.assets.output_path/config.glslkit.manifest_path)"
+  task reflect: :environment do
+    app = Rails.application
+    builder = Glslkit::Rails::ManifestBuilder.new(app)
+    manifest = builder.build
+
+    # config.glslkit.validateが有効な間は、precompileの入口でビルドを
+    # 止める(SPEC.md §8.6)。マニフェストをファイルに書く前に検査すること
+    # (壊れたシェーダの情報を含むマニフェストをpublic/に残さないため)。
+    if builder.failing?
+      message = builder.diagnostics.select(&:error?).join("\n")
+      raise Glslkit::ValidationFailed, "glslkit validation failed:\n#{message}"
+    end
+
+    output_path = app.config.assets.output_path
+    FileUtils.mkdir_p(output_path)
+    File.write(output_path.join(app.config.glslkit.manifest_path), JSON.generate(manifest))
+  end
+
+  desc "Validate all glslkit shaders and exit non-zero on failure (ignores config.glslkit.validate)"
+  task check: :environment do
+    app = Rails.application
+    builder = Glslkit::Rails::ManifestBuilder.new(app)
+    builder.build
+
+    errors = builder.diagnostics.select(&:error?)
+    warnings = builder.diagnostics.select(&:warning?)
+
+    builder.diagnostics.each { |diagnostic| puts diagnostic }
+
+    # `rake glslkit:check` はconfig.glslkit.validateの設定に関わらず
+    # 常に検証結果に基づいて成否を判定する(CI等での明示的な検査用)。
+    abort("glslkit: #{errors.size} error(s)") if errors.any?
+    abort("glslkit: #{warnings.size} warning(s)") if app.config.glslkit.fail_on_warning && warnings.any?
+  end
+end
+
+# Propshaft自身のassets:precompile (propshaft/railties/assets.rake) の
+# 後に実行される。そのためRails.application.assets.resolverは、その場での
+# ファイルシステムスキャンではなく、Propshaftが直前に書いた.manifest.json
+# を見て、そこからdigest付きURLを解決する。
+Rake::Task["assets:precompile"].enhance do
+  Rake::Task["glslkit:reflect"].invoke
+end

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: glslkit-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0.pre
+platform: ruby
+authors:
+- kyubey1228
+bindir: bin
+cert_chain: []
+date: 2026-08-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: glslkit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0.pre
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0.pre
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: propshaft
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.2
+description: 'Registers .glsl/.vert/.frag assets with Propshaft, resolves #include
+  directives at request/precompile time, and publishes a shader reflection manifest
+  for consumption by views and JS at runtime.'
+email:
+- kyuuka1228@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- config/routes.rb
+- glslkit-rails.gemspec
+- lib/glslkit/rails.rb
+- lib/glslkit/rails/compiler.rb
+- lib/glslkit/rails/helper.rb
+- lib/glslkit/rails/live_reload/engine.rb
+- lib/glslkit/rails/live_reload/known_files.rb
+- lib/glslkit/rails/live_reload/mount.rb
+- lib/glslkit/rails/live_reload/programs_controller.rb
+- lib/glslkit/rails/manifest_builder.rb
+- lib/glslkit/rails/manifest_reader.rb
+- lib/glslkit/rails/railtie.rb
+- lib/glslkit/rails/shader_programs.rb
+- lib/glslkit/rails/version.rb
+- lib/tasks/glslkit.rake
+homepage: https://github.com/kyubey1228/glslkit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kyubey1228/glslkit
+  source_code_uri: https://github.com/kyubey1228/glslkit/tree/main/rails
+  changelog_uri: https://github.com/kyubey1228/glslkit/blob/main/rails/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Rails (Propshaft) integration for glslkit
+test_files: []