homura-runtime 0.3.6 → 0.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6fac4160687b6043e752f8d18ba217e5eb53dcb1efa16158f2b8409da7e26d39
-  data.tar.gz: 57386658268ff69b225ebbb3fac5a9400c702783c384eb9fec117fc6a315cbf5
+  metadata.gz: 90ff82f40bdd001631e5dd1626579eaa0c3e62b2b8569b5d33829203b44c7a17
+  data.tar.gz: 865e7c3bc07aa6b48362afb2c436eaf09c33f8dd41c98ac6c59ccacbb8b4f718
 SHA512:
-  metadata.gz: 50fd0246537d673f1211066e3aa1a443f8f50cbb33bdfd5197a70cf9786c67a401b8109646189eb16af3d33cd0c936420a9f93d7a7e2dec327221062705c1048
-  data.tar.gz: 075e7b5786548a85a3bb90f7ee451c4288ec5a759597942ae92df797bcc39be453d3e80b2e9a4c619462b469c009453942022e6930fb938766d475e07565d19a
+  metadata.gz: 7814e73863240b28be6da34ab8043da6e6ad64eadc29a083b6feb115b5ee55e1549c9271980bc83ef30a1b009a1e31ab9624b9fbc9abb8f43dd8f273c1ea4837
+  data.tar.gz: a7a9fd42c426e784c6938816c83c6f55924ad0256f953978dd6fbce1ce827c94634cb5d3b0b2a08bcc98375b40a261749e4884bd547c6500cb13c7b9e5847633

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.3.7 (2026-05-06)
+
+- Add Ruby-shaped Workers AI helpers for the staged voice examples:
+  `ai.chat`, `ai.chat_text`, `ai.transcribe`, `ai.transcribe_text`,
+  `ai.speak`, and `ai.speak_data_url`.
+- `ai.speak` returns a `Cloudflare::BinaryBody`, so a Sinatra route can
+  stream Aura audio directly back to the browser without exposing JS
+  response plumbing in user code.
+- Register the new AI helpers with auto-await so example/source Ruby stays
+  sync-shaped.
+
 ## 0.3.6 (2026-05-03)
 
 - Release the no-await-surface examples/docs baseline: public Rack,

data/exe/auto-await

@@ -13,34 +13,47 @@
 # output directory earlier on the Opal load path and fall back to
 # the original input for unchanged files.
 
-require 'fileutils'
-require 'pathname'
-require_relative '../lib/homura/runtime/build_support'
+require "fileutils"
+require "pathname"
+require_relative "../lib/homura/runtime/build_support"
 
 # homura-runtime lib path resolution (with legacy alias fallback)
-runtime_lib = ENV['CFW_RUNTIME_LIB']
+runtime_lib = ENV["CFW_RUNTIME_LIB"]
 unless runtime_lib
-  runtime_lib = HomuraRuntime::BuildSupport.runtime_root(current_file: __FILE__).join('lib').to_s
+  runtime_lib =
+    HomuraRuntime::BuildSupport
+      .runtime_root(current_file: __FILE__)
+      .join("lib")
+      .to_s
 end
 $LOAD_PATH.unshift(runtime_lib) unless $LOAD_PATH.include?(runtime_lib)
 
-require 'homura/runtime/async_registry'
-require 'homura/runtime/auto_await/analyzer'
-require 'homura/runtime/auto_await/transformer'
+require "homura/runtime/async_registry"
+require "homura/runtime/auto_await/analyzer"
+require "homura/runtime/auto_await/transformer"
 
-options = { input: nil, output: nil, debug: ENV['CLOUDFLARE_WORKERS_AUTO_AWAIT_DEBUG'] == '1' }
+options = {
+  input: nil,
+  output: nil,
+  debug: ENV["CLOUDFLARE_WORKERS_AUTO_AWAIT_DEBUG"] == "1"
+}
 
 ARGV.each_with_index do |arg, i|
   case arg
-  when '--input'  then options[:input] = ARGV[i + 1]
-  when '--output' then options[:output] = ARGV[i + 1]
-  when '--debug'  then options[:debug] = true
+  when "--input"
+    options[:input] = ARGV[i + 1]
+  when "--output"
+    options[:output] = ARGV[i + 1]
+  when "--debug"
+    options[:debug] = true
   end
 end
 
-abort('Usage: auto-await --input DIR --output DIR [--debug]') unless options[:input] && options[:output]
+unless options[:input] && options[:output]
+  abort("Usage: auto-await --input DIR --output DIR [--debug]")
+end
 
-input_root  = Pathname(options[:input]).expand_path
+input_root = Pathname(options[:input]).expand_path
 output_root = Pathname(options[:output]).expand_path
 
 registry = HomuraRuntime::AsyncRegistry.instance
@@ -49,18 +62,19 @@ registry = HomuraRuntime::AsyncRegistry.instance
 HomuraRuntime::AsyncRegistry.auto_load_gem_async_sources(debug: options[:debug])
 
 # Load project-specific async source registrations if present.
-project_async = File.join(Dir.pwd, 'lib', 'homura_async_sources.rb')
+project_async = File.join(Dir.pwd, "lib", "homura_async_sources.rb")
 require project_async if File.exist?(project_async)
 
 changed = 0
 skipped = 0
-errors  = 0
+errors = 0
 
-paths = if File.directory?(input_root)
-  Dir.glob(input_root.join('**', '*.rb')).sort
-else
-  [input_root.to_s]
-end
+paths =
+  if File.directory?(input_root)
+    Dir.glob(input_root.join("**", "*.rb")).sort
+  else
+    [input_root.to_s]
+  end
 
 paths.each do |path|
   rel = Pathname(path).relative_path_from(input_root)
@@ -72,10 +86,11 @@ paths.each do |path|
   # needed to tell Opal to wrap the file in an async function and to
   # translate #__await__ calls into real JS await keywords.
   has_magic = source.lines.first(5).any? { |l| l.match?(/#\s*await:/) }
-  has_existing_await = source.include?('.__await__')
+  has_existing_await = source.include?(".__await__")
 
   begin
-    analyzer = HomuraRuntime::AutoAwait::Analyzer.new(registry, debug: options[:debug])
+    analyzer =
+      HomuraRuntime::AutoAwait::Analyzer.new(registry, debug: options[:debug])
     buffer, nodes = analyzer.process(source, path)
     needs_magic_only_output = has_existing_await && !has_magic
 
@@ -91,13 +106,13 @@ paths.each do |path|
       else
         HomuraRuntime::AutoAwait::Transformer.transform(source, nodes, buffer)
       end
-    unless has_magic
-      transformed = "# await: true\n" + transformed
-    end
+    transformed = "# await: true\n" + transformed unless has_magic
     out_path = output_root.join(rel)
     FileUtils.mkdir_p(out_path.dirname)
     File.write(out_path, transformed)
-    puts "[auto-await] write #{rel} (#{nodes.length} await#{'s' if nodes.length > 1})" if options[:debug]
+    if options[:debug]
+      puts "[auto-await] write #{rel} (#{nodes.length} await#{"s" if nodes.length > 1})"
+    end
     changed += 1
   rescue => e
     $stderr.puts "[auto-await] ERROR #{rel}: #{e.message}"

data/exe/compile-assets

@@ -12,39 +12,39 @@
 # Usage:
 #   ruby bin/compile-assets --input public --output build/homura_assets.rb --namespace HomuraAssets
 
-require 'base64'
-require 'fileutils'
-require 'optparse'
+require "base64"
+require "fileutils"
+require "optparse"
 
 MIME_TYPES = {
-  '.css'  => 'text/css; charset=utf-8',
-  '.js'   => 'application/javascript; charset=utf-8',
-  '.json' => 'application/json; charset=utf-8',
-  '.html' => 'text/html; charset=utf-8',
-  '.svg'  => 'image/svg+xml',
-  '.png'  => 'image/png',
-  '.jpg'  => 'image/jpeg',
-  '.jpeg' => 'image/jpeg',
-  '.gif'  => 'image/gif',
-  '.ico'  => 'image/x-icon',
-  '.woff' => 'font/woff',
-  '.woff2'=> 'font/woff2',
-  '.txt'  => 'text/plain; charset=utf-8',
-  '.xml'  => 'application/xml; charset=utf-8',
-  '.webp' => 'image/webp',
-  '.map'  => 'application/json',
+  ".css" => "text/css; charset=utf-8",
+  ".js" => "application/javascript; charset=utf-8",
+  ".json" => "application/json; charset=utf-8",
+  ".html" => "text/html; charset=utf-8",
+  ".svg" => "image/svg+xml",
+  ".png" => "image/png",
+  ".jpg" => "image/jpeg",
+  ".jpeg" => "image/jpeg",
+  ".gif" => "image/gif",
+  ".ico" => "image/x-icon",
+  ".woff" => "font/woff",
+  ".woff2" => "font/woff2",
+  ".txt" => "text/plain; charset=utf-8",
+  ".xml" => "application/xml; charset=utf-8",
+  ".webp" => "image/webp",
+  ".map" => "application/json"
 }.freeze
 
 def mime_for(path)
   ext = File.extname(path).downcase
-  MIME_TYPES[ext] || 'application/octet-stream'
+  MIME_TYPES[ext] || "application/octet-stream"
 end
 
 def binary_content_type?(content_type)
-  !(content_type.start_with?('text/') ||
-    content_type.include?('javascript') ||
-    content_type.include?('json') ||
-    content_type.include?('xml'))
+  !(
+    content_type.start_with?("text/") || content_type.include?("javascript") ||
+      content_type.include?("json") || content_type.include?("xml")
+  )
 end
 
 HELP = <<~USAGE
@@ -55,23 +55,31 @@ HELP = <<~USAGE
     --input public --output build/homura_assets.rb --namespace HomuraAssets
 USAGE
 
-if ARGV.include?('-h') || ARGV.include?('--help')
+if ARGV.include?("-h") || ARGV.include?("--help")
   puts HELP
   exit 0
 end
 
 options = {
-  input_dir: 'public',
-  output: 'build/homura_assets.rb',
-  namespace: 'HomuraAssets'
+  input_dir: "public",
+  output: "build/homura_assets.rb",
+  namespace: "HomuraAssets"
 }
 
-OptionParser.new do |op|
-  op.banner = 'Usage: bin/compile-assets [options]'
-  op.on('--input DIR', 'Root directory to embed (recursive)') { |d| options[:input_dir] = d }
-  op.on('--output PATH', 'Generated Ruby output path') { |p| options[:output] = p }
-  op.on('--namespace NAME', 'Ruby module name') { |n| options[:namespace] = n }
-end.parse!
+OptionParser
+  .new do |op|
+    op.banner = "Usage: bin/compile-assets [options]"
+    op.on("--input DIR", "Root directory to embed (recursive)") do |d|
+      options[:input_dir] = d
+    end
+    op.on("--output PATH", "Generated Ruby output path") do |p|
+      options[:output] = p
+    end
+    op.on("--namespace NAME", "Ruby module name") do |n|
+      options[:namespace] = n
+    end
+  end
+  .parse!
 
 public_dir = File.join(Dir.pwd, options[:input_dir])
 unless File.directory?(public_dir)
@@ -81,12 +89,13 @@ end
 
 ns = options[:namespace]
 
-files = Dir.glob(File.join(public_dir, '**', '*')).select { |f| File.file?(f) }.sort
+files =
+  Dir.glob(File.join(public_dir, "**", "*")).select { |f| File.file?(f) }.sort
 
 out_path = options[:output]
 FileUtils.mkdir_p(File.dirname(out_path))
 
-File.open(out_path, 'w') do |io|
+File.open(out_path, "w") do |io|
   io.puts <<~RUBY
     # frozen_string_literal: true
     # Auto-generated by bin/compile-assets — DO NOT EDIT BY HAND.
@@ -131,7 +140,7 @@ File.open(out_path, 'w') do |io|
   RUBY
 
   files.each do |full_path|
-    rel = full_path.sub(public_dir, '')        # e.g. "/style.css"
+    rel = full_path.sub(public_dir, "") # e.g. "/style.css"
     content = File.binread(full_path)
     ct = mime_for(full_path)
     binary = binary_content_type?(ct)

data/exe/compile-erb

@@ -22,8 +22,8 @@
 # The output registers each template with `HomuraTemplates` and
 # monkey-patches `Sinatra::Templates#erb` to dispatch there.
 
-require 'fileutils'
-require 'optparse'
+require "fileutils"
+require "optparse"
 
 HELP = <<~USAGE
   Usage:
@@ -53,7 +53,7 @@ module HomuraERB
   end
 
   def normalize_fragment(fragment)
-    return '__homura_template_yield__' if supported_yield_fragment?(fragment)
+    return "__homura_template_yield__" if supported_yield_fragment?(fragment)
     rewrite_class_variables(fragment)
   end
 
@@ -75,13 +75,15 @@ module HomuraERB
   # comments are vanishingly rare in real templates. Anything more
   # ambitious would need a Ruby parser, which is overkill for the
   # `@@ivar` shape we actually have to handle here.
-  CVAR_OP_ASSIGN_RE = /(?<![@\w])@@([A-Za-z_]\w*)\s*(\|\||&&|\+|-|\*|\/|%|\*\*|<<|>>|\||&|\^)=\s*([^;\n]+)/.freeze
+  CVAR_OP_ASSIGN_RE =
+    %r{(?<![@\w])@@([A-Za-z_]\w*)\s*(\|\||&&|\+|-|\*|/|%|\*\*|<<|>>|\||&|\^)=\s*([^;\n]+)}.freeze
   CVAR_ASSIGN_RE = /(?<![@\w])@@([A-Za-z_]\w*)\s*=(?!=)\s*([^;\n]+)/.freeze
   # Read pattern excludes `@@name` that appears on the left-hand side
   # of an assignment (`@@name =`, `@@name +=`, `@@name ||=`, etc.) so
   # the assignment passes still see the raw token to rewrite. The
   # `=(?!=)` guard keeps `==` (comparison) treated as a read.
-  CVAR_READ_RE = %r{
+  CVAR_READ_RE =
+    %r{
     (?<![@\w])@@([A-Za-z_]\w*)\b
     (?!
       \s*
@@ -94,13 +96,14 @@ module HomuraERB
   CVAR_PLACEHOLDER_SUFFIX = "\x01".freeze
 
   def rewrite_class_variables(fragment)
-    return fragment unless fragment.include?('@@')
+    return fragment unless fragment.include?("@@")
 
     placeholders = []
-    record = lambda do |replacement|
-      placeholders << replacement
-      "#{CVAR_PLACEHOLDER_PREFIX}#{placeholders.length - 1}#{CVAR_PLACEHOLDER_SUFFIX}"
-    end
+    record =
+      lambda do |replacement|
+        placeholders << replacement
+        "#{CVAR_PLACEHOLDER_PREFIX}#{placeholders.length - 1}#{CVAR_PLACEHOLDER_SUFFIX}"
+      end
 
     # Reads first: rewrite every `@@name` that is *not* the target of
     # an assignment, including occurrences on the right-hand side of
@@ -108,36 +111,41 @@ module HomuraERB
     # later assignment passes see the original `@@name = ...` shape
     # (without their RHS reads being clobbered) and so the final
     # output never re-enters this same rewrite loop.
-    work = fragment.gsub(CVAR_READ_RE) do
-      name = Regexp.last_match(1)
-      record.call("self.class.class_variable_get(:@@#{name})")
-    end
+    work =
+      fragment.gsub(CVAR_READ_RE) do
+        name = Regexp.last_match(1)
+        record.call("self.class.class_variable_get(:@@#{name})")
+      end
 
-    work = work.gsub(CVAR_OP_ASSIGN_RE) do
-      name = Regexp.last_match(1)
-      op = Regexp.last_match(2)
-      value = Regexp.last_match(3)
-      replacement =
-        case op
-        when '||'
-          "self.class.class_variable_set(:@@#{name}, (self.class.class_variable_defined?(:@@#{name}) ? self.class.class_variable_get(:@@#{name}) : nil) || (#{value}))"
-        when '&&'
-          "self.class.class_variable_set(:@@#{name}, (self.class.class_variable_defined?(:@@#{name}) ? self.class.class_variable_get(:@@#{name}) : nil) && (#{value}))"
-        else
-          "self.class.class_variable_set(:@@#{name}, self.class.class_variable_get(:@@#{name}) #{op} (#{value}))"
-        end
-      record.call(replacement)
-    end
+    work =
+      work.gsub(CVAR_OP_ASSIGN_RE) do
+        name = Regexp.last_match(1)
+        op = Regexp.last_match(2)
+        value = Regexp.last_match(3)
+        replacement =
+          case op
+          when "||"
+            "self.class.class_variable_set(:@@#{name}, (self.class.class_variable_defined?(:@@#{name}) ? self.class.class_variable_get(:@@#{name}) : nil) || (#{value}))"
+          when "&&"
+            "self.class.class_variable_set(:@@#{name}, (self.class.class_variable_defined?(:@@#{name}) ? self.class.class_variable_get(:@@#{name}) : nil) && (#{value}))"
+          else
+            "self.class.class_variable_set(:@@#{name}, self.class.class_variable_get(:@@#{name}) #{op} (#{value}))"
+          end
+        record.call(replacement)
+      end
 
-    work = work.gsub(CVAR_ASSIGN_RE) do
-      name = Regexp.last_match(1)
-      value = Regexp.last_match(2)
-      record.call("self.class.class_variable_set(:@@#{name}, (#{value}))")
-    end
+    work =
+      work.gsub(CVAR_ASSIGN_RE) do
+        name = Regexp.last_match(1)
+        value = Regexp.last_match(2)
+        record.call("self.class.class_variable_set(:@@#{name}, (#{value}))")
+      end
 
-    placeholder_re = /#{Regexp.escape(CVAR_PLACEHOLDER_PREFIX)}(\d+)#{Regexp.escape(CVAR_PLACEHOLDER_SUFFIX)}/
+    placeholder_re =
+      /#{Regexp.escape(CVAR_PLACEHOLDER_PREFIX)}(\d+)#{Regexp.escape(CVAR_PLACEHOLDER_SUFFIX)}/
     loop do
-      replaced = work.gsub(placeholder_re) { placeholders[Regexp.last_match(1).to_i] }
+      replaced =
+        work.gsub(placeholder_re) { placeholders[Regexp.last_match(1).to_i] }
       break if replaced == work
       work = replaced
     end
@@ -146,7 +154,10 @@ module HomuraERB
 
   def validate_code_fragment!(fragment)
     stripped = fragment.strip
-    return unless supported_yield_fragment?(stripped) || yield_with_args_fragment?(stripped)
+    unless supported_yield_fragment?(stripped) ||
+             yield_with_args_fragment?(stripped)
+      return
+    end
 
     raise <<~MSG.strip
       Unsupported ERB yield form `<% #{stripped} %>`.
@@ -176,7 +187,7 @@ module HomuraERB
     ruby = +"_out = ''\n"
     cursor = 0
     while cursor < source.length
-      open_idx = source.index('<%', cursor)
+      open_idx = source.index("<%", cursor)
       if open_idx.nil?
         static = source[cursor..]
         ruby << "_out = _out + #{static.inspect}\n" unless static.empty?
@@ -189,21 +200,23 @@ module HomuraERB
         ruby << "_out = _out + #{static.inspect}\n"
       end
 
-      close_idx = source.index('%>', open_idx + 2)
-      raise "Unmatched `<%` in ERB source (starting at #{open_idx})" if close_idx.nil?
+      close_idx = source.index("%>", open_idx + 2)
+      if close_idx.nil?
+        raise "Unmatched `<%` in ERB source (starting at #{open_idx})"
+      end
 
       inner = source[(open_idx + 2)...close_idx]
 
-      if inner.start_with?('#')
+      if inner.start_with?("#")
         # `<%# comment %>` — drop
-      elsif inner.start_with?('==')
+      elsif inner.start_with?("==")
         # `<%== expression %>` — identical to `<%= %>` in this minimal
         # dialect (no HTML escaping yet; the author is responsible).
         expr = inner[2..].strip
         validate_expression_fragment!(expr)
         expr = normalize_fragment(expr)
         ruby << "_out = _out + ((#{expr})).to_s\n"
-      elsif inner.start_with?('=')
+      elsif inner.start_with?("=")
         # `<%= expression %>`
         expr = inner[1..].strip
         validate_expression_fragment!(expr)
@@ -243,17 +256,17 @@ end
 def default_inputs_for(dir)
   # Recursive so `views/posts/index.erb` becomes `:'posts/index'`,
   # matching upstream Sinatra's subdirectory convention.
-  Dir.glob(File.join(dir, '**', '*.erb')).sort
+  Dir.glob(File.join(dir, "**", "*.erb")).sort
 end
 
 def template_name_for(path, root)
   rel = path.dup
   if root
-    root_with_sep = root.end_with?('/') ? root : "#{root}/"
+    root_with_sep = root.end_with?("/") ? root : "#{root}/"
     rel = rel[root_with_sep.length..] if rel.start_with?(root_with_sep)
   end
-  rel = File.basename(rel) unless rel.include?('/')
-  rel.delete_suffix('.erb').to_sym
+  rel = File.basename(rel) unless rel.include?("/")
+  rel.delete_suffix(".erb").to_sym
 end
 
 def emit_header(io, namespace)
@@ -479,25 +492,34 @@ end
 # Entry point
 # ---------------------------------------------------------------------------
 
-if ARGV.include?('-h') || ARGV.include?('--help')
+if ARGV.include?("-h") || ARGV.include?("--help")
   puts HELP
   exit 0
 end
 
 options = {
-  input_dir: 'views',
-  output: 'build/homura_templates.rb',
-  namespace: 'HomuraTemplates',
+  input_dir: "views",
+  output: "build/homura_templates.rb",
+  namespace: "HomuraTemplates",
   stdout: false
 }
 
-parser = OptionParser.new do |op|
-  op.banner = 'Usage: bin/compile-erb [options] [--] [files...]'
-  op.on('--input DIR', 'Directory containing *.erb templates') { |d| options[:input_dir] = d }
-  op.on('--output PATH', 'Write generated Ruby to PATH') { |p| options[:output] = p }
-  op.on('--namespace NAME', 'Ruby module name for the registry') { |n| options[:namespace] = n }
-  op.on('--stdout', 'Write generated Ruby to stdout') { options[:stdout] = true }
-end
+parser =
+  OptionParser.new do |op|
+    op.banner = "Usage: bin/compile-erb [options] [--] [files...]"
+    op.on("--input DIR", "Directory containing *.erb templates") do |d|
+      options[:input_dir] = d
+    end
+    op.on("--output PATH", "Write generated Ruby to PATH") do |p|
+      options[:output] = p
+    end
+    op.on("--namespace NAME", "Ruby module name for the registry") do |n|
+      options[:namespace] = n
+    end
+    op.on("--stdout", "Write generated Ruby to stdout") do
+      options[:stdout] = true
+    end
+  end
 parser.parse!
 
 positional = ARGV.dup
@@ -505,12 +527,15 @@ namespace = options[:namespace]
 
 inputs =
   if positional.any?
-    positional.flat_map { |a| File.directory?(a) ? Dir.glob(File.join(a, '**', '*.erb')).sort : [a] }
+    positional.flat_map do |a|
+      File.directory?(a) ? Dir.glob(File.join(a, "**", "*.erb")).sort : [a]
+    end
   else
     default_inputs_for(options[:input_dir])
   end
 
-template_root = positional.find { |a| File.directory?(a) } || options[:input_dir]
+template_root =
+  positional.find { |a| File.directory?(a) } || options[:input_dir]
 
 write_file = !options[:stdout] && (positional.empty? || options[:output])
 out_path = options[:output]
@@ -524,7 +549,7 @@ end
 
 if write_file
   FileUtils.mkdir_p(File.dirname(out_path))
-  File.open(out_path, 'w') do |io|
+  File.open(out_path, "w") do |io|
     emit_header(io, namespace)
     emit_templates(io, inputs, namespace, template_root)
     emit_sinatra_patch(io, namespace) unless inputs.empty?