ruact 0.0.1

data/Users/luiz/workspace/rails-rsc/gem/vendor/javascript/vite-plugin-ruact/index.js

@@ -0,0 +1,163 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * vite-plugin-ruact
+ *
+ * Scans app/javascript/components for files with "use client" directives and
+ * emits public/react-client-manifest.json so the Rails gem can resolve
+ * component names to chunk URLs.
+ *
+ * Manifest format:
+ * {
+ *   "LikeButton": {
+ *     "id":     "/assets/LikeButton-abc123.js",
+ *     "name":   "LikeButton",
+ *     "chunks": ["/assets/LikeButton-abc123.js"]
+ *   }
+ * }
+ */
+export default function ruact(options = {}) {
+  const {
+    componentsDir = "app/javascript/components",
+    manifestOutput = "public/react-client-manifest.json",
+  } = options;
+
+  let root;
+  let manifest = {};
+
+  return {
+    name: "vite-plugin-ruact",
+
+    configResolved(config) {
+      root = config.root;
+    },
+
+    // During dev: build the manifest from source files
+    buildStart() {
+      manifest = buildManifest(path.resolve(root, componentsDir));
+      writeManifest(path.resolve(root, manifestOutput), manifest);
+    },
+
+    // During build: update with hashed chunk URLs from the bundle
+    generateBundle(_options, bundle) {
+      const updated = {};
+
+      for (const [chunkFileName, chunk] of Object.entries(bundle)) {
+        if (chunk.type !== "chunk") continue;
+
+        const facadeId = chunk.facadeModuleId;
+        if (!facadeId) continue;
+
+        // Find manifest entries whose source file matches this chunk
+        for (const [name, entry] of Object.entries(manifest)) {
+          if (facadeId === entry._sourceFile) {
+            const url = "/" + chunkFileName;
+            updated[name] = {
+              id: url,
+              name,
+              chunks: [url],
+            };
+          }
+        }
+      }
+
+      // Merge: keep entries that didn't get a hashed URL (dev mode)
+      const final = { ...manifest, ...updated };
+      // Strip internal _sourceFile field
+      for (const entry of Object.values(final)) {
+        delete entry._sourceFile;
+      }
+
+      writeManifest(path.resolve(root, manifestOutput), final);
+    },
+
+    // Dev server: watch components dir and rebuild manifest on change
+    configureServer(server) {
+      const dir = path.resolve(root, componentsDir);
+      server.watcher.add(dir);
+      server.watcher.on("change", (file) => {
+        if (file.startsWith(dir)) {
+          manifest = buildManifest(dir);
+          writeManifest(path.resolve(root, manifestOutput), manifest);
+        }
+      });
+    },
+  };
+}
+
+function buildManifest(componentsDir) {
+  const manifest = {};
+
+  if (!fs.existsSync(componentsDir)) return manifest;
+
+  const files = walkDir(componentsDir).filter((f) =>
+    /\.(jsx?|tsx?)$/.test(f)
+  );
+
+  for (const file of files) {
+    const content = fs.readFileSync(file, "utf8");
+    if (!hasUseClient(content)) continue;
+
+    const exports = extractExportNames(content);
+    const relUrl = "/" + path.relative(componentsDir, file);
+
+    for (const name of exports) {
+      manifest[name] = {
+        id: relUrl,
+        name,
+        chunks: [relUrl],
+        _sourceFile: file, // used during build to match hashed chunks
+      };
+    }
+  }
+
+  return manifest;
+}
+
+function hasUseClient(content) {
+  // "use client" must appear as a directive at the top of the file
+  return /^\s*["']use client["']/m.test(content);
+}
+
+function extractExportNames(content) {
+  const names = new Set();
+
+  // export function Foo
+  // export const Foo
+  // export class Foo
+  const namedRe = /export\s+(?:default\s+)?(?:function|const|class|let|var)\s+([A-Z][A-Za-z0-9]*)/g;
+  let m;
+  while ((m = namedRe.exec(content)) !== null) {
+    names.add(m[1]);
+  }
+
+  // export { Foo, Bar }
+  const bracedRe = /export\s+\{([^}]+)\}/g;
+  while ((m = bracedRe.exec(content)) !== null) {
+    for (const part of m[1].split(",")) {
+      const name = part.trim().split(/\s+as\s+/).pop().trim();
+      if (/^[A-Z]/.test(name)) names.add(name);
+    }
+  }
+
+  return Array.from(names);
+}
+
+function writeManifest(outputPath, manifest) {
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, JSON.stringify(manifest, null, 2));
+}
+
+function walkDir(dir) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkDir(full));
+    } else {
+      results.push(full);
+    }
+  }
+  return results;
+}

data/lib/generators/ruact/install/install_generator.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "ruact"
+
+module Ruact
+  module Generators
+    # Installs ruact into the current Rails application.
+    #
+    # Performs the following actions:
+    # 1. Creates config/initializers/ruact.rb
+    # 2. Injects `include Ruact::Controller` into ApplicationController
+    # 3. Injects the React root div into app/views/layouts/application.html.erb
+    # 4. Creates app/javascript/components/.keep
+    # 5. Creates vite.config.js (or shows manual instructions if one exists)
+    # 6. Creates app/javascript/application.jsx (or skips if one exists)
+    #
+    # Run: rails generate ruact:install
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs ruact into the current Rails application"
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/ruact.rb"
+      end
+
+      def inject_controller_concern
+        controller_file = "app/controllers/application_controller.rb"
+        return unless File.exist?(destination_root.join(controller_file))
+
+        content = File.read(destination_root.join(controller_file))
+        if content.include?("Ruact::Controller")
+          say_status "skip", "Ruact::Controller already included in ApplicationController", :yellow
+          return
+        end
+
+        inject_into_file controller_file,
+                         "\n  include Ruact::Controller\n",
+                         after: /class ApplicationController.*\n/
+      end
+
+      def inject_layout_shell
+        layout_file = "app/views/layouts/application.html.erb"
+        return unless File.exist?(destination_root.join(layout_file))
+
+        content = File.read(destination_root.join(layout_file))
+        if content.include?("ruact: root")
+          say_status "skip", "Rails RSC root already present in layout", :yellow
+          return
+        end
+
+        inject_into_file layout_file,
+                         "\n    <%# ruact: root %>\n    <div id=\"root\"></div>\n",
+                         before: "  </body>"
+      end
+
+      def create_components_directory
+        empty_directory "app/javascript/components"
+        create_file "app/javascript/components/.keep" unless
+          File.exist?(destination_root.join("app/javascript/components/.keep"))
+      end
+
+      def create_vite_config
+        vite_config_file = destination_root.join("vite.config.js")
+
+        if vite_config_file.exist?
+          say_status "notice", "vite.config.js already exists — add the plugin manually:", :yellow
+          say "  1. At the top of vite.config.js, add:"
+          say "       import ruact from '#{Ruact.vite_plugin_path}';"
+          say "  2. In the plugins array, add: ruact()"
+          say ""
+          say "  Re-run `rails generate ruact:install --force` to overwrite vite.config.js."
+        else
+          template "vite.config.js.tt", "vite.config.js"
+        end
+      end
+
+      def create_javascript_entry
+        template "application.jsx.tt", "app/javascript/application.jsx"
+      end
+
+      def show_post_install_message
+        say ""
+        say "=" * 60
+        say "  ruact installed successfully!"
+        say "=" * 60
+        say ""
+        say "Next steps:"
+        say "  1. Start the Vite dev server:  npm run dev"
+        say "  2. Start Rails:                rails server"
+        say "  3. Add <MyComponent /> to any ERB view"
+        say ""
+        say "Note: Re-run this generator after updating the ruact gem"
+        say "to refresh the bundled Vite plugin path in vite.config.js."
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/ruact/install/templates/application.jsx.tt

@@ -0,0 +1,51 @@
+import { createRoot } from 'react-dom/client';
+import { useState, useEffect } from 'react';
+import { createFromFlightPayload } from './flight-client.js';
+import { setupRouter, teardownRouter } from './rsc-router.js';
+
+// MODULE_REGISTRY maps react-client-manifest "id" values to component exports.
+// Add each "use client" component here as you create it.
+// Keys must match the "id" field in public/react-client-manifest.json.
+//
+// Example:
+//   import { MyButton } from './components/MyButton.jsx';
+//   const MODULE_REGISTRY = { '/MyButton.jsx': { MyButton } };
+const MODULE_REGISTRY = {};
+
+// ---------------------------------------------------------------------------
+// Boot
+// ---------------------------------------------------------------------------
+const flightData = globalThis.__FLIGHT_DATA;
+
+if (!flightData || flightData.length === 0) {
+  // Non-RSC page or Rails server not running — skip hydration.
+  const root = document.getElementById('root');
+  if (root && root.childNodes.length === 0) {
+    root.textContent = '[ruact] No Flight data found — is the Rails server running?';
+  }
+} else {
+  const payload = flightData.join('');
+
+  let initialTree;
+  try {
+    initialTree = createFromFlightPayload(payload, MODULE_REGISTRY);
+  } catch (err) {
+    console.error('[ruact] Failed to parse Flight payload:', err);
+    const root = document.getElementById('root');
+    if (root) root.textContent = '[ruact] Error: ' + err.message;
+    throw err;
+  }
+
+  function App() {
+    const [tree, setTree] = useState(() => initialTree);
+
+    useEffect(() => {
+      setupRouter({ onNavigate: setTree, moduleRegistry: MODULE_REGISTRY });
+      return () => teardownRouter();
+    }, []);
+
+    return tree;
+  }
+
+  createRoot(document.getElementById('root')).render(<App />);
+}

data/lib/generators/ruact/install/templates/initializer.rb.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+Ruact.configure do |config|
+  # Path to the react-client-manifest.json generated by the Vite plugin.
+  # Defaults to Rails.root.join("public/react-client-manifest.json").
+  # config.manifest_path = Rails.root.join("public", "react-client-manifest.json")
+
+  # When true, objects without explicit rsc_props declaration raise
+  # Ruact::SerializationError instead of falling back to as_json.
+  # Recommended: true in production to prevent accidental attribute exposure.
+  # config.strict_serialization = Rails.env.production?
+
+  # Timeout in seconds for deferred Suspense chunks. Default: 5.0.
+  # config.suspense_timeout = 5.0
+
+  # Base URL of the Vite dev server. Default: "http://localhost:5173".
+  # config.vite_dev_server = "http://localhost:5173"
+end

data/lib/generators/ruact/install/templates/vite.config.js.tt

@@ -0,0 +1,26 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+// Bundled Vite plugin — path resolved from the installed ruact gem.
+// Re-run `rails generate ruact:install` after gem upgrades to refresh this path.
+import ruact from '<%= Ruact.vite_plugin_path %>';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    ruact(), // scans app/javascript/components/ for "use client", emits react-client-manifest.json
+  ],
+
+  build: {
+    outDir: 'public/assets',
+    manifest: true,
+    rollupOptions: {
+      input: 'app/javascript/application.jsx',
+    },
+  },
+
+  server: {
+    port: 5173,
+    strictPort: true,
+    origin: 'http://localhost:5173',
+  },
+});

data/lib/ruact/client_manifest.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ruact
+  # Reads the react-client-manifest.json emitted by the Vite plugin and
+  # resolves component names to Flight ClientReferences.
+  #
+  # Manifest format (one entry per "use client" export):
+  #   {
+  #     "LikeButton": {
+  #       "id":     "/assets/LikeButton-abc123.js",
+  #       "chunks": ["/assets/LikeButton-abc123.js"],
+  #       "name":   "LikeButton"
+  #     },
+  #     "posts/_like_button": {
+  #       "id":     "/assets/posts/_like_button-abc123.js",
+  #       "chunks": ["/assets/posts/_like_button-abc123.js"],
+  #       "name":   "default"
+  #     }
+  #   }
+  class ClientManifest
+    # Used by Flight::Serializer to produce I rows.
+    # Returns the metadata array the client expects: [id, name, chunks]
+    def resolve(module_id, _export_name)
+      entry = by_module_id(module_id)
+      raise "ClientManifest: no entry for module_id=#{module_id.inspect}" unless entry
+
+      [entry["id"], entry["name"], entry["chunks"]]
+    end
+
+    # Returns true if +name+ is a top-level key in the manifest data.
+    # Used by the dual-path resolver to check co-located key existence before fallback.
+    def include?(name)
+      entries_by_name.key?(name)
+    end
+
+    # Resolve a component name (e.g. "LikeButton") → ClientReference.
+    #
+    # When +controller_path+ is provided (e.g. "posts"), the resolver first
+    # looks for a co-located key ("posts/_like_button"). If found, it returns
+    # that reference; otherwise it falls back to the shared PascalCase key.
+    #
+    # Returns the same object for repeated calls with the same resolved key
+    # (needed for dedup by object_id in Flight::Serializer).
+    # Raises if the resolved name is not found in the manifest.
+    def reference_for(name, controller_path: nil)
+      @reference_cache ||= {}
+      key = resolve_key(name, controller_path)
+      @reference_cache[key] ||= begin
+        entry = entries_by_name[key]
+        unless entry
+          raise ManifestError,
+                "Component #{name.inspect} not found in manifest — " \
+                "Did you run the Vite build? Run 'npm run build' or start the Vite dev server."
+        end
+
+        Flight::ClientReference.new(module_id: entry["id"], export_name: name)
+      end
+    end
+
+    # Load from a file path (JSON).
+    # Pre-warms the reference cache and freezes the manifest so it cannot be
+    # mutated at runtime (AC#5). Pre-warming is required because Ruby's freeze
+    # is shallow: instance variable assignment on a frozen object raises
+    # FrozenError, so @reference_cache must already be set before freeze.
+    def self.load(path)
+      raw      = File.read(path)
+      data     = JSON.parse(raw)
+      manifest = from_hash(data)
+      data.each_key { |name| manifest.reference_for(name) }
+      manifest.freeze
+    end
+
+    # Build from an already-parsed Hash (useful in tests).
+    def self.from_hash(data)
+      manifest = new
+      manifest.instance_variable_set(:@data, data)
+      manifest
+    end
+
+    private
+
+    # Returns the manifest key to use for +name+ given an optional +controller_path+.
+    # Co-located key format: "<controller_path>/_<underscored_name>" (e.g. "posts/_like_button").
+    # Co-located takes precedence when both keys exist.
+    def resolve_key(name, controller_path)
+      return name unless controller_path
+
+      co_located = "#{controller_path}/_#{rsc_underscore(name)}"
+      include?(co_located) ? co_located : name
+    end
+
+    # Converts PascalCase component names to snake_case without requiring ActiveSupport.
+    # Equivalent to ActiveSupport::Inflector.underscore for PascalCase inputs.
+    def rsc_underscore(name)
+      name.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .downcase
+    end
+
+    def data
+      @data ||= {}
+    end
+
+    # Index by component name for fast lookup
+    def entries_by_name
+      @entries_by_name ||= data
+    end
+
+    def by_module_id(id)
+      data.values.find { |entry| entry["id"] == id }
+    end
+  end
+end

data/lib/ruact/component_registry.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Holds the client components encountered during ERB rendering.
+  # Thread-local so it's safe under concurrent requests.
+  module ComponentRegistry
+    THREAD_KEY = :__rsc_component_registry__
+
+    def self.start
+      Thread.current[THREAD_KEY] = [] # rubocop:disable Ruact/NoSharedState -- TODO: refactor to explicit arg passing (NFR8)
+    end
+
+    def self.register(name, props)
+      token = "__RSC_#{components.length}__"
+      components << { token: token, name: name, props: props }
+      token
+    end
+
+    def self.components
+      Thread.current[THREAD_KEY] ||= [] # rubocop:disable Ruact/NoSharedState -- TODO: refactor to explicit arg passing (NFR8)
+    end
+
+    def self.reset
+      Thread.current[THREAD_KEY] = nil # rubocop:disable Ruact/NoSharedState -- TODO: refactor to explicit arg passing (NFR8)
+    end
+
+    def self.by_token(token)
+      components.find { |c| c[:token] == token }
+    end
+  end
+end

data/lib/ruact/configuration.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Holds gem-wide configuration. Instantiated once via Ruact.config.
+  # Configure via Ruact.configure { |c| c.attr = value } in an initializer.
+  class Configuration
+    # @return [String, nil] Path to react-client-manifest.json.
+    #   Defaults to Rails.root.join("public/react-client-manifest.json") when nil.
+    attr_accessor :manifest_path
+
+    # @return [Boolean] When true, objects without explicit rsc_props declaration
+    #   raise Ruact::SerializationError. Defaults to false in development, true in production.
+    attr_accessor :strict_serialization
+
+    # @return [Float] Seconds before a deferred Suspense chunk times out. Default: 5.0.
+    attr_accessor :suspense_timeout
+
+    # @return [String] Base URL of the Vite dev server. Default: "http://localhost:5173".
+    attr_accessor :vite_dev_server
+
+    def initialize
+      @manifest_path        = nil
+      @strict_serialization = begin
+        Rails.env.production?
+      rescue StandardError
+        false
+      end
+      @suspense_timeout     = 5.0
+      @vite_dev_server      = "http://localhost:5173"
+    end
+  end
+end