RubyGems - skybolt - Versions diffs - 3.2.0 - Mend

skybolt 3.2.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 (7) hide show

checksums.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 730d6c870bd053421958e83321177a1f55f6d394eab14243c9db126d1177eb8b
+  data.tar.gz: '0883ef34760b719f36ec6e9221518f1034f3b9e3853f1bd54fb2432148adf446'
+SHA512:
+  metadata.gz: ee08f62ab0bebbca2522022a22c52c1f3c00a8b30f27104c3e54487e963d4bf47ff03d23efac0ca34f5b825fba121090ebd2e1a8627be62305de5c400e586b49
+  data.tar.gz: af5ab159945553fbbf348e1e81ab706f4ee6d6d5c2a2a4c73d54ae843afec1aa4365bea3b36d1eaae8e7590f5e318e0597d721494b6f55c1d086758adf307ae6

data/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025 Jens Roland
+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 ADDED Viewed

@@ -0,0 +1,287 @@
+# Skybolt Ruby
+Ruby adapter for [Skybolt](https://github.com/JensRoland/skybolt) - High-performance asset caching for multi-page applications.
+## Installation
+Add to your Gemfile:
+```ruby
+gem "skybolt"
+```
+Then run:
+```bash
+bundle install
+```
+## Prerequisites
+1. Install and configure the Vite plugin: `npm install @skybolt/vite-plugin`
+2. Build your project: `npm run build`
+3. Ensure `render-map.json` is generated in your build output
+## Usage
+```ruby
+require "skybolt"
+sb = Skybolt::Renderer.new(
+  "public/dist/.skybolt/render-map.json",
+  cookies: request.cookies
+)
+```
+```erb
+<!DOCTYPE html>
+<html>
+<head>
+    <%= raw sb.css("src/css/critical.css") %>
+    <%= raw sb.launch_script %>
+    <%= raw sb.css("src/css/main.css") %>
+</head>
+<body>
+    <h1>Hello Skybolt!</h1>
+    <%= raw sb.script("src/js/app.js") %>
+</body>
+</html>
+```
+## API
+### `Skybolt::Renderer.new(render_map_path, cookies: nil, cdn_url: nil)`
+Create a new Skybolt renderer.
+- `render_map_path` - Path to `render-map.json` generated by Vite plugin
+- `cookies:` - Cookie hash (defaults to `nil`)
+- `cdn_url:` - Optional CDN URL prefix (e.g., `'https://cdn.example.com'`)
+```ruby
+# Basic usage
+sb = Skybolt::Renderer.new(
+  "public/dist/.skybolt/render-map.json",
+  cookies: request.cookies
+)
+# With CDN
+sb = Skybolt::Renderer.new(
+  "public/dist/.skybolt/render-map.json",
+  cookies: request.cookies,
+  cdn_url: "https://cdn.example.com"
+)
+```
+### `css(entry) -> String`
+Render CSS asset.
+- First visit: Inlines CSS with caching attributes
+- Repeat visit: Outputs `<link>` tag (Service Worker serves from cache)
+```ruby
+sb.css("src/css/main.css")
+```
+### `script(entry, is_module: true) -> String`
+Render JavaScript asset.
+- First visit: Inlines JS with caching attributes
+- Repeat visit: Outputs `<script>` tag (Service Worker serves from cache)
+```ruby
+# ES module (default)
+sb.script("src/js/app.js")
+# Classic script
+sb.script("src/js/legacy.js", is_module: false)
+```
+### `launch_script -> String`
+Render the Skybolt client launcher. Call once in `<head>` before other assets.
+```erb
+<head>
+    <%= raw sb.launch_script %>
+</head>
+```
+### `asset_url(entry) -> String?`
+Get the URL for an asset (for manual use cases).
+```ruby
+url = sb.asset_url("src/css/main.css")
+# "/assets/main-Pw3rT8vL.css"
+```
+### `asset_hash(entry) -> String?`
+Get the content hash for an asset.
+```ruby
+hash = sb.asset_hash("src/css/main.css")
+# "Pw3rT8vL"
+```
+### `preload(entry, as_type:, type: nil, crossorigin: nil, fetchpriority: nil) -> String`
+Render preload link for critical resources like fonts and images.
+```ruby
+# Preload hero image with high priority
+sb.preload("images/hero.jpg", as_type: "image", fetchpriority: "high")
+# Preload font
+sb.preload("fonts/inter.woff2", as_type: "font", type: "font/woff2", crossorigin: "anonymous")
+# Preload a Vite-built asset (resolved from render-map)
+sb.preload("src/css/main.css", as_type: "style")
+```
+Parameters:
+- `entry` - Source file path or direct URL
+- `as_type:` - Resource type (`'image'`, `'font'`, `'style'`, `'script'`, `'fetch'`)
+- `type:` - MIME type (e.g., `'font/woff2'`, `'image/webp'`)
+- `crossorigin:` - Crossorigin attribute (`'anonymous'`, `'use-credentials'`)
+- `fetchpriority:` - Fetch priority (`'high'`, `'low'`, `'auto'`)
+## Service Worker Setup
+The Service Worker must be served from your domain root. Configure your web server:
+**Nginx:**
+```nginx
+location = /skybolt-sw.js {
+    alias /path/to/public/dist/skybolt-sw.js;
+}
+```
+**Apache (.htaccess):**
+```apache
+RewriteRule ^skybolt-sw\.js$ public/dist/skybolt-sw.js [L]
+```
+## Framework Integration
+### Rails
+```ruby
+# app/helpers/skybolt_helper.rb
+module SkyboltHelper
+  def skybolt
+    @skybolt ||= Skybolt::Renderer.new(
+      Rails.root.join("public/dist/.skybolt/render-map.json").to_s,
+      cookies: cookies.to_h
+    )
+  end
+end
+```
+```erb
+<%# app/views/layouts/application.html.erb %>
+<!DOCTYPE html>
+<html>
+<head>
+    <%= raw skybolt.css("app/assets/stylesheets/critical.css") %>
+    <%= raw skybolt.launch_script %>
+    <%= raw skybolt.css("app/assets/stylesheets/application.css") %>
+</head>
+<body>
+    <%= yield %>
+    <%= raw skybolt.script("app/javascript/application.js") %>
+</body>
+</html>
+```
+### Sinatra
+```ruby
+require "sinatra"
+require "skybolt"
+helpers do
+  def skybolt
+    @skybolt ||= Skybolt::Renderer.new(
+      "public/dist/.skybolt/render-map.json",
+      cookies: request.cookies
+    )
+  end
+end
+get "/" do
+  erb :index
+end
+```
+```erb
+<%# views/index.erb %>
+<!DOCTYPE html>
+<html>
+<head>
+    <%= raw skybolt.css("src/css/critical.css") %>
+    <%= raw skybolt.launch_script %>
+    <%= raw skybolt.css("src/css/main.css") %>
+</head>
+<body>
+    <h1>Hello Skybolt!</h1>
+    <%= raw skybolt.script("src/js/app.js") %>
+</body>
+</html>
+```
+### Hanami
+```ruby
+# app/actions/home/index.rb
+module MyApp
+  module Actions
+    module Home
+      class Index < MyApp::Action
+        def handle(request, response)
+          sb = Skybolt::Renderer.new(
+            "public/dist/.skybolt/render-map.json",
+            cookies: request.cookies
+          )
+          response.render(view, sb: sb)
+        end
+      end
+    end
+  end
+end
+```
+## Requirements
+- Ruby 3.0+
+- Vite with `@skybolt/vite-plugin`
+## Publishing
+This package is maintained in the [Skybolt monorepo](https://github.com/JensRoland/skybolt) and automatically synced to [skybolt-ruby](https://github.com/JensRoland/skybolt-ruby).
+To publish a new version, run one command from the `packages/ruby` directory:
+```sh
+./scripts/release.sh patch   # 3.1.0 → 3.1.1
+./scripts/release.sh minor   # 3.1.0 → 3.2.0
+./scripts/release.sh major   # 3.1.0 → 4.0.0
+```
+This automatically:
+1. Bumps the version in `VERSION`, `skybolt.gemspec`, and `lib/skybolt/version.rb`
+2. Commits and pushes to the monorepo
+3. Sync workflow pushes changes to the split repo
+4. `tag-version.yml` in the split repo creates the `v*` tag
+5. `publish.yml` builds and publishes to RubyGems using trusted publishing (OIDC)
+## License
+MIT

data/lib/skybolt/renderer.rb ADDED Viewed

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+require "json"
+require "cgi"
+require "uri"
+module Skybolt
+  # Skybolt asset renderer.
+  #
+  # Reads the render-map.json generated by @skybolt/vite-plugin and outputs
+  # optimized HTML tags with intelligent caching via Service Workers.
+  class Renderer
+    # @param render_map_path [String] Path to render-map.json generated by Vite plugin
+    # @param cookies [Hash, nil] Cookie hash (defaults to empty hash)
+    # @param cdn_url [String, nil] Optional CDN URL prefix
+    def initialize(render_map_path, cookies: nil, cdn_url: nil)
+      json = File.read(render_map_path)
+      @map = JSON.parse(json)
+      @client_cache = parse_cookie((cookies || {})["sb_assets"] || "")
+      @cdn_url = cdn_url&.chomp("/")
+    end
+    # Render CSS asset.
+    #
+    # On first visit: inlines CSS with sb-* attributes for caching
+    # On repeat visit: outputs <link> tag (Service Worker serves from cache)
+    #
+    # @param entry [String] Source file path (e.g., 'src/css/main.css')
+    # @return [String] HTML string
+    def css(entry)
+      asset = @map.dig("assets", entry)
+      return comment("Skybolt: asset not found: #{entry}") if asset.nil?
+      url = resolve_url(asset["url"])
+      # Client has current version - external link (SW serves from cache)
+      if cached?(entry, asset["hash"])
+        return %(<link rel="stylesheet" href="#{esc(url)}">)
+      end
+      # First visit - inline with cache attributes
+      %(<style sb-asset="#{esc(entry)}:#{esc(asset["hash"])}" sb-url="#{esc(url)}">#{asset["content"]}</style>)
+    end
+    # Render JavaScript asset.
+    #
+    # On first visit: inlines JS with sb-* attributes for caching
+    # On repeat visit: outputs <script> tag (Service Worker serves from cache)
+    #
+    # @param entry [String] Source file path (e.g., 'src/js/app.js')
+    # @param is_module [Boolean] Whether to load as ES module (default: true)
+    # @return [String] HTML string
+    def script(entry, is_module: true)
+      asset = @map.dig("assets", entry)
+      return comment("Skybolt: asset not found: #{entry}") if asset.nil?
+      url = resolve_url(asset["url"])
+      type_attr = is_module ? ' type="module"' : ""
+      # Client has current version - external script (SW serves from cache)
+      if cached?(entry, asset["hash"])
+        return %(<script#{type_attr} src="#{esc(url)}"></script>)
+      end
+      # First visit - inline with cache attributes
+      %(<script#{type_attr} sb-asset="#{esc(entry)}:#{esc(asset["hash"])}" sb-url="#{esc(url)}">#{asset["content"]}</script>)
+    end
+    # Render preload link for critical resources.
+    #
+    # Use this for fonts, images, or other resources that should load early.
+    # Preloaded resources are not cached by Skybolt's Service Worker.
+    #
+    # @param entry [String] Source file path or direct URL
+    # @param as_type [String] Resource type ('image', 'font', 'style', 'script', 'fetch')
+    # @param type [String, nil] MIME type (e.g., 'font/woff2', 'image/webp')
+    # @param crossorigin [String, nil] Crossorigin attribute ('anonymous', 'use-credentials')
+    # @param fetchpriority [String, nil] Fetch priority ('high', 'low', 'auto')
+    # @return [String] HTML string
+    def preload(entry, as_type:, type: nil, crossorigin: nil, fetchpriority: nil)
+      # Try to resolve from assets, fall back to using entry as URL
+      url = asset_url(entry) || entry
+      url = resolve_url(url)
+      attrs = {
+        rel: "preload",
+        href: url,
+        as: as_type
+      }
+      attrs[:type] = type if type
+      attrs[:crossorigin] = crossorigin if crossorigin
+      attrs[:fetchpriority] = fetchpriority if fetchpriority
+      build_tag("link", attrs)
+    end
+    # Render the Skybolt client launcher.
+    #
+    # Call this once in <head> before other Skybolt assets.
+    # Outputs config meta tag and client script.
+    #
+    # @return [String] HTML string
+    def launch_script
+      sw_path = @map.dig("serviceWorker", "path") || "/skybolt-sw.js"
+      config = { swPath: sw_path }.to_json
+      %(<meta name="skybolt-config" content="#{esc(config)}">\n<script type="module">#{@map.dig("client", "script")}</script>)
+    end
+    # Get URL for an asset (for manual use cases).
+    #
+    # @param entry [String] Source file path
+    # @return [String, nil] Asset URL or nil if not found
+    def asset_url(entry)
+      url = @map.dig("assets", entry, "url")
+      url ? resolve_url(url) : nil
+    end
+    # Get hash for an asset (for manual use cases).
+    #
+    # @param entry [String] Source file path
+    # @return [String, nil] Asset hash or nil if not found
+    def asset_hash(entry)
+      @map.dig("assets", entry, "hash")
+    end
+    private
+    def resolve_url(url)
+      return url if @cdn_url.nil?
+      return url if url.start_with?("http://", "https://", "//")
+      "#{@cdn_url}#{url}"
+    end
+    def cached?(entry, hash)
+      @client_cache[entry] == hash
+    end
+    def parse_cookie(cookie)
+      return {} if cookie.empty?
+      decoded = URI.decode_www_form_component(cookie)
+      cache = {}
+      decoded.split(",").each do |pair|
+        # Find last colon (hash doesn't contain colons, but paths might)
+        colon_pos = pair.rindex(":")
+        next if colon_pos.nil?
+        name = pair[0...colon_pos]
+        hash = pair[(colon_pos + 1)..]
+        cache[name] = hash
+      end
+      cache
+    end
+    def build_tag(tag, attrs)
+      attr_str = attrs.map { |k, v| %(#{k}="#{esc(v)}") }.join(" ")
+      "<#{tag} #{attr_str}>"
+    end
+    def esc(value)
+      CGI.escapeHTML(value.to_s)
+    end
+    def comment(text)
+      "<!-- #{esc(text)} -->"
+    end
+  end
+end

data/lib/skybolt/version.rb ADDED Viewed

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+module Skybolt
+  VERSION = "3.2.0"
+end

data/lib/skybolt.rb ADDED Viewed

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+require_relative "skybolt/version"
+require_relative "skybolt/renderer"
+module Skybolt
+  class Error < StandardError; end
+end

metadata ADDED Viewed

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: skybolt
+version: !ruby/object:Gem::Version
+  version: 3.2.0
+platform: ruby
+authors:
+- Jens Roland
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-11-27 00:00:00.000000000 Z
+dependencies: []
+description: Reads the render-map.json generated by @skybolt/vite-plugin and outputs
+  optimized HTML tags with intelligent caching via Service Workers.
+email:
+- mail@jensroland.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/skybolt.rb
+- lib/skybolt/renderer.rb
+- lib/skybolt/version.rb
+homepage: https://github.com/JensRoland/skybolt-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/JensRoland/skybolt-ruby
+  source_code_uri: https://github.com/JensRoland/skybolt-ruby
+  changelog_uri: https://github.com/JensRoland/skybolt-ruby/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: High-performance asset caching for multi-page applications
+test_files: []