three-rb 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +38 -2
  3. data/README.md +14 -6
  4. data/docs/browser-runtime.md +10 -6
  5. data/docs/cloudflare-pages.md +205 -0
  6. data/docs/implementation-plan.md +6 -4
  7. data/docs/loaded-assets-design.md +1 -1
  8. data/docs/next-work.md +26 -25
  9. data/docs/publishing.md +4 -1
  10. data/docs/release-readiness.md +11 -11
  11. data/docs/standalone-browser-app.md +8 -2
  12. data/examples/browser/README.md +5 -1
  13. data/examples/browser/composition/index.html +65 -4
  14. data/examples/browser/composition/main.rb +2 -2
  15. data/examples/browser/cube/README.md +3 -3
  16. data/examples/browser/cube/index.html +61 -6
  17. data/examples/browser/cubemap/assets/checker.svg +11 -0
  18. data/examples/browser/cubemap/index.html +60 -5
  19. data/examples/browser/cubemap/main.rb +1 -1
  20. data/examples/browser/dango/README.md +26 -0
  21. data/examples/browser/dango/boot.mjs +6 -0
  22. data/examples/browser/dango/index.html +197 -0
  23. data/examples/browser/dango/main.rb +278 -0
  24. data/examples/browser/dango/smoke_test.mjs +232 -0
  25. data/examples/browser/gltf/index.html +60 -5
  26. data/examples/browser/gltf/main.rb +2 -2
  27. data/examples/browser/picking/index.html +61 -6
  28. data/examples/browser/postprocessing/index.html +61 -6
  29. data/examples/browser/primitives/assets/checker.svg +11 -0
  30. data/examples/browser/primitives/index.html +61 -6
  31. data/examples/browser/primitives/main.rb +1 -1
  32. data/examples/browser/ruby/README.md +2 -0
  33. data/examples/browser/ruby/assets/helvetiker_regular.typeface.json +1 -0
  34. data/examples/browser/ruby/index.html +112 -8
  35. data/examples/browser/ruby/main.rb +2 -6
  36. data/examples/browser/serialization/assets/checker.svg +11 -0
  37. data/examples/browser/serialization/index.html +61 -6
  38. data/examples/browser/serialization/main.rb +1 -1
  39. data/examples/browser/shared/boot.mjs +116 -14
  40. data/examples/browser/shared/config.mjs +3 -0
  41. data/examples/browser/shared/smoke_test_helpers.mjs +13 -8
  42. data/examples/browser/textures/assets/checker.svg +11 -0
  43. data/examples/browser/textures/index.html +61 -6
  44. data/examples/browser/textures/main.rb +2 -2
  45. data/exe/three-rb +1 -0
  46. data/lib/three/backends/threejs/parameters.rb +4 -1
  47. data/lib/three/backends/threejs/ruby_wasm_adapter.rb +8 -2
  48. data/lib/three/generators/browser_example.rb +220 -12
  49. data/lib/three/version.rb +1 -1
  50. data/package.json +9 -5
  51. data/pnpm-lock.yaml +1235 -31
  52. metadata +19 -7
  53. /data/examples/browser/{assets → composition/assets}/checker.svg +0 -0
  54. /data/examples/browser/{assets → gltf/assets}/animated_triangle.gltf +0 -0
  55. /data/examples/browser/{assets → gltf/assets}/compressed_triangle.gltf +0 -0
  56. /data/examples/browser/{assets → gltf/assets}/triangle.gltf +0 -0
  57. /data/examples/browser/{assets → textures/assets}/studio.hdr +0 -0
@@ -1,9 +1,12 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require "fileutils"
4
- require "cgi"
4
+ # Ruby 4.0 keeps only the escape helpers of the cgi library.
5
+ require "cgi/escape"
5
6
  require "json"
6
7
  require "pathname"
8
+ require "set"
9
+ require "yaml"
7
10
 
8
11
  module Three
9
12
  module Generators
@@ -56,21 +59,134 @@ module Three
56
59
  end
57
60
 
58
61
  def copy_runtime
59
- copy_file(runtime_path("package.json"), File.join(@root, "package.json"), overwrite: false)
60
- copy_file(runtime_path("pnpm-lock.yaml"), File.join(@root, "pnpm-lock.yaml"), overwrite: false)
62
+ write_app_package
61
63
  copy_tree(runtime_path("lib"), File.join(@root, "lib"), overwrite: false)
62
64
  copy_file(
63
65
  runtime_path("examples/browser/shared/boot.mjs"),
64
66
  File.join(File.dirname(@target), "shared", "boot.mjs"),
65
67
  overwrite: @force
66
68
  )
69
+ # boot.mjs imports the wasm URL from here. Apps may point it at their
70
+ # own host, so an existing copy is kept even with --force.
71
+ copy_file(
72
+ runtime_path("examples/browser/shared/config.mjs"),
73
+ File.join(File.dirname(@target), "shared", "config.mjs"),
74
+ overwrite: false
75
+ )
76
+ end
77
+
78
+ # The gem's own package.json also lists its test and deploy tooling, and
79
+ # pnpm refuses to install that tooling without the gem's
80
+ # pnpm-workspace.yaml. Apps only need the browser runtime packages.
81
+ def write_app_package
82
+ package_path = File.join(@root, "package.json")
83
+ package = app_package_json
84
+ write_runtime_file(package_path, package)
85
+
86
+ # A lockfile written next to someone else's package.json would not
87
+ # match it, and pnpm rejects a mismatched lockfile in CI.
88
+ return unless File.read(package_path) == package
89
+
90
+ lockfile = app_lockfile
91
+ write_runtime_file(File.join(@root, "pnpm-lock.yaml"), lockfile) if lockfile
92
+ end
93
+
94
+ def app_package_json
95
+ package = JSON.parse(File.read(runtime_path("package.json")))
96
+ app = {
97
+ "private" => true,
98
+ "packageManager" => package.fetch("packageManager"),
99
+ "dependencies" => package.fetch("dependencies")
100
+ }
101
+ "#{JSON.pretty_generate(app)}\n"
102
+ end
103
+
104
+ # Keeps the entries the runtime dependencies reach, so the app gets the
105
+ # versions and integrity hashes the gem was tested with.
106
+ def app_lockfile
107
+ source = File.read(runtime_path("pnpm-lock.yaml"))
108
+ return unless YAML.parse_stream(source).children.length == 1
109
+
110
+ lockfile = YAML.safe_load(source)
111
+ importer = lockfile.dig("importers", ".")
112
+ return unless importer
113
+
114
+ importer.delete("devDependencies")
115
+ snapshots = lockfile.fetch("snapshots", {})
116
+ reachable = reachable_snapshots(snapshots, importer.fetch("dependencies", {}))
117
+ # Snapshot keys may carry a peer suffix, as in "name@1.0.0(peer@2.0.0)".
118
+ packages = reachable.to_set { |key| key.sub(/\(.*\z/, "") }
119
+ lockfile["packages"] = lockfile.fetch("packages", {}).select { |key, _value| packages.include?(key) }
120
+ lockfile["snapshots"] = snapshots.select { |key, _value| reachable.include?(key) }
121
+
122
+ # pnpm reads a leading document marker as an empty first document and
123
+ # then reports the lockfile as missing.
124
+ YAML.dump(lockfile).delete_prefix("---\n")
125
+ end
126
+
127
+ def reachable_snapshots(snapshots, dependencies)
128
+ pending = dependencies.map { |name, dependency| "#{name}@#{dependency.fetch("version")}" }
129
+ reachable = Set.new
130
+ until pending.empty?
131
+ key = pending.shift
132
+ next unless reachable.add?(key)
133
+
134
+ snapshot = snapshots.fetch(key, nil) || {}
135
+ %w[dependencies optionalDependencies].each do |field|
136
+ snapshot.fetch(field, {}).each { |name, version| pending << "#{name}@#{version}" }
137
+ end
138
+ end
139
+ reachable
140
+ end
141
+
142
+ def write_runtime_file(path, content)
143
+ if File.exist?(path)
144
+ @skipped << relative_path(path)
145
+ return
146
+ end
147
+
148
+ FileUtils.mkdir_p(File.dirname(path))
149
+ File.write(path, content)
150
+ @created << relative_path(path)
67
151
  end
68
152
 
69
153
  def write_example_files
70
- write_file(example_path("index.html"), index_html, overwrite: @force)
71
- write_file(example_path("boot.mjs"), boot_js, overwrite: @force)
72
- write_file(example_path("main.rb"), main_rb, overwrite: @force)
73
- write_file(example_path("README.md"), readme, overwrite: @force)
154
+ if ruby_example?
155
+ copy_ruby_example_files
156
+ else
157
+ write_file(example_path("index.html"), index_html, overwrite: @force)
158
+ write_file(example_path("boot.mjs"), boot_js, overwrite: @force)
159
+ write_file(example_path("main.rb"), main_rb, overwrite: @force)
160
+ write_file(example_path("README.md"), readme, overwrite: @force)
161
+ end
162
+ end
163
+
164
+ def copy_ruby_example_files
165
+ {
166
+ "index.html" => "index.html",
167
+ "boot.mjs" => "boot.mjs",
168
+ "main.rb" => "main.rb",
169
+ "assets/helvetiker_regular.typeface.json" => "assets/helvetiker_regular.typeface.json"
170
+ }.each do |source_name, destination_name|
171
+ copy_generated_file(
172
+ runtime_path(File.join("examples/browser/ruby", source_name)),
173
+ example_path(destination_name),
174
+ overwrite: @force
175
+ )
176
+ end
177
+
178
+ write_ruby_readme
179
+ end
180
+
181
+ def write_ruby_readme
182
+ source = runtime_path("examples/browser/ruby/README.md")
183
+ destination = example_path("README.md")
184
+ if File.exist?(destination) && File.identical?(source, destination)
185
+ @skipped << relative_path(destination)
186
+ return
187
+ end
188
+
189
+ write_file(destination, ruby_readme, overwrite: @force)
74
190
  end
75
191
 
76
192
  def copy_tree(source, destination, overwrite:)
@@ -83,6 +199,11 @@ module Three
83
199
  end
84
200
 
85
201
  def copy_file(source, destination, overwrite:)
202
+ if File.exist?(destination) && File.identical?(source, destination)
203
+ @skipped << relative_path(destination)
204
+ return
205
+ end
206
+
86
207
  if File.exist?(destination) && !overwrite
87
208
  @skipped << relative_path(destination)
88
209
  return
@@ -93,6 +214,21 @@ module Three
93
214
  @created << relative_path(destination)
94
215
  end
95
216
 
217
+ def copy_generated_file(source, destination, overwrite:)
218
+ if File.exist?(destination) && File.identical?(source, destination)
219
+ @skipped << relative_path(destination)
220
+ return
221
+ end
222
+
223
+ if File.exist?(destination) && !overwrite
224
+ raise ArgumentError, "#{relative_path(destination)} already exists; pass --force to overwrite generated example files"
225
+ end
226
+
227
+ FileUtils.mkdir_p(File.dirname(destination))
228
+ FileUtils.cp(source, destination)
229
+ @created << relative_path(destination)
230
+ end
231
+
96
232
  def write_file(path, content, overwrite:)
97
233
  if File.exist?(path) && !overwrite
98
234
  raise ArgumentError, "#{relative_path(path)} already exists; pass --force to overwrite generated example files"
@@ -114,7 +250,9 @@ module Three
114
250
  end
115
251
 
116
252
  def example_files
117
- %w[index.html boot.mjs main.rb README.md].map { |name| example_path(name) }
253
+ names = %w[index.html boot.mjs main.rb README.md]
254
+ names << "assets/helvetiker_regular.typeface.json" if ruby_example?
255
+ names.map { |name| example_path(name) }
118
256
  end
119
257
 
120
258
  def example_path(name)
@@ -155,6 +293,10 @@ module Three
155
293
  JSON.generate(text)
156
294
  end
157
295
 
296
+ def ruby_example?
297
+ relative_path(@target) == "examples/browser/ruby"
298
+ end
299
+
158
300
  def index_html
159
301
  <<~HTML
160
302
  <!doctype html>
@@ -180,9 +322,11 @@ module Three
180
322
  position: absolute;
181
323
  top: 16px;
182
324
  left: 16px;
183
- display: flex;
325
+ display: grid;
326
+ grid-template-columns: auto minmax(0, 1fr);
184
327
  align-items: center;
185
328
  gap: 8px;
329
+ min-width: min(360px, calc(100% - 32px));
186
330
  padding: 8px 10px;
187
331
  border: 1px solid rgba(255, 255, 255, 0.14);
188
332
  border-radius: 6px;
@@ -199,6 +343,27 @@ module Three
199
343
  }
200
344
  .status-dot[data-state="running"] { background: #4ed08f; }
201
345
  .status-dot[data-state="error"] { background: #f15b5b; }
346
+ .status-dot[data-state="loading"] { animation: status-dot-pulse 1.2s ease-in-out infinite; }
347
+ @keyframes status-dot-pulse {
348
+ 0%, 100% { opacity: 1; transform: scale(1); }
349
+ 50% { opacity: 0.4; transform: scale(0.75); }
350
+ }
351
+ .progress {
352
+ grid-column: 1 / -1;
353
+ width: 100%;
354
+ height: 4px;
355
+ overflow: hidden;
356
+ border-radius: 999px;
357
+ background: rgba(255, 255, 255, 0.16);
358
+ }
359
+ .progress-bar {
360
+ width: 4%;
361
+ height: 100%;
362
+ border-radius: inherit;
363
+ background: linear-gradient(90deg, #55ace0, #4ed08f);
364
+ transition: width 180ms ease;
365
+ }
366
+ .progress[hidden] { display: none; }
202
367
  </style>
203
368
  <script type="importmap">
204
369
  {
@@ -213,10 +378,22 @@ module Three
213
378
  <script type="module">
214
379
  const status = document.querySelector("#status");
215
380
  const statusDot = document.querySelector("#status-dot");
381
+ const progress = document.querySelector("#progress");
382
+ const progressBar = document.querySelector("#progress-bar");
216
383
 
217
- globalThis.__threeRbSetStatus = (message, state) => {
384
+ globalThis.__threeRbSetStatus = (message, state, percent) => {
218
385
  if (status) status.textContent = message;
219
386
  if (statusDot) statusDot.dataset.state = state;
387
+ if (progress && progressBar) {
388
+ if (state === "running" || state === "error") {
389
+ progress.hidden = true;
390
+ } else {
391
+ progress.hidden = false;
392
+ if (Number.isFinite(percent)) {
393
+ progressBar.style.width = `${Math.max(4, Math.min(100, percent))}%`;
394
+ }
395
+ }
396
+ }
220
397
  };
221
398
  globalThis.__threeRbBootFailed = (message) => globalThis.__threeRbSetStatus(message, "error");
222
399
  globalThis.addEventListener("error", (event) => globalThis.__threeRbBootFailed(event.message || "Browser error"));
@@ -224,7 +401,12 @@ module Three
224
401
  const reason = event.reason;
225
402
  globalThis.__threeRbBootFailed(reason && reason.message ? reason.message : "Ruby boot failed");
226
403
  });
227
- globalThis.__threeRbSetStatus("Loading ruby.wasm", "loading");
404
+ globalThis.setTimeout(() => {
405
+ if (status && statusDot && statusDot.dataset.state === "loading") {
406
+ status.textContent = "Still loading after 15 seconds. Try reloading the page.";
407
+ }
408
+ }, 15000);
409
+ globalThis.__threeRbSetStatus("Loading ruby.wasm", "loading", 4);
228
410
  </script>
229
411
  <script type="module" src="./boot.mjs"></script>
230
412
  </head>
@@ -232,8 +414,11 @@ module Three
232
414
  <main id="viewport">
233
415
  <canvas id="scene" data-testid="scene-canvas"></canvas>
234
416
  <div class="hud" aria-live="polite">
235
- <span class="status-dot" id="status-dot"></span>
417
+ <span class="status-dot" id="status-dot" data-state="loading"></span>
236
418
  <span id="status" data-testid="status">Loading ruby.wasm</span>
419
+ <div class="progress" id="progress" aria-hidden="true">
420
+ <div class="progress-bar" id="progress-bar"></div>
421
+ </div>
237
422
  </div>
238
423
  </main>
239
424
  </body>
@@ -310,6 +495,29 @@ module Three
310
495
  Keep serving the project root. The browser runtime loads `node_modules/`, `lib/`, and this example over HTTP.
311
496
  MARKDOWN
312
497
  end
498
+
499
+ def ruby_readme
500
+ <<~MARKDOWN
501
+ # three-rb Ruby Example
502
+
503
+ This generated browser example runs Ruby through ruby.wasm and renders a faceted red gemstone with a three-dimensional `three-rb` title.
504
+
505
+ From the project root:
506
+
507
+ ```sh
508
+ pnpm install
509
+ ruby -run -e httpd . -p 8000
510
+ ```
511
+
512
+ Open:
513
+
514
+ ```text
515
+ http://localhost:8000/#{relative_path(@target)}/
516
+ ```
517
+
518
+ Keep serving the project root. The browser runtime loads `node_modules/`, `lib/`, and this example's local `assets/` directory over HTTP.
519
+ MARKDOWN
520
+ end
313
521
  end
314
522
  end
315
523
  end
data/lib/three/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Three
4
- VERSION = "0.2.0"
4
+ VERSION = "0.3.0"
5
5
  end
data/package.json CHANGED
@@ -4,9 +4,11 @@
4
4
  "type": "module",
5
5
  "packageManager": "pnpm@11.1.1",
6
6
  "scripts": {
7
- "test:browser": "pnpm test:browser:ruby && pnpm test:browser:cube && pnpm test:browser:composition && pnpm test:browser:textures && pnpm test:browser:cubemap && pnpm test:browser:gltf && pnpm test:browser:serialization && pnpm test:browser:picking && pnpm test:browser:primitives && pnpm test:browser:postprocessing",
7
+ "build:pages:ruby": "sh scripts/build-pages-ruby.sh",
8
+ "test:browser": "pnpm test:browser:ruby && pnpm test:browser:cube && pnpm test:browser:dango && pnpm test:browser:composition && pnpm test:browser:textures && pnpm test:browser:cubemap && pnpm test:browser:gltf && pnpm test:browser:serialization && pnpm test:browser:picking && pnpm test:browser:primitives && pnpm test:browser:postprocessing && pnpm test:browser:generated",
8
9
  "test:browser:ruby": "node examples/browser/ruby/smoke_test.mjs",
9
10
  "test:browser:cube": "node examples/browser/cube/smoke_test.mjs",
11
+ "test:browser:dango": "node examples/browser/dango/smoke_test.mjs",
10
12
  "test:browser:composition": "node examples/browser/composition/smoke_test.mjs",
11
13
  "test:browser:textures": "node examples/browser/textures/smoke_test.mjs",
12
14
  "test:browser:cubemap": "node examples/browser/cubemap/smoke_test.mjs",
@@ -15,17 +17,19 @@
15
17
  "test:browser:picking": "node examples/browser/picking/smoke_test.mjs",
16
18
  "test:browser:primitives": "node examples/browser/primitives/smoke_test.mjs",
17
19
  "test:browser:postprocessing": "node examples/browser/postprocessing/smoke_test.mjs",
20
+ "test:browser:generated": "node test/browser/generated_apps_smoke_test.mjs",
18
21
  "benchmark:browser": "pnpm benchmark:browser:mesh-sync && pnpm benchmark:browser:instanced-mesh-sync",
19
22
  "benchmark:browser:mesh-sync": "node benchmarks/browser/mesh_sync/run.mjs",
20
23
  "benchmark:browser:instanced-mesh-sync": "node benchmarks/browser/instanced_mesh_sync/run.mjs"
21
24
  },
22
25
  "dependencies": {
23
26
  "@bjorn3/browser_wasi_shim": "0.4.2",
24
- "@ruby/3.4-wasm-wasi": "2.9.4-2026-05-11-a",
25
- "@ruby/wasm-wasi": "2.9.4-2026-05-11-a",
26
- "three": "0.184.0"
27
+ "@ruby/3.4-wasm-wasi": "2.10.1",
28
+ "@ruby/wasm-wasi": "2.10.1",
29
+ "three": "0.187.0"
27
30
  },
28
31
  "devDependencies": {
29
- "playwright": "^1.60.0"
32
+ "playwright": "^1.65.1",
33
+ "wrangler": "^4.165.0"
30
34
  }
31
35
  }