raindown 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fab4cc96057c97d8a6c5ef07b11e12fda146e25855ac2015f667e838b1c805d
-  data.tar.gz: 1b9044d112a1d05773bb22bfdc4767264ad190c24bceb49b82733ecd1989a026
+  metadata.gz: ad54482b1bd78c23942aefb02bc8a8b9cce56e369ecbb67366668187ed521323
+  data.tar.gz: 9d8475c719c52063424a6215c762a926e67641700981b6834dd56e07d410d535
 SHA512:
-  metadata.gz: 1cf8132950f24d3005113635835426471514a7c79312cac8379e66d93c3345b32e9788e2f86c73eb80e4050d757eab4bcb7c08ef8ad6a3c41aad2808493a6c5b
-  data.tar.gz: f1c47f511df4d7d9725c60f30fb0e3a0af3e762e197d510ec55eafe9ad01db51f0cefa6b6b2a684e1e5a37fb2654fbe1c8fc91c07e8b5a815e576df51b617682
+  metadata.gz: 8789f0135781bfe782ae2af47f2bd537cafef9d55a522ba592bbcc1c8f27e0364cfbb860cb0aa106617af0bd6e82d2bd0174084ca4bd3ca7779b82e2e284ff79
+  data.tar.gz: 88237d0429270a0651434511d462b0051b9a752a2e8aae315e4d2bafc0ef833fa1818d8424cf5e025b12655c9df3de6a22e6eab7e23e1b40ec0063d7fe4f3396

data/lib/raindown/actions.rb

@@ -31,7 +31,7 @@ module Raindown
       raise NotAnEndpoint, "#{directive.name} on line #{directive.line} isn't an endpoint" unless directive.endpoint?
       raise NotAnEndpoint, "The endpoint on line #{directive.line} only renders, so put it in comments to run it" unless directive.writes
 
-      content = File.read(path, encoding: Encoding::UTF_8)
+      content = Utils.read_markdown(path)
       rewritten = EndpointRunner.new(content:, bare: BareDirectives.enabled?(path:, content:), only: directive.line - 1).rewrite
       return false if rewritten == content
 

data/lib/raindown/document.rb

@@ -39,7 +39,7 @@ module Raindown
     # they're allowed, like with --bare.
     # A project's own nodes are only directives once they're loaded, like with Nodes.load(path), the same as when the file renders.
     def self.read(path, bare: false)
-      new(markdown: File.read(path, encoding: Encoding::UTF_8), bare: bare || BareDirectives.file?(path))
+      new(markdown: Utils.read_markdown(path), bare: bare || BareDirectives.file?(path))
     end
 
     def initialize(markdown:, bare: false)

data/lib/raindown/js/host.mjs

@@ -0,0 +1,51 @@
+// Runs a project's JavaScript Components for Raindown, which starts it with node -e, since inside Raindown's package
+// the script is where NodeJS can't read it. Each line on stdin is a request, answered by one line of JSON on stdout:
+//   { op: 'load', folder }                → { nodes: [{ name, render }] }
+//   { op: 'new', id, name, args, props }  → {}
+//   { op: 'call', id, method, context }   → { value }
+// A request that throws is answered with { error }.
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { createInterface } from 'node:readline'
+import { pathToFileURL } from 'node:url'
+
+// stdout carries the replies, so what nodes log goes to stderr.
+console.log = console.info = console.error
+
+const classes = {}
+const nodes = {}
+
+const requests = {
+  // Every exported class with replace is a node, named by its export, or by its class for a default export.
+  async load({ folder }) {
+    for (const file of readdirSync(folder).filter((file) => /\.m?js$/.test(file))) {
+      const exports = await import(pathToFileURL(join(folder, file)).href)
+
+      for (const [name, value] of Object.entries(exports)) {
+        if (typeof value?.prototype?.replace === 'function') classes[name === 'default' ? value.name : name] = value
+      }
+    }
+
+    const nodes = Object.entries(classes).map(([name, node]) => ({ name, render: typeof node.prototype.render === 'function' }))
+    return { nodes }
+  },
+
+  new({ id, name, args, props }) {
+    nodes[id] = new classes[name](props, ...args)
+    return {}
+  },
+
+  async call({ id, method, context }) {
+    return { value: await nodes[id][method](context) }
+  },
+}
+
+for await (const line of createInterface({ input: process.stdin })) {
+  const request = JSON.parse(line)
+
+  try {
+    process.stdout.write(`${JSON.stringify(await requests[request.op](request))}\n`)
+  } catch (error) {
+    process.stdout.write(`${JSON.stringify({ error: String(error?.message ?? error) })}\n`)
+  }
+}

data/lib/raindown/js/js_nodes.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+
+require_relative '../node'
+
+module Raindown
+  # JavaScript Components, the .js and .mjs files in a project's .raindown folder, which export classes with replace and
+  # optionally render, like Ruby nodes. They run in a NodeJS process of Raindown's own, started when a folder has them,
+  # so only projects with JavaScript Components need NodeJS.
+  module JSNodes
+    EXTENSIONS = %w[.js .mjs].freeze
+    SCRIPT = File.join(__dir__, 'host.mjs')
+
+    class Error < StandardError; end
+
+    # The NodeJS process running the nodes, which answers each request with a line of JSON. NodeJS can't read the script
+    # inside Raindown's package, so it's passed to node -e.
+    class Host
+      def initialize
+        @input, @output, = Open3.popen2('node', '--input-type=module', '-e', File.read(SCRIPT))
+      rescue Errno::ENOENT
+        raise Error, 'JavaScript Components need NodeJS 22 or later on your PATH'
+      end
+
+      def request(**message)
+        @input.puts(JSON.generate(message))
+        reply = JSON.parse(@output.gets || raise(Error, 'NodeJS stopped running the JavaScript Components'))
+        raise Error, reply['error'] if reply['error']
+
+        reply
+      end
+    end
+
+    module_function
+
+    # Loads the JavaScript Components in a .raindown folder, starting NodeJS the first time a folder has any.
+    def load(folder)
+      return if Dir.glob(EXTENSIONS.map { "*#{it}" }, base: folder).empty?
+
+      host.request(op: 'load', folder:).fetch('nodes').each do |node|
+        node_classes[node['name']] ||= JSNode.for(name: node['name'], render: node['render'])
+      end
+    end
+
+    def node_class(name)
+      node_classes[name]
+    end
+
+    def host
+      @host ||= Host.new
+    end
+
+    def node_classes
+      @node_classes ||= {}
+    end
+  end
+
+  # A JavaScript Component, made in the NodeJS process with its props, where its replace and render are sent.
+  class JSNode < Node
+    # A class for each JavaScript Component, which renders its own HTML when the component has render.
+    def self.for(name:, render:)
+      Class.new(self) do
+        define_singleton_method(:name) { name }
+        define_method(:render) { |**context| js_output(:render, context) } if render
+      end
+    end
+
+    def initialize(*args, **props)
+      super()
+      JSNodes.host.request(op: 'new', id: object_id, name: self.class.name, args:, props:)
+    end
+
+    def replace(**context)
+      js_output(:replace, context)
+    end
+
+    private
+
+    def js_output(method, context)
+      JSNodes.host.request(op: 'call', id: object_id, method:, context: json_context(**context)).fetch('value').to_s
+    end
+
+    # JSON can't hold Pages, so the metadata is its root and each file's front matter and path.
+    def json_context(metadata: NoMetadata, **context)
+      root = metadata.root if metadata.respond_to?(:root)
+      { **context, metadata: { root:, files: metadata.list.map(&:metadata) } }
+    end
+  end
+end

data/lib/raindown/nodes.rb

@@ -2,13 +2,14 @@
 
 require_relative 'chart/chart'
 require_relative 'files'
+require_relative 'js/js_nodes'
 require_relative 'node'
 require_relative 'stat'
 require_relative 'toc'
 
 module Raindown
   # Nodes are LowNodes that a node block writes into the Markdown and renders into the HTML.
-  # A project keeps them in a .raindown folder, which is loaded with Dirload.
+  # A project keeps them in a .raindown folder, which is loaded with Dirload, beside its JavaScript Components, if any.
   # A node writes Markdown with #replace, and HTML with #render if it has one. Either can take the keywords
   # document: (the Markdown being rendered), metadata: and bare:, and gets the ones it asks for.
   module Nodes
@@ -29,6 +30,7 @@ module Raindown
       require 'dirload'
       loaded << folder
       dirload(folder)
+      JSNodes.load(folder)
     end
 
     def find_folder(directory)
@@ -54,11 +56,12 @@ module Raindown
       loaded_class(BUILT_INS[name]) || Raindown.const_get(BUILT_INS[name])
     end
 
+    # A Ruby node of the name, or else a JavaScript one.
     def loaded_class(name)
-      klass = Object.const_get(name)
-      klass if node?(klass)
-    rescue NameError
-      nil
+      klass = Object.const_get(name) if Object.const_defined?(name)
+      return klass if node?(klass)
+
+      JSNodes.node_class(name)
     end
 
     # A LowNode, or one of Raindown's own nodes, that writes Markdown. In an app, LowNodes are also routes and pages,

data/lib/raindown/page.rb

@@ -17,7 +17,7 @@ module Raindown
     # It follows the file's project config, like render_file, unless the render options say otherwise.
     def content
       @content ||= begin
-        markdown = File.read(file_path, encoding: Encoding::UTF_8)
+        markdown = Utils.read_markdown(file_path)
 
         if FrontMatter.parse(markdown).last.strip.empty? then ''
         else Raindown.render(markdown:, bare: BareDirectives.file?(file_path), **Config.render_options(file_path).merge(@render_options))

data/lib/raindown/pages.rb

@@ -2,6 +2,7 @@
 
 require_relative 'front_matter'
 require_relative 'page'
+require_relative 'utils'
 
 module Raindown
   # The metadata of a project's Markdown files, which list: and files: list by tag.
@@ -62,7 +63,7 @@ module Raindown
     end
 
     def process(file_path:)
-      metadata = implicit_metadata(file_path:).merge(FrontMatter.parse(File.read(file_path, encoding: Encoding::UTF_8)).first)
+      metadata = implicit_metadata(file_path:).merge(FrontMatter.parse(Utils.read_markdown(file_path)).first)
       @metadata[file_path] = metadata
       metadata.each { |type, tag| Array(tag).each { |item| tag(type:, tag: item, file_path:) } }
     end

data/lib/raindown/projects.rb

@@ -10,6 +10,8 @@ module Raindown
   module Projects
     # Folders of dependencies, builds and tooling, which aren't searched for projects or watched, nor are hidden folders.
     IGNORED = %w[node_modules vendor tmp pkg build dist coverage].freeze
+    # Ruby nodes and JavaScript Components.
+    NODE_EXTENSIONS = ['.rb', '.rbx', *JSNodes::EXTENSIONS].freeze
 
     module_function
 
@@ -61,7 +63,7 @@ module Raindown
 
     # Whether a file is one of a project's own nodes, which load when its watcher starts.
     def node?(path, root:)
-      File.expand_path(path).start_with?(File.join(root, Nodes::FOLDER, '')) && %w[.rb .rbx].include?(File.extname(path))
+      File.expand_path(path).start_with?(File.join(root, Nodes::FOLDER, '')) && NODE_EXTENSIONS.include?(File.extname(path))
     end
 
     def project?(folder)

data/lib/raindown/rewriter.rb

@@ -3,6 +3,7 @@
 require_relative 'node_injector'
 require_relative 'endpoint/endpoint_runner'
 require_relative 'table_formatter'
+require_relative 'utils'
 
 module Raindown
   # Rewrites the generated parts of a Markdown file in place before it's rendered:
@@ -21,7 +22,7 @@ module Raindown
 
     # Returns true when the file changed.
     def update(path:, bare: false, execute: false, metadata: NoMetadata)
-      content = File.read(path, encoding: Encoding::UTF_8)
+      content = Utils.read_markdown(path)
       rewritten = rewrite(content:, path:, bare:, execute:, metadata:)
       return false if rewritten == content
 

data/lib/raindown/tui/project.rb

@@ -65,7 +65,7 @@ module Raindown
       # the ones whose snippet can't be read.
       def endpoints
         Projects.files(root).flat_map do |path|
-          lines = File.readlines(path, encoding: Encoding::UTF_8)
+          lines = Utils.read_markdown(path).lines
           runnable = Document.read(path, bare: @bare).directives.select { it.endpoint? && it.writes }
           runnable.filter_map { |directive| endpoint(path, lines, directive) }
         rescue StandardError
@@ -94,7 +94,7 @@ module Raindown
       end
 
       def charts_in(path)
-        content = File.read(path, encoding: Encoding::UTF_8)
+        content = Utils.read_markdown(path)
         bare = @bare || BareDirectives.enabled?(path:, content:)
         lines = content.lines
         headings = Document.parse(content, bare:).headings

data/lib/raindown/tui/terminal/input.rb

@@ -34,7 +34,7 @@ module Raindown
         Curses.stdscr.timeout = timeout
         key = Curses.stdscr.getch
         return :tick if key.nil?
-        return mouse(zones) if key == Curses::KEY_MOUSE
+        return mouse(zones) if MOUSE && key == Curses::KEY_MOUSE
 
         Curses.stdscr.clear if key == Curses::KEY_RESIZE
         key_event(key, typing:)
@@ -60,22 +60,27 @@ module Raindown
         TYPING_KEYS.fetch(key) { Type.new(text: key) if key.is_a?(String) && key.match?(/\A[[:print:]]\z/) }
       end
 
+      # Windows' curses has no mouse, so the curses gem leaves out its constants and the mouse does nothing there.
+      MOUSE = Curses.respond_to?(:mousemask)
+
       # The mouse buttons that click, which are the left button's. Scrolling does nothing, and since older ncurses,
       # like macOS's, has no button for scrolling down, it can't be mistaken for a click.
-      CLICKS = Curses::BUTTON1_PRESSED | Curses::BUTTON1_CLICKED
+      CLICKS = MOUSE && Curses::BUTTON1_PRESSED | Curses::BUTTON1_CLICKED
 
       # Letting go of the button, which older ncurses, like macOS's, also reports for each move while it's held, as it
       # doesn't know the moves terminals send then.
-      RELEASE = Curses::BUTTON1_RELEASED
+      RELEASE = MOUSE && Curses::BUTTON1_RELEASED
 
       # Moving the mouse, which terminals report once they're asked to, with any motion tracking.
-      MOTION = Curses::REPORT_MOUSE_POSITION
+      MOTION = MOUSE && Curses::REPORT_MOUSE_POSITION
       ANY_MOTION = "\e[?1003h"
       NO_MOTION = "\e[?1003l"
 
       # The terminal sends the app its mouse events, clicks and moves, so scrolling doesn't scroll the terminal either.
       # ncurses only asks some terminals to report every move, so it's asked directly too, until untrack_mouse.
       def track_mouse
+        return unless MOUSE
+
         Curses.mousemask(CLICKS | RELEASE | MOTION)
         Curses.mouseinterval(0)
         $stdout.write(ANY_MOTION)
@@ -83,6 +88,8 @@ module Raindown
       end
 
       def untrack_mouse
+        return unless MOUSE
+
         $stdout.write(NO_MOTION)
         $stdout.flush
       end

data/lib/raindown/utils.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Raindown
+  module Utils
+    module_function
+
+    # A Markdown file's text, with its line endings as LF, "\n", whatever they are in the file.
+    #
+    # Windows ends lines with CRLF, "\r\n", and Git for Windows checks files out that way, so a file written or cloned on
+    # Windows can reach Raindown with them on any platform. Raindown finds directives, like a bare toc:, front matter
+    # and code fences line by line, with patterns that end at "\n", so a "\r" left at the end of a line stops them
+    # matching: toc: would be left as text instead of writing its table of contents.
+    #
+    # Text mode ("rt") reads CRLF as LF on every platform, as Ruby does on Windows by default, so the rest of Raindown
+    # only ever sees "\n". Writing a file back then gives it LF line endings, except on Windows, where text mode writes
+    # CRLF again.
+    def read_markdown(path)
+      File.read(path, mode: 'rt', encoding: Encoding::UTF_8)
+    end
+  end
+end

data/lib/raindown.rb

@@ -15,6 +15,7 @@ require_relative 'raindown/heading_ids'
 require_relative 'raindown/node_blocks'
 require_relative 'raindown/pages'
 require_relative 'raindown/pre_renderer'
+require_relative 'raindown/utils'
 require_relative 'raindown/variables'
 
 module Raindown
@@ -40,7 +41,7 @@ module Raindown
   # Code is highlighted, unless the file's project changes it in .raindown/config.yml.
   def render_file(path:, metadata: NoMetadata, bare: false, **options)
     options = Config.render_options(path).merge(options)
-    render(markdown: File.read(path, encoding: Encoding::UTF_8), metadata:, bare: bare || BareDirectives.file?(path), **options)
+    render(markdown: Utils.read_markdown(path), metadata:, bare: bare || BareDirectives.file?(path), **options)
   end
 
   # Front matter keys are variables, like {title} or <{ title }>.

data/lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Raindown
-  VERSION = '0.8.1'
+  VERSION = '0.9.0'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: raindown
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.9.0
 platform: ruby
 authors:
 - maedi
 bindir: bin
 cert_chain: []
-date: 2026-11-02 00:00:00.000000000 Z
+date: 2026-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: antlers
@@ -217,6 +217,8 @@ files:
 - lib/raindown/fragments.rb
 - lib/raindown/front_matter.rb
 - lib/raindown/heading_ids.rb
+- lib/raindown/js/host.mjs
+- lib/raindown/js/js_nodes.rb
 - lib/raindown/node.rb
 - lib/raindown/node_blocks.rb
 - lib/raindown/node_injector.rb
@@ -295,6 +297,7 @@ files:
 - lib/raindown/tui/views/endpoint_view.rb
 - lib/raindown/tui/views/list_view.rb
 - lib/raindown/tui/views/outline_view.rb
+- lib/raindown/utils.rb
 - lib/raindown/variables.rb
 - lib/raindown/watcher/changes.rb
 - lib/raindown/watcher/file_watcher.rb