turbo_desktop-rails 0.0.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b5500a9a8e4b248dc2b0f274ae9e45ea023ee609a7986ee5ec6882e23254537
-  data.tar.gz: 1fea19f6e2056e7b6cceb27f6eb5a4188dfdfed791f373347f40301abbe0cc29
+  metadata.gz: 28aa3a8403d578104476a660dd9ee06a6c89e662f16264f7142451413ba32963
+  data.tar.gz: 99e458936a6838a91b3aa205ed21931436b726a14758ba52d6bebeb6e643a35e
 SHA512:
-  metadata.gz: dd37b92667b4387a0b189a11b6abf1f2d4541ffa719807b46f7ff4b6c78a847294fea744be887d8053ffcdb4f8cb17dd3a9b44286b13960345fe70cf14f1c69e
-  data.tar.gz: f0698610d97df906b146bbb7371209eb18554a9dc816af5fbc75fa07c11fffb7b8644e4b6d9d92ac6666edc125fc4296cda285c50bc2fe7ed3f7a6a6daff0e6c
+  metadata.gz: 846e2a35b02b73557bfcfb11cde442d93d5a3b32be010cfaf0433d78c375650c41c143c17a35f14ce9d8f34e87e183f95a3a5a79dbe6e220b23557f4d1e5525e
+  data.tar.gz: c04b4ac951f6b2176af91eb021e6278602b814db6a99e74bd1d015a6562bb6c8020a5b8901b8ee78c2cb1b848006b2c9eaf1d491bfdf2116f9394671227fd330

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.2.2 (2026-09-27)
+
+Version aligned with the desktop shell's 0.2.2 release. The CLI now scaffolds
+new apps with `gem "turbo_desktop-rails", "~> 0.2"`; it previously wrote
+`"~> 0.1"`, which resolved to 0.1.1. First 0.2.x version published to RubyGems.
+No gem-side API changes.
+
+## 0.2.1 (2026-07-29)
+
+Version aligned with the desktop shell's 0.2.1 release, which fixes bridge
+events (shell/sudo output streaming, drag & drop, component onReceive) never
+reaching pages loaded from the app server. No gem-side API changes.
+
+## 0.2.0 (2026-07-29)
+
+Version aligned with the desktop shell's 0.2.0 release (server auto-start,
+Windows support, cross-platform sudo, drag & drop, file associations,
+clipboard, launch-at-login). No gem-side API changes.
+
+## 0.1.1 (2026-07-27)
+
+### Added
+
+- Install generator: `rails generate turbo_desktop:install` scaffolds the initializer.
+- Dev Inspector support:
+  - `config.inspector_enabled` and the `turbo_desktop_inspector_meta_tag` view helper to enable
+    the in-app inspector overlay (dev only).
+  - The gem now serves the inspector's JavaScript **same-origin** at `/turbo-desktop/inspector.js`
+    (and its sub-modules), so the desktop shell can `import()` it without extra setup.
+  - `config.inspector_mount_path` to match a custom engine mount point.
+
+### Changed
+
+- Minimum Ruby version is now 3.3.
+
 ## 0.0.1 (2026-03-22)
 
 - Initial release

data/README.md

@@ -56,6 +56,33 @@ turbo_desktop_arch      # => "aarch64", "x86_64", or nil
     ) %>
 ```
 
+### Desktop-only templates
+
+Requests from the desktop app are marked with a Rails variant, so a whole
+template can be written for it rather than branching inside a shared one:
+
+```
+app/views/orders/show.html.erb           # everyone
+app/views/orders/show.html+desktop.erb   # the desktop app
+```
+
+Layouts work the same way — `app/views/layouts/application.html+desktop.erb`.
+Rails falls back to the plain template wherever no variant exists, so this costs
+nothing until you add one.
+
+The block helpers above are still the right tool for a button or a nav bar. Reach
+for a variant when the whole page differs.
+
+Rename it, or turn it off, in the initializer:
+
+```ruby
+TurboDesktop.configure do |config|
+  config.variant = :desktop   # nil leaves variants alone
+end
+```
+
+It is added to any variants you have already set rather than replacing them.
+
 ### Path Configuration
 
 The gem mounts a path configuration endpoint at `/turbo-desktop/path-configuration.json`:
@@ -76,7 +103,7 @@ end
 
 ## Requirements
 
-- Ruby >= 3.1.0
+- Ruby >= 3.3
 - Rails >= 7.0
 - turbo-rails >= 1.0
 

data/app/controllers/turbo_desktop/inspector_assets_controller.rb

@@ -0,0 +1,44 @@
+module TurboDesktop
+  # Serves the Dev Inspector's JavaScript from the Rails origin so the desktop
+  # shell's `turbo-desktop.js` can `import()` it same-origin.
+  #
+  # The shell points its WebView at your Rails app (server_url), so a relative
+  # `import("./inspector.js")` resolves against the Rails origin — which is why
+  # these assets must be served here, not from the bundled Tauri frontend.
+  #
+  # Only the fixed set of inspector modules is served (strict allow-list, so no
+  # path traversal). Enabled implicitly by mounting the engine; the meta-tag
+  # helper points the shell at these URLs.
+  class InspectorAssetsController < ActionController::Base
+    ASSET_ROOT = TurboDesktop::Engine.root.join("lib/turbo_desktop/inspector_assets").freeze
+
+    # Relative paths (as requested by the browser) → allowed. Anything else 404s.
+    ALLOWED = %w[
+      inspector.js
+      inspector/state.js
+      inspector/panel.js
+      inspector/bridge-tap.js
+      inspector/catalog.js
+    ].freeze
+
+    # GET /turbo-desktop/inspector.js
+    # GET /turbo-desktop/inspector/<module>.js
+    def show
+      rel = requested_asset
+      return head(:not_found) unless ALLOWED.include?(rel)
+
+      path = ASSET_ROOT.join(rel)
+      return head(:not_found) unless File.file?(path)
+
+      response.set_header("Cache-Control", "public, max-age=3600")
+      render body: File.read(path), content_type: "text/javascript"
+    end
+
+    private
+
+    def requested_asset
+      mod = params[:module]
+      mod.blank? ? "inspector.js" : "inspector/#{mod}"
+    end
+  end
+end

data/config/routes.rb

@@ -1,3 +1,7 @@
 TurboDesktop::Engine.routes.draw do
   get "path-configuration", to: "path_configurations#show", defaults: { format: :json }
+
+  # Dev Inspector assets, served same-origin so the desktop shell can import() them.
+  get "inspector.js", to: "inspector_assets#show", format: false
+  get "inspector/*module", to: "inspector_assets#show", format: false
 end

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

@@ -0,0 +1,30 @@
+require "rails/generators/base"
+
+module TurboDesktop
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install Turbo Desktop into your Rails application"
+
+      def copy_initializer
+        template "initializer.rb.tt", "config/initializers/turbo_desktop.rb"
+      end
+
+      def mount_engine
+        route 'mount TurboDesktop::Engine => "/turbo-desktop"'
+      end
+
+      def show_next_steps
+        say ""
+        say "Turbo Desktop installed!", :green
+        say ""
+        say "Next steps:"
+        say "  1. npx turbo-desktop init    # Scaffold the desktop shell"
+        say "  2. rails server              # Start your Rails app"
+        say "  3. npx turbo-desktop dev     # Launch the desktop app"
+        say ""
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# config/initializers/turbo_desktop.rb
+#
+# Configure how the Turbo Desktop native shell presents your Rails routes.
+# This path configuration follows the same pattern as Hotwire Native (turbo-ios/turbo-android).
+#
+# Presentations:
+#   "default"    — Navigate in the current window (standard Turbo Drive behavior)
+#   "modal"      — Open in a modal/sheet window
+#   "new_window" — Open in a separate window
+#   "replace"    — Replace the current page (no back button)
+#   "native"     — Route to a fully native screen (handled by Rust/Tauri)
+#   "none"       — Do nothing (handled by a bridge component)
+
+TurboDesktop.configure do |config|
+  # Dev Inspector — an in-app overlay (Cmd/Ctrl+Shift+D) that surfaces available
+  # bridge components, a live web↔native message log, and the current path-config
+  # presentation. Enable it in development only:
+  config.inspector_enabled = Rails.env.development?
+
+  # Requests from the desktop app are marked with a Rails variant, so you can
+  # write a whole template for it instead of branching inside a shared one:
+  #
+  #   app/views/orders/show.html.erb           # everyone
+  #   app/views/orders/show.html+desktop.erb   # the desktop app
+  #
+  # Layouts work the same way (layouts/application.html+desktop.erb), and Rails
+  # falls back to the plain template wherever no variant exists. Rename it, or
+  # set it to nil to leave variants alone.
+  # config.variant = :desktop
+
+  config.path_configuration = {
+    settings: {
+      screenshots_enabled: false
+    },
+    rules: [
+      # Default: all pages navigate in the current window
+      { patterns: ["/"], properties: { presentation: "default" } },
+
+      # Forms open in a modal window
+      { patterns: ["/new$", "/edit$"], properties: { presentation: "modal" } },
+
+      # Example: settings could be a native screen
+      # { patterns: ["/settings"], properties: { presentation: "native" } },
+
+      # Example: external links open in a new window
+      # { patterns: ["^http"], properties: { presentation: "new_window" } },
+    ]
+  }
+end

data/lib/turbo_desktop/configuration.rb

@@ -1,10 +1,18 @@
 module TurboDesktop
   class Configuration
-    attr_accessor :path_configuration, :user_agent_pattern
+    attr_accessor :path_configuration, :user_agent_pattern, :inspector_enabled,
+                  :inspector_mount_path, :variant
 
     def initialize
       @path_configuration = default_path_configuration
       @user_agent_pattern = /Turbo Desktop/
+      @inspector_enabled = false
+      # Rails variant set on requests from the desktop app, so views can be
+      # written as show.html+desktop.erb. Set to nil to leave variants alone.
+      @variant = :desktop
+      # Where the engine is mounted; the inspector meta tag advertises assets
+      # under this prefix. Override if you mount the engine elsewhere.
+      @inspector_mount_path = "/turbo-desktop"
     end
 
     def path_configuration_json
@@ -19,7 +27,7 @@ module TurboDesktop
           screenshots_enabled: false
         },
         rules: [
-          { patterns: ["/"], properties: { presentation: "default" } }
+          { patterns: [ "/" ], properties: { presentation: "default" } }
         ]
       }
     end

data/lib/turbo_desktop/detection.rb

@@ -11,6 +11,23 @@ module TurboDesktop
 
     included do
       helper_method :turbo_desktop_app?, :turbo_desktop_platform, :turbo_desktop_arch
+
+      before_action :set_turbo_desktop_variant
+    end
+
+    # The variant list a request should end up with, or nil to leave it alone.
+    #
+    # Kept separate from the controller so the decision can be exercised on its
+    # own. Adds to whatever variants are already set rather than replacing them:
+    # an app may well be using variants for something else.
+    def self.variant_for(current:, desktop:, configured:)
+      return nil if configured.blank? || !desktop
+
+      current = Array(current).map(&:to_sym)
+      configured = configured.to_sym
+      return nil if current.include?(configured)
+
+      current + [ configured ]
     end
 
     # Returns true if the request is from a Turbo Desktop app.
@@ -31,6 +48,27 @@ module TurboDesktop
       end
     end
 
+    # Mark desktop requests with a Rails variant, so a whole template can be
+    # written for the desktop app instead of branching inside a shared one:
+    #
+    #   app/views/orders/show.html.erb           # everyone
+    #   app/views/orders/show.html+desktop.erb   # the desktop app
+    #
+    # Layouts pick it up too — layouts/application.html+desktop.erb. Rails falls
+    # back to the plain template wherever no variant exists, so this costs
+    # nothing until you add one.
+    #
+    # Set config.variant to nil to turn it off.
+    def set_turbo_desktop_variant
+      variant = TurboDesktop::Detection.variant_for(
+        current: request.variant,
+        desktop: turbo_desktop_app?,
+        configured: TurboDesktop.configuration.variant
+      )
+
+      request.variant = variant if variant
+    end
+
     # Returns the architecture: "aarch64", "x86_64", or nil.
     def turbo_desktop_arch
       return nil unless turbo_desktop_app?

data/lib/turbo_desktop/inspector_assets/inspector/bridge-tap.js

@@ -0,0 +1,59 @@
+/**
+ * Observes bridge traffic without altering it.
+ *
+ * install() wraps host.sendBridgeMessage so every outbound call is recorded
+ * then forwarded to the original exactly once, with its return/throw preserved.
+ * observeResponse() records inbound bridge-response payloads.
+ *
+ * Recording runs inside its own try/catch so a logging bug can never affect a
+ * real bridge call. No DOM access.
+ */
+export class BridgeTap {
+  constructor(host, { onRecord, now = () => Date.now() } = {}) {
+    this.host = host;
+    this.onRecord = onRecord;
+    this.now = now;
+    this._installed = false;
+    this._original = null;
+  }
+
+  install() {
+    if (this._installed) return;
+    // Store the raw property so uninstall can restore the exact same reference.
+    this._original = this.host.sendBridgeMessage;
+    const original = this._original.bind(this.host);
+    const self = this;
+    this.host.sendBridgeMessage = function (component, event, data = {}) {
+      self._safeRecord({ direction: "out", component, event, data, ts: self.now() });
+      return original(component, event, data); // pass-through, exactly once
+    };
+    this._installed = true;
+  }
+
+  /** Record an inbound bridge-response payload. */
+  observeResponse(payload) {
+    if (!payload) return;
+    this._safeRecord({
+      direction: "in",
+      component: payload.component,
+      event: payload.event || "response",
+      data: payload.data !== undefined ? payload.data : payload,
+      ts: this.now(),
+    });
+  }
+
+  uninstall() {
+    if (this._installed && this._original) {
+      this.host.sendBridgeMessage = this._original;
+      this._installed = false;
+    }
+  }
+
+  _safeRecord(record) {
+    try {
+      if (this.onRecord) this.onRecord(record);
+    } catch (_e) {
+      /* recording must never break the host */
+    }
+  }
+}

data/lib/turbo_desktop/inspector_assets/inspector/catalog.js

@@ -0,0 +1,75 @@
+/**
+ * Static catalog of built-in bridge components.
+ * Single source of truth for the Inspector's "Available" list and snippets.
+ * Each entry: { description, erb, stimulus }.
+ */
+export const CATALOG = {
+  "notification": {
+    description: "Show native OS notifications.",
+    erb: `<button data-controller="notification"\n        data-action="click->notification#notify"\n        data-body="Saved!">Notify</button>`,
+    stimulus: `import { Controller } from "@hotwired/stimulus"\nexport default class extends TurboDesktop.stimulusBridge(Controller, "notification") {\n  notify(e) { this.sendBridge("connect", { title: "My App", body: e.target.dataset.body }) }\n}`,
+  },
+  "menu-item": {
+    description: "Register an item in the native menu bar.",
+    erb: `<%= tag.button "Export PDF",\n      **turbo_desktop_bridge("menu-item", title: "Export PDF", shortcut: "Cmd+E") %>`,
+    stimulus: `import { Controller } from "@hotwired/stimulus"\nexport default class extends TurboDesktop.stimulusBridge(Controller, "menu-item") {\n  connect() { super.connect(); this.sendBridge("register", { title: "Export PDF", shortcut: "Cmd+E" }) }\n}`,
+  },
+  "file-picker": {
+    description: "Open a native file open/save dialog.",
+    erb: `<button data-controller="file-picker"\n        data-action="click->file-picker#open">Choose file…</button>`,
+    stimulus: `import { Controller } from "@hotwired/stimulus"\nexport default class extends TurboDesktop.stimulusBridge(Controller, "file-picker") {\n  open() { this.sendBridge("open", { multiple: false }) }\n  receiveBridge(msg) { console.log("picked", msg.data) }\n}`,
+  },
+  "badge": {
+    description: "Set the dock / taskbar badge count.",
+    erb: `<span data-controller="badge" data-badge-count-value="3"></span>`,
+    stimulus: `import { Controller } from "@hotwired/stimulus"\nexport default class extends TurboDesktop.stimulusBridge(Controller, "badge") {\n  static values = { count: Number }\n  connect() { super.connect(); this.sendBridge("set", { count: this.countValue }) }\n}`,
+  },
+  "shortcut": {
+    description: "Register a global keyboard shortcut.",
+    erb: `<div data-controller="shortcut" data-shortcut-keys-value="CmdOrCtrl+K"></div>`,
+    stimulus: `import { Controller } from "@hotwired/stimulus"\nexport default class extends TurboDesktop.stimulusBridge(Controller, "shortcut") {\n  static values = { keys: String }\n  connect() { super.connect(); this.sendBridge("register", { keys: this.keysValue }) }\n  receiveBridge() { /* fired when the shortcut is pressed */ }\n}`,
+  },
+  "shell": {
+    description: "Spawn and manage native shell processes.",
+    erb: `<button data-controller="shell" data-action="click->shell#run">Run</button>`,
+    stimulus: `import { Controller } from "@hotwired/stimulus"\nexport default class extends TurboDesktop.stimulusBridge(Controller, "shell") {\n  run() { TurboDesktop.shell.spawn("job-1", "echo", ["hello"]) }\n}`,
+  },
+  "filesystem": {
+    description: "Read and write files through the native filesystem bridge.",
+    erb: `<button data-controller="fs" data-action="click->fs#read">Read file</button>`,
+    stimulus: `import { Controller } from "@hotwired/stimulus"\nexport default class extends TurboDesktop.stimulusBridge(Controller, "filesystem") {\n  read() { this.sendBridge("read", { path: "~/notes.txt" }) }\n  receiveBridge(msg) { console.log(msg.data) }\n}`,
+  },
+  "sudo": {
+    description: "Run a privileged command via the native elevation prompt.",
+    erb: `<button data-controller="sudo" data-action="click->sudo#elevate">Install</button>`,
+    stimulus: `import { Controller } from "@hotwired/stimulus"\nexport default class extends TurboDesktop.stimulusBridge(Controller, "sudo") {\n  elevate() { this.sendBridge("execute", { command: "brew install foo" }) }\n}`,
+  },
+  "tray": {
+    description: "Add items to the system tray / menu-bar icon.",
+    erb: `<div data-controller="tray" data-tray-title-value="My App"></div>`,
+    stimulus: `import { Controller } from "@hotwired/stimulus"\nexport default class extends TurboDesktop.stimulusBridge(Controller, "tray") {\n  static values = { title: String }\n  connect() { super.connect(); this.sendBridge("set", { tooltip: this.titleValue }) }\n}`,
+  },
+  "deep-link": {
+    description: "Handle custom-scheme deep links opened from outside the app.",
+    erb: `<div data-controller="deep-link"></div>`,
+    stimulus: `import { Controller } from "@hotwired/stimulus"\nexport default class extends TurboDesktop.stimulusBridge(Controller, "deep-link") {\n  receiveBridge(msg) { Turbo.visit(msg.data.path) }\n}`,
+  },
+  "updater": {
+    description: "Check for and apply native app updates.",
+    erb: `<button data-controller="updater" data-action="click->updater#check">Check for updates</button>`,
+    stimulus: `import { Controller } from "@hotwired/stimulus"\nexport default class extends TurboDesktop.stimulusBridge(Controller, "updater") {\n  check() { this.sendBridge("check", {}) }\n  receiveBridge(msg) { console.log("update status", msg.data) }\n}`,
+  },
+};
+
+for (const entry of Object.values(CATALOG)) Object.freeze(entry);
+Object.freeze(CATALOG);
+
+/** Names of every catalogued component. */
+export function listComponents() {
+  return Object.keys(CATALOG);
+}
+
+/** Look up one component's metadata, or null if unknown. */
+export function getComponent(name) {
+  return Object.prototype.hasOwnProperty.call(CATALOG, name) ? CATALOG[name] : null;
+}

data/lib/turbo_desktop/inspector_assets/inspector/panel.js

@@ -0,0 +1,148 @@
+import { listComponents, getComponent } from "./catalog.js";
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function escapeAttr(value) {
+  return escapeHtml(value).replace(/"/g, "&quot;");
+}
+
+/**
+ * Shadow-DOM overlay that renders an InspectorState.
+ * Subscribes to state changes; never mutates state. No Tauri access.
+ */
+export class InspectorPanel {
+  constructor(state, { document }) {
+    this.state = state;
+    this.document = document;
+    this.visible = false;
+    this.activeTab = "components";
+    this.filter = "";
+    this.hostEl = null;
+    this.root = null; // shadow root
+    this._unsub = null;
+  }
+
+  mount(parent) {
+    const host = this.document.createElement("div");
+    host.setAttribute("data-turbo-desktop-inspector", "");
+    host.style.cssText = "position:fixed;right:0;bottom:0;z-index:2147483647;";
+    this.root = host.attachShadow ? host.attachShadow({ mode: "open" }) : host;
+    this.hostEl = host;
+    parent.appendChild(host);
+    this._unsub = this.state.subscribe(() => this.render());
+    this.render();
+    this._applyVisibility();
+    return this;
+  }
+
+  unmount() {
+    if (this._unsub) this._unsub();
+    if (this.hostEl && this.hostEl.parentNode) this.hostEl.parentNode.removeChild(this.hostEl);
+  }
+
+  show() { this.visible = true; this._applyVisibility(); }
+  hide() { this.visible = false; this._applyVisibility(); }
+  toggle() { this.visible = !this.visible; this._applyVisibility(); }
+
+  selectTab(tab) { this.activeTab = tab; this.render(); }
+  setFilter(text) { this.filter = text || ""; this.render(); }
+
+  _applyVisibility() {
+    if (this.hostEl) this.hostEl.style.display = this.visible ? "block" : "none";
+  }
+
+  render() {
+    if (!this.root) return;
+    try {
+      this.root.innerHTML = this._html();
+      this._wire();
+    } catch (_e) {
+      this.root.innerHTML = "<div>&lt;unrenderable&gt;</div>";
+    }
+  }
+
+  _wire() {
+    const q = (sel) => this.root.querySelectorAll(sel);
+    q("[data-tab]").forEach((btn) => {
+      btn.addEventListener("click", () => this.selectTab(btn.dataset.tab));
+    });
+    const input = this.root.querySelector("[data-filter]");
+    if (input) input.addEventListener("input", (e) => this.setFilter(e.target.value));
+  }
+
+  _html() {
+    return `
+      <style>
+        :host { all: initial; }
+        .wrap { font: 12px/1.4 monospace; width: 420px; height: 320px; background:#111; color:#eee; border:1px solid #333; display:flex; flex-direction:column; }
+        .tabs { display:flex; }
+        .tabs button { flex:1; background:#222; color:#ccc; border:0; padding:6px; cursor:pointer; }
+        .tabs button[aria-selected="true"] { background:#0a84ff; color:#fff; }
+        .body { flex:1; overflow:auto; padding:8px; }
+        .row { padding:2px 0; border-bottom:1px solid #222; }
+        .muted { color:#888; }
+        input { width:100%; box-sizing:border-box; margin-bottom:6px; background:#000; color:#eee; border:1px solid #333; }
+      </style>
+      <div class="wrap">
+        <div class="tabs">
+          ${["components", "messages", "navigation", "shell"].map((t) =>
+            `<button data-tab="${t}" aria-selected="${this.activeTab === t}">${t}</button>`).join("")}
+        </div>
+        <div class="body">
+          ${this._panelHtml()}
+        </div>
+      </div>`;
+  }
+
+  _panelHtml() {
+    switch (this.activeTab) {
+      case "messages": return this._messagesHtml();
+      case "navigation": return this._navHtml();
+      case "shell": return this._shellHtml();
+      default: return this._componentsHtml();
+    }
+  }
+
+  _componentsHtml() {
+    const active = new Map(this.state.components().map((c) => [c.name, c]));
+    const rows = listComponents().map((name) => {
+      const c = getComponent(name);
+      const seen = active.get(name);
+      const tag = seen ? `<span>×${escapeHtml(seen.count)} (${escapeHtml(seen.lastEvent)})</span>` : `<span class="muted">available</span>`;
+      return `<div class="row"><strong>${escapeHtml(name)}</strong> ${tag}<br><span class="muted">${escapeHtml(c.description)}</span></div>`;
+    }).join("");
+    return `<div data-panel="components">${rows}</div>`;
+  }
+
+  _messagesHtml() {
+    const f = this.filter.toLowerCase();
+    const rows = this.state.messages
+      .filter((m) => !f || (m.component || "").toLowerCase().includes(f))
+      .map((m) => {
+        const arrow = m.direction === "out" ? "↑" : "↓";
+        return `<div class="row" data-message-row>${arrow} <strong>${escapeHtml(m.component)}</strong> ${escapeHtml(m.event)} <span class="muted">${escapeHtml(JSON.stringify(m.data))}</span></div>`;
+      }).join("");
+    return `<div data-panel="messages"><input data-filter placeholder="filter by component" value="${escapeAttr(this.filter)}">${rows}</div>`;
+  }
+
+  _navHtml() {
+    const n = this.state.nav;
+    return `<div data-panel="navigation"><div class="row">URL: ${escapeHtml(n.url || "—")}</div><div class="row">Presentation: <strong>${escapeHtml(n.presentation || "default")}</strong></div></div>`;
+  }
+
+  _shellHtml() {
+    const s = this.state.shell;
+    return `<div data-panel="shell">
+      <div class="row">Platform: ${escapeHtml(s.platform || "—")}</div>
+      <div class="row">Arch: ${escapeHtml(s.arch || "—")}</div>
+      <div class="row">Version: ${escapeHtml(s.version || "—")}</div>
+      <div class="row">Server: ${escapeHtml(s.serverUrl || "—")}</div>
+      <div class="row">Updater: ${escapeHtml(s.updater || "—")}</div>
+    </div>`;
+  }
+}

data/lib/turbo_desktop/inspector_assets/inspector/state.js

@@ -0,0 +1,61 @@
+/**
+ * In-memory model for the Dev Inspector.
+ * Holds a bounded ring buffer of message records plus a derived component
+ * summary and nav/shell facts. Emits "change" to subscribers. No DOM.
+ */
+export class InspectorState {
+  constructor({ capacity = 200 } = {}) {
+    this.capacity = capacity;
+    this.messages = [];
+    this._components = new Map(); // name -> { count, lastEvent }
+    this.nav = { url: null, presentation: null };
+    this.shell = { platform: null, arch: null, version: null, serverUrl: null, updater: null };
+    this._listeners = new Set();
+  }
+
+  /** Append a record { direction, component, event, data, ts }. */
+  record(record) {
+    this.messages.push(record);
+    if (this.messages.length > this.capacity) this.messages.shift();
+
+    const prev = this._components.get(record.component) || { count: 0, lastEvent: null };
+    prev.count += 1;
+    prev.lastEvent = record.event;
+    this._components.set(record.component, prev);
+
+    this._emit();
+  }
+
+  /** Derived component summary as an array. */
+  components() {
+    return [...this._components.entries()].map(([name, v]) => ({ name, count: v.count, lastEvent: v.lastEvent }));
+  }
+
+  setNav(nav) {
+    this.nav = { ...this.nav, ...nav };
+    this._emit();
+  }
+
+  setShell(shell) {
+    this.shell = { ...this.shell, ...shell };
+    this._emit();
+  }
+
+  clear() {
+    this.messages = [];
+    this._components.clear();
+    this._emit();
+  }
+
+  /** Subscribe to changes; returns an unsubscribe function. */
+  subscribe(fn) {
+    this._listeners.add(fn);
+    return () => this._listeners.delete(fn);
+  }
+
+  _emit() {
+    for (const fn of this._listeners) {
+      try { fn(this); } catch (_e) { /* a bad subscriber must not break others */ }
+    }
+  }
+}

data/lib/turbo_desktop/inspector_assets/inspector.js

@@ -0,0 +1,57 @@
+/**
+ * Dev Inspector entry point.
+ *
+ * startInspector(host, env) wires the inspector units onto a TurboDesktop-like
+ * host: it installs a BridgeTap on the host's sendBridgeMessage, subscribes to
+ * inbound bridge-response events, seeds shell facts, mounts the Shadow-DOM
+ * panel, and binds the toggle hotkey (Cmd/Ctrl+Shift+D).
+ *
+ * This module is loaded lazily by turbo-desktop.js only when the inspector gate
+ * passes, so it ships no code to production builds.
+ */
+import { BridgeTap } from "./inspector/bridge-tap.js";
+import { InspectorState } from "./inspector/state.js";
+import { InspectorPanel } from "./inspector/panel.js";
+
+export function startInspector(host, { doc = document, win = window } = {}) {
+  const state = new InspectorState();
+
+  const now = (win.Date && typeof win.Date.now === "function") ? () => win.Date.now() : () => 0;
+  const tap = new BridgeTap(host, { onRecord: (r) => state.record(r), now });
+  tap.install();
+
+  const internals = win.__TAURI_INTERNALS__;
+  if (internals && internals.event && typeof internals.event.listen === "function") {
+    internals.event.listen("bridge-response", (e) => tap.observeResponse(e && e.payload));
+  }
+
+  state.setShell({ platform: host.platform, version: host.version });
+  if (typeof host.getWindowInfo === "function") {
+    host.getWindowInfo().then((info) => { if (info) state.setShell(info); }).catch(() => {});
+  }
+
+  if (typeof host.proposeVisit === "function") {
+    const originalProposeVisit = host.proposeVisit.bind(host);
+    host.proposeVisit = async function (url, action) {
+      const result = await originalProposeVisit(url, action);
+      try {
+        state.setNav({ url, presentation: result && result.presentation ? result.presentation : "default" });
+      } catch (_e) { /* nav recording must never break navigation */ }
+      return result;
+    };
+  }
+
+  const panel = new InspectorPanel(state, { document: doc });
+  panel.mount(doc.body);
+
+  win.addEventListener("keydown", (e) => {
+    if ((e.metaKey || e.ctrlKey) && e.shiftKey && (e.key === "D" || e.key === "d")) {
+      e.preventDefault();
+      panel.toggle();
+    }
+  });
+
+  return { state, tap, panel };
+}
+
+export default startInspector;

data/lib/turbo_desktop/version.rb

@@ -1,3 +1,3 @@
 module TurboDesktop
-  VERSION = "0.0.1"
+  VERSION = "0.2.2"
 end

data/lib/turbo_desktop/view_helpers.rb

@@ -26,12 +26,20 @@ module TurboDesktop
       end
     end
 
+    # Attribute name fragments we are willing to build a data-* attribute from.
+    # Values are escaped by the tag helpers, but names are interpolated, so they
+    # are restricted rather than escaped.
+    BRIDGE_NAME_PATTERN = /\A[a-zA-Z0-9_-]+\z/
+
     # Renders a bridge component data attribute.
     #
     #   <%= tag.button "Export", **turbo_desktop_bridge("menu-item", title: "Export PDF", shortcut: "Cmd+E") %>
     def turbo_desktop_bridge(component, **options)
-      attrs = { "data-turbo-desktop-bridge" => component }
+      validate_bridge_name!(component, "component")
+
+      attrs = { "data-turbo-desktop-bridge" => component.to_s }
       options.each do |key, value|
+        validate_bridge_name!(key, "option name")
         attrs["data-turbo-desktop-bridge-#{key}"] = value.to_s
       end
       attrs
@@ -46,5 +54,42 @@ module TurboDesktop
     def turbo_web_only(&block)
       capture(&block) unless turbo_desktop_app?
     end
+
+    # Returns true when the Dev Inspector is enabled in configuration.
+    def turbo_desktop_inspector?
+      TurboDesktop.configuration.inspector_enabled
+    end
+
+    # Emits the <meta> tag that enables the Dev Inspector in the browser, or nil
+    # when the inspector is disabled. Place in your layout <head>; it is a no-op
+    # in production unless you explicitly enable the inspector there.
+    #
+    # The tag also carries the same-origin URL of the inspector entry module
+    # (served by this engine) so the desktop shell's turbo-desktop.js can
+    # import() it instead of guessing a relative path.
+    #
+    #   <%= turbo_desktop_inspector_meta_tag %>
+    def turbo_desktop_inspector_meta_tag
+      return nil unless turbo_desktop_inspector?
+
+      tag.meta(name: "turbo-desktop-inspector", content: "enabled",
+               data: { inspector_url: turbo_desktop_inspector_url })
+    end
+
+    # Same-origin URL of the inspector entry module, under the engine's mount
+    # path (configurable via config.inspector_mount_path).
+    def turbo_desktop_inspector_url
+      "#{TurboDesktop.configuration.inspector_mount_path.chomp("/")}/inspector.js"
+    end
+
+    private
+
+    def validate_bridge_name!(name, label)
+      return if name.to_s.match?(BRIDGE_NAME_PATTERN)
+
+      raise ArgumentError,
+            "turbo_desktop_bridge #{label} #{name.inspect} may only contain " \
+            "letters, numbers, hyphens and underscores"
+    end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: turbo_desktop-rails
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.2.2
 platform: ruby
 authors:
-- RaiderHQ
+- aguspe
 bindir: bin
 cert_chain: []
-date: 2026-03-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -48,13 +48,21 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- app/controllers/turbo_desktop/inspector_assets_controller.rb
 - app/controllers/turbo_desktop/path_configurations_controller.rb
 - config/routes.rb
+- lib/generators/turbo_desktop/install/install_generator.rb
+- lib/generators/turbo_desktop/install/templates/initializer.rb.tt
 - lib/turbo_desktop-rails.rb
 - lib/turbo_desktop.rb
 - lib/turbo_desktop/configuration.rb
 - lib/turbo_desktop/detection.rb
 - lib/turbo_desktop/engine.rb
+- lib/turbo_desktop/inspector_assets/inspector.js
+- lib/turbo_desktop/inspector_assets/inspector/bridge-tap.js
+- lib/turbo_desktop/inspector_assets/inspector/catalog.js
+- lib/turbo_desktop/inspector_assets/inspector/panel.js
+- lib/turbo_desktop/inspector_assets/inspector/state.js
 - lib/turbo_desktop/version.rb
 - lib/turbo_desktop/view_helpers.rb
 homepage: https://github.com/aguspe/turbo_desktop
@@ -72,14 +80,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Turbo Native for Desktop — Rails integration
 test_files: []