voice_control 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 21230246c534702dc5e7304fce70009b50a1db239ed73b78e4d6eaaf41aa8fc4
+  data.tar.gz: 86c1e751e45bb9f59b286be138896edb4a95c84f61b6dd36fce2b2d9ac83962c
+SHA512:
+  metadata.gz: f2d7e8be4cb052ed7b96874e80b71c50ba8c20bdcee9b2b110699dc999c27d85adf7cc726c8456c2a0fb7b81dba31ed72c2046dad3b3e9908607a050537ebed9
+  data.tar.gz: 0e13f05400026ea9a8a99742fe0981c49d76259db2d55b1fcbcf305367965006f11b1b7196c40051539b3e140368a00ba679b3cc5c2ed523a371922ada6e619a

data/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- Allow installation on Ruby 3.2+; CI runs on Ruby 4.0.
+- Stay within Jev's 255-choice limit: skip the longest commands beyond 254 and log a warning instead of failing the request.
+- Add `speech_language` to configure the browser speech recognition language.
+- Rename the gem and repository to `voice_control`, with `VoiceControl` Ruby/JavaScript APIs, `voice_control:install`, and the `voice-control-widget` component.
+- Add `pages:` command scopes for exact paths and regexes, with navigation-aware help and a custom-router `VoiceControl.refresh()` hook.
+- Add a page-wide dynamic-action opt-out meta tag; enforce ignored forms for externally associated controls.
+- Reject delayed command execution after navigation and links whose navigation behavior changed while pending.
+- Document notifications without reload and add a scoped workspace-summary demo command.
+- Bound widget requests with configurable `request_timeout`; report uncertain execution without retrying actions.
+- Add optional `notify:` completion notices to result helpers, preserved briefly across navigation and reloads.
+- Restore continuous listening after command-triggered reloads and browser back/forward cache restoration.
+- Run real Turbo navigation, reload, timeout, and widget regressions in Chromium, Firefox, and WebKit CI.
+- Add Ruby and JavaScript coverage reports, behavioral tests, and CI coverage gates above 95%.
+- Keep both “Logout” and “Log out” out of suggested commands.
+
+- Add `VoiceControl::Result.reload` to refresh the current page after successful commands.
+
+- Deduplicate equivalent links in browser actions, help, and command choices.
+
+- Constrain JSON to 2.x for Rails 8.0/8.1 compatibility in fresh installs and CI.
+
+- Add a small launcher option, explain initializer settings, and expand the README with command examples.
+
+- Discover only controls with readable text or labels, and show command descriptions alongside Jev probability IDs.
+
+- Prevent canceled interpretations and incomplete speech fragments from executing; restore listeners after widget reinsertion.
+- Reject changed form ownership/submit behavior and oversized signed state before issuing unusable tickets.
+- Add a development-only execution cache fallback, dependency-free browser regression fixtures, and Rails 8.0/8.1 CI coverage.
+- Reorganize the README and ship guides for commands, browser actions, configuration, deployment, and privacy.
+
+- Resolve exact browser click labels before Jev, and show Jev's action answer, probabilities, and readable candidates in debug mode.
+
+- Add “submit” for the active form, with native validation, submitter semantics, and stale-form protection.
+
+- Add browser back/forward commands and separate interpretation/execution progress messages.
+
+- Add keyboard help navigation, configurable left/right positioning, and a hold-to-talk shortcut.
+- Support native date/time entry and contextual labels for generic table-row actions.
+
+- Highlight action targets, clear named/selected fields with Undo, and scroll the page or discovered headings.
+- Add typo-tolerant help search and a Copy details button for the latest debug report.
+
+- Discover checkbox check/uncheck and radio choose actions, including spoken aliases and checkbox undo.
+- Add opt-in command diagnostics, a green/cream widget, and a Google-inspired demo design.
+
+- Add a Rails engine with configurable parent controller and authorization.
+- Define grouped Ruby commands with typed arguments, extractors, defaults and validation.
+- Route commands through Jev and collect missing arguments with signed continuations.
+- Add automatic execution with CSRF, session binding and cache-based replay protection.
+- Add a Shadow DOM voice/typing widget with Turbo support, browser events and help.
+- Include an install generator and a credential-free dummy app.

data/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+Use Ruby 3.2+ and Rails 8.x. From this gem's directory:
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec rubocop --ignore-parent-exclusion
+npm ci --ignore-scripts
+npm run test:coverage
+npm run lint
+bin/demo
+```
+
+Minitest uses an isolated SQLite dummy app and stubs Jev HTTP calls. It does not require a provider key or make paid calls. Add a failing regression before fixing behavior. Keep application-specific services and policies outside the gem. Runtime JavaScript is shipped directly; no Node build is required.
+
+## Coverage
+
+Run `bundle exec rake test` for Ruby coverage and `npm run test:coverage` for JavaScript coverage (Node 24.15+ or 26+; CI uses Node 24). Both commands fail if line or branch coverage falls below **95.01%**. JavaScript also enforces 95.01% statements and functions.
+
+Open `coverage/ruby/index.html` and `coverage/javascript/index.html` for uncovered lines and branches. Machine-readable reports are at `coverage/ruby/coverage.json` and `coverage/javascript/coverage-summary.json`; CI uploads the reports even when a test or threshold fails.
+
+Ruby coverage includes all executable Ruby under `lib`, `app`, and `config`, including generator code and its initializer template. JavaScript coverage includes all `assets/**/*.js`. Tests, the dummy app, examples, dependencies, and reports are outside those production scopes; unloaded production files still count. Keep the scopes intact and add behavioral tests instead of coverage-ignore comments. Run the full suite for a representative report; individual Ruby test files are still subject to the aggregate coverage gate.
+
+The JavaScript suite uses Vitest, jsdom, and V8. It exercises the real widget and DOM events with stubbed HTTP/speech and simulated layout, animation, and scrolling APIs. These percentages do not prove microphone recognition or real-browser rendering: keep running the browser checks below for native form submission, navigation, and layout behavior.
+
+## Browser checks
+
+Run the Playwright suite in Chromium, Firefox, and WebKit:
+
+```sh
+npx playwright install chromium firefox webkit
+npm run test:browser
+```
+
+The suite starts its own local fixture server and runs in CI. It covers native form submission, cancellation, stale forms, reconnection, debug rendering, request timeouts, optional completion notices, and consecutive speech commands across real Turbo navigation and full reloads. Speech events and provider responses are simulated; no Jev key or microphone is required. Test real recognition and permissions separately.
+
+Open `playwright-report/index.html` for results; failing tests retain traces under `test-results/`. CI uploads both directories. To inspect the dependency-free regression fixture manually, run `python3 -m http.server 4205 --bind 127.0.0.1` and open [the fixture](http://127.0.0.1:4205/test/browser/index.html).
+
+JavaScript lint configuration is provided in `eslint.config.mjs`; use ESLint 9 or 10 and Prettier 3 when editing assets. Test Turbo navigation in the dummy app and custom router behavior in your integration. Run against real Redis when changing replay protection; separate processes must claim a ticket only once.
+
+CI tests Rails 8.0 and 8.1. To select a version locally, use a separate checkout without its ignored lockfile and run `RAILS_VERSION='~> 8.0.0' bundle install`, then `RAILS_VERSION='~> 8.0.0' bundle exec rake test`. The gemspec constrains JSON below 3 for both supported Rails versions. Use fresh dependency resolution when changing dependencies; an existing local lockfile can hide CI failures.
+
+## Packaging
+
+```sh
+gem build voice_control.gemspec
+gem install --local voice_control-0.1.0.gem
+gem contents voice_control --show-install-dir # After installing your local build
+```
+
+Inspect the archive: runtime files, examples, and documentation should be present; demo databases, logs, credentials, test output, and development dependencies must not ship. Install the built gem in a disposable Rails application, run `voice_control:install`, and verify authorization, CSRF, rendering, and a complete command. Source-path tests alone do not verify packaging.
+
+Document public configuration and behavior changes, update CHANGELOG.md, and include reproduction steps for browser issues. Do not add framework-wide abstractions for a single command. A bug report should contain Ruby/Rails/browser versions, the minimal vocabulary, expected/actual behavior, and redacted command diagnostics.
+
+The repository is currently private and the gem is not published to RubyGems. A private vulnerability-reporting channel must be established before public release.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Kasyanchuk
+
+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

@@ -0,0 +1,343 @@
+# voice_control
+
+[![Watch the voice_control demo on YouTube](docs/demo.png)](https://youtu.be/Zz1Ibx8R7WI)
+
+[▶ Watch the demo on YouTube](https://youtu.be/Zz1Ibx8R7WI)
+
+**You say it. Your app does it.**
+
+Voice and typed commands for Rails. Define actions in Ruby, keep your authorization, and give users a shortcut to the work they already do.
+
+```ruby
+VoiceControl.configure do |config|
+  config.command :open_users,
+    description: "Open users", aliases: ["show people"] do
+    execute { |_args, _context| VoiceControl::Result.navigate(main_app.users_path) }
+  end
+end
+```
+
+Say **“show people.”** Your app opens its users page.
+
+| You provide | voice_control handles |
+| --- | --- |
+| Ruby actions and permissions | Command matching, typed arguments, and follow-up questions |
+| Existing buttons and forms | Optional page discovery: click, fill, select, check, and submit |
+| Your Rails app | A Shadow DOM widget, searchable help, Turbo support, and JavaScript hooks |
+
+**No runtime database, migrations, Node build, or CSS framework.** Rails 8.x, Ruby 3.2+, MIT. A short-lived execution cache is required; production uses a shared atomic cache.
+
+The gem requires JSON 2.x because the supported Rails 8.0/8.1 versions use JSON APIs changed in JSON 3. Bundler applies this constraint automatically.
+
+**Status:** unreleased. Installation currently uses this source checkout or a locally built gem. Commands execute immediately once their arguments are complete; no confirmation dialog is added. Start with navigation and actions you can safely expose to the authorized user.
+
+[Quick start](#quick-start) · [Configuration](#configuration) · [Demo](#try-it-locally) · [Ruby DSL](docs/commands.md) · [Browser actions](docs/browser-actions.md) · [Deployment](docs/deployment.md)
+
+## Quick start
+
+Add it to your application's Gemfile:
+
+```ruby
+# Gemfile
+gem "voice_control"
+```
+
+The gem is not published to RubyGems yet. Until release, [build and install a local copy](CONTRIBUTING.md#packaging), then use `bundle install --local` for the first command below.
+
+```sh
+bundle install
+bin/rails generate voice_control:install
+```
+
+The generator creates an initializer and mounts `/voice_control`. Edit the generated initializer:
+
+```ruby
+VoiceControl.configure do |config|
+  config.api_key = ENV.fetch("JEV_API_KEY")
+  config.authorize = -> { current_user&.admin? } # Use your app's access check.
+  config.browser_actions = true
+  config.launcher_size = :small # Optional: smaller floating microphone button.
+
+  config.group "Navigation" do
+    config.command :home, description: "Open home", aliases: ["go home"] do
+      execute { |_args, _context| VoiceControl::Result.navigate(main_app.root_path) }
+    end
+  end
+end
+```
+
+Replace the initializer's example block rather than appending another `home` command. Supply your [Jev](https://docs.typesafe.ai/introduction/quickstart) key in the server environment and restart Rails. The key never reaches the browser.
+
+Add the widget before `</body>` in your layout. Keep the existing CSRF tags in `<head>`:
+
+```erb
+<!-- In <head>, if your layout does not already include it: -->
+<%= csrf_meta_tags %>
+
+<!-- Before </body>: -->
+<%= voice_control_widget %>
+```
+
+Sign in with an authorized account. Click the microphone or press **⌘⇧U / Ctrl+Shift+U**, then type **“go home.”** Open **?** to see available commands. Help selections work without a Jev key; free-form interpretation needs one. Authorization defaults to denying access until configured.
+
+Assets are served by the engine. No importmap, bundler, or asset-manifest changes are needed. Standard cookie sessions and CSRF protection are required; API-only apps need those Rails facilities enabled. In development, a disabled `NullStore` gets a local MemoryStore fallback. [Configure a shared cache before production.](docs/deployment.md)
+
+## Try it locally
+
+Clone the repository (access is required while it is private), then start the demo:
+
+```sh
+git clone git@github.com:igorkasyanchuk/voice_control.git
+cd voice_control
+bundle install
+bin/demo
+```
+
+Open [127.0.0.1:4100](http://127.0.0.1:4100). No credentials are needed: the demo uses deterministic local matching without a key, and Jev when `JEV_API_KEY` is present.
+
+| Say or type | Where |
+| --- | --- |
+| `open users` | Any demo page |
+| `give user 42 100 tokens` | Any demo page; updates the user's balance |
+| `change my plan` | Any demo page; asks which plan |
+| `fill workspace name with Studio North` | Settings |
+| `submit` | After selecting a Settings field |
+| `summarize workspace` | Settings only; shows details and a notice without reloading |
+| `undo that` | After an unsaved field edit |
+
+The standalone demo includes user CRUD, settings, account plans, and 24 seeded users. Its SQLite database persists changes between runs; SQLite is a development dependency, not a gem runtime requirement. [Demo guide →](docs/demo.md)
+
+## More command examples
+
+Add these inside your `VoiceControl.configure` block. Route examples assume your application has `users_path` and `reports_path`; replace them with your own routes.
+
+**Search with a text argument:** “find users” asks for a search term; “find users named Alex” opens the results directly.
+
+```ruby
+config.command :find_users, description: "Find users by name",
+  aliases: ["search users", "find users"], examples: ["find users named Alex"] do
+  argument :query, :string, prompt: "Who are you looking for?",
+    extract: ->(text, _context) { text[/\bnamed\s+(.+)\z/i, 1] }
+
+  execute do |args, _context|
+    VoiceControl::Result.navigate(main_app.users_path(q: args[:query]))
+  end
+end
+```
+
+**Choose from a fixed list:** “show weekly report” opens it; “show report” asks which period.
+
+```ruby
+config.group "Reports" do
+  config.command :show_report, description: "Open a daily, weekly or monthly report",
+    aliases: ["show report"], examples: ["show weekly report"] do
+    argument :period, :enum, values: %w[daily weekly monthly],
+      prompt: "Daily, weekly or monthly?",
+      extract: ->(text, _context) { text[/\b(daily|weekly|monthly)\b/i, 1] }
+
+    execute do |args, _context|
+      VoiceControl::Result.navigate(main_app.reports_path(period: args[:period]))
+    end
+  end
+end
+```
+
+**Return a message without navigating:** “what is my account ID” displays the signed-in account's ID. This example assumes your controller provides `current_user`.
+
+```ruby
+config.command :account_id, description: "Show my account ID",
+  aliases: ["what is my account ID"] do
+  execute do |_args, _context|
+    VoiceControl::Result.message("Your account ID is #{current_user.id}.")
+  end
+end
+```
+
+**Trigger your JavaScript:** “show shortcuts” dispatches an event that your app can use to open a dialog.
+
+```ruby
+config.command :show_shortcuts, description: "Show keyboard shortcuts",
+  aliases: ["show shortcuts"] do
+  execute { |_args, _context| VoiceControl::Result.event("app:show-shortcuts") }
+end
+```
+
+```javascript
+// Add a <dialog id="keyboard-shortcuts"> to your app, then register this once.
+window.addEventListener("app:show-shortcuts", () => {
+  document.querySelector("#keyboard-shortcuts")?.showModal();
+});
+```
+
+## Use your existing business logic
+
+Commands are Ruby callbacks, not generated code. Add record-level permission checks for mutations:
+
+```ruby
+config.command :archive_project,
+  description: "Archive a project",
+  visible: -> { current_user.admin? },
+  authorize: ->(args, _context) { policy(Project.find(args[:id])).archive? } do
+  argument :id, :integer,
+    extract: ->(text, _context) { text[/\bproject (\d+)\b/i, 1] },
+    validate: ->(id) { id.positive? },
+    prompt: "Which project ID?"
+
+  execute do |args, _context|
+    Project.find(args[:id]).archive! # Your existing operation.
+    VoiceControl::Result.message("Project archived.")
+  end
+end
+```
+
+This example assumes your app provides `Project#archive!` and a Pundit-style `policy`. Callbacks run in the request controller; `main_app`, `current_user`, and your application helpers are available there. Arguments use symbol keys, context uses string keys. Your action owns transactions, tenant scoping, and domain idempotency.
+
+Return `VoiceControl::Result.reload` after a successful mutation when the whole page should reflect the change, such as an account plan update. It reloads the current URL, including its query and fragment. Use `Result.message` for feedback without reloading, or `Result.event` for a targeted JavaScript update.
+
+Add `notify:` to any result helper for an optional five-second completion notice. No reload is required:
+
+```ruby
+VoiceControl::Result.message("Preferences saved.", notify: "Saved successfully.")
+VoiceControl::Result.event("account:updated", { plan: "premium" }, notify: "Plan updated.")
+```
+
+Both keep the current page in place. Use `VoiceControl::Result.reload(notify: "Plan updated.")` when you also want a reload; the notice carries across it. Results show a separate notice only when you opt in. [Result options →](docs/commands.md#results)
+
+## Limit commands to relevant pages
+
+Use `pages:` to offer a command only on matching paths:
+
+```ruby
+config.command :show_user_help, description: "Show user management help",
+  pages: ["/users", %r{\A/users/\d+/edit\z}] do
+  execute { |_args, _context| VoiceControl::Result.message("Edit the fields, then say submit.") }
+end
+```
+
+Strings match exactly; regexes let you match routes containing IDs. Commands without `pages:` remain global, which is useful for navigation. Help and Jev receive only commands available on the current page. Page scopes are routing hints supplied by the browser; keep authorization in `authorize:`. [Scope rules →](docs/commands.md#page-scopes)
+
+[Arguments, groups, authorization, and result types →](docs/commands.md)
+
+## Work with the page
+
+With `browser_actions = true`, voice_control discovers supported visible controls at command time. You do not register each button in Ruby.
+
+- **Click and navigate:** “click Performance,” “go back,” “scroll to Billing.”
+- **Edit:** “enter 500 into Token balance,” “select Premium from Plan,” “check notifications.”
+- **Use the selected field:** “enter Hello,” “clear this field,” “submit.”
+- **Undo:** restore the last unsaved VoiceControl field edit.
+
+Unique exact click labels resolve directly. Other phrases use Jev; ambiguous matches ask which command you meant. Discovery refreshes after Turbo navigation and DOM changes. Removed or changed controls are rejected before execution.
+
+Native dropdowns, checkboxes, radios, date/time inputs, and forms are supported. Iframes, other shadow roots, custom dropdowns, and multi-selects need application-specific commands. [Full browser-action guide →](docs/browser-actions.md)
+
+Disable automatic browser actions on a page, or exclude just part of its DOM:
+
+```html
+<!-- In the page's head: Ruby commands remain available. -->
+<meta name="voice-control-browser-actions" content="off">
+
+<!-- Or on a control/container: excludes it and its descendants. -->
+<section data-voice-control-ignore>Private controls go here</section>
+```
+
+These exclusions apply to discovery, help, and pending dynamic actions. [Exclusions and limits →](docs/browser-actions.md#exclude-pages-or-controls)
+
+**Command limit.** Jev accepts at most 255 choices per request, so at most 254 commands (your vocabulary plus discovered page actions) are matched at once. Beyond that, the commands with the longest descriptions/aliases are skipped for that request and a warning listing them is written to the Rails log (debug mode also shows `skipped_commands`). Skipped commands still work through help and exact click labels. Keep large pages under the limit with `pages:` scopes and `data-voice-control-ignore`.
+
+## Know what is sent and what can run
+
+Jev receives the transcript, configured page context (current URL/path by default), and available command descriptions. Dynamic discovery also sends control labels, IDs/names, types, and dropdown labels. Existing field values, Ruby code, and page HTML are not sent; anything the user types or speaks as a command is part of the transcript. Speech recognition may use the browser vendor's service.
+
+Use `data-voice-control-ignore` for private UI regions and a context callback to remove sensitive URL parameters. Jev chooses an allowed command; the server validates arguments and checks permissions before issuing and executing a signed, session-bound ticket. Duplicate tickets use an atomic cache claim. A confidence score is a routing signal, not an authorization check or a guarantee of intent.
+
+[Privacy, deployment, cache setup, and failure semantics →](docs/deployment.md)
+
+## Configuration
+
+All configuration options are below. Merge the settings you need into `config/initializers/voice_control.rb`, keep your command definitions in the same block, and restart Rails. Values match the defaults except the API key, which is read from your environment.
+
+```ruby
+VoiceControl.configure do |config|
+  # Server-side Jev key; a string or zero-argument callable. Default: nil.
+  config.api_key = ENV["JEV_API_KEY"]
+
+  # Jev model used to match natural-language commands.
+  config.model = "jev-latest"
+
+  # Engine endpoints inherit this controller's authentication and callbacks.
+  config.parent_controller = "ApplicationController"
+
+  # Widget/endpoint access; replace with your check, e.g. -> { current_user&.admin? }.
+  config.authorize = -> { false }
+
+  # Bind tickets to the signed-in user as well as the session; adapt for your auth system.
+  config.identity = -> { respond_to?(:current_user, true) ? current_user&.id : nil }
+
+  # Filter page context before matching; defaults to pass-through. Use .slice("path") to restrict it.
+  config.context = ->(client_context) { client_context }
+
+  # Discover labeled controls for click/fill/select/check/submit and page navigation commands.
+  # Sends labels/IDs and dropdown labels to Jev; excludes existing field values.
+  config.browser_actions = false
+
+  # Open/close shortcut; mod means Cmd on macOS, Ctrl elsewhere. nil disables it.
+  config.keyboard_shortcut = "mod+shift+u"
+
+  # Hold to speak, release to submit; nil disables this shortcut.
+  config.push_to_talk_shortcut = "mod+shift+space"
+
+  # Speech recognition language (BCP 47 tag, e.g. "uk-UA"); widget text and built-in page phrases stay English.
+  config.speech_language = "en-US"
+
+  # Widget corner: :bottom_right or :bottom_left.
+  config.widget_position = :bottom_right
+
+  # Button/icon size: :normal = 56px/24px; :small = 44px/20px. Panel size stays unchanged.
+  config.launcher_size = :normal
+
+  # Close and stop listening after this many milliseconds of inactivity; use a positive value.
+  config.idle_timeout = 120_000
+
+  # Browser request deadline in milliseconds (1_000..300_000); timed-out actions are never retried.
+  config.request_timeout = 30_000
+
+  # Matches below this score ask for disambiguation; calibrate for your vocabulary.
+  config.confidence_threshold = 0.35
+
+  # Show the latest transcript, Jev result and execution details; enable only for trusted users.
+  config.debug = false
+
+  # Default: Rails.cache, with a development-only MemoryStore fallback for NullStore.
+  # Override with a shared atomic cache for production replay protection.
+  # config.execution_store = -> { Rails.cache }
+
+  # nil uses Jev; a custom callable accepts transcript:, context:, commands: and returns a match.
+  config.interpreter = nil
+
+  # Unexpected-error callback; defaults to logging the error class and command, not the transcript.
+  config.on_error = ->(error, details) { Rails.logger.error("VoiceControl #{error.class} command=#{details[:command]}") }
+end
+```
+
+For a manually mounted web component, use `data-launcher-size="small"` for the compact launcher. See the [configuration reference](docs/configuration.md) for the custom interpreter contract and [deployment guide](docs/deployment.md) for cache and privacy setup.
+
+## Find the details
+
+| Guide | Includes |
+| --- | --- |
+| [Commands](docs/commands.md) | DSL, argument types, visibility, authorization, results |
+| [Browser actions](docs/browser-actions.md) | Supported controls, selection, submit, Undo, limits, debug JSON |
+| [Integration](docs/integration.md) | Turbo, React, context, keyboard shortcuts, push-to-talk |
+| [Configuration](docs/configuration.md) | Every option and default |
+| [Deployment](docs/deployment.md) | Shared cache, privacy, CSP, rate limiting, troubleshooting |
+| [Demo](docs/demo.md) | Local interpreter, Jev setup, SQLite data |
+| [Contributing](CONTRIBUTING.md) | Tests, >95% coverage gates, browser checks, packaging |
+
+**Debug a command:** set `config.debug = true`, restart Rails, and expand **Command details**. Inspect the matching source, chosen action, confidence, candidates, and Jev's choice/probabilities. Copy details for a reproducible report. Debug is off by default.
+
+Voice uses browser Speech Recognition in `config.speech_language` (default `en-US`); widget text and built-in page phrases are English. Typing is the fallback when voice is unavailable. See [browser support and microphone requirements](docs/integration.md#browser-support).
+
+## License
+
+[MIT](LICENSE). Copyright © 2026 Igor Kasyanchuk.

data/SECURITY.md

@@ -0,0 +1,15 @@
+# Security
+
+VoiceControl is currently unreleased. Do not use public issues to disclose exploitable vulnerabilities, credentials, transcripts, or private page data. Before public publication, the maintainer must establish and publish a private reporting channel; this checkout does not yet advertise one.
+
+## Integration boundary
+
+- Overall authorization defaults to deny. Add record-level authorization and tenant scoping to mutation commands.
+- Jev matches intent; it does not authorize operations. Commands execute immediately after validation, without a confirmation dialog.
+- Tickets are signed, expire, and bind to the session and configured identity. They are readable by the client, not encrypted.
+- Production replay protection requires a shared atomic cache. Eviction, outages, or resets are application operational concerns; business-critical actions also need durable idempotency.
+- Browser manifests and page context are untrusted. Underlying HTTP endpoints must enforce their own permissions.
+- Transcripts/context/control labels may be sent to Jev. Browser speech recognition may use another remote service. Exclude sensitive labels, filter context and Rails logs, and keep provider keys server-side.
+- Closing the widget cannot undo a server operation already in progress.
+
+See [deployment guidance](docs/deployment.md) for configuration, logging, CSP, rate limiting, and failure semantics. Report findings with a minimal reproduction and affected versions, without real user data.

data/app/controllers/voice_control/assets_controller.rb

@@ -0,0 +1,20 @@
+module VoiceControl
+  class AssetsController < ActionController::Base
+    skip_forgery_protection
+    def javascript
+      send_asset("widget.js", "text/javascript")
+    end
+
+    def stylesheet
+      send_asset("widget.css", "text/css")
+    end
+
+    private
+
+    def send_asset(name, type)
+      path = Engine.root.join("assets", name)
+      expires_in Rails.env.development? ? 0.seconds : 1.hour, public: true
+      send_data File.binread(path), type: type, disposition: "inline" if stale?(etag: Digest::SHA256.file(path).hexdigest, public: true)
+    end
+  end
+end

data/app/controllers/voice_control/commands_controller.rb

@@ -0,0 +1,77 @@
+module VoiceControl
+  class CommandsController < VoiceControl.configuration.parent_controller.constantize
+    wrap_parameters false
+    protect_from_forgery with: :exception
+    before_action :voice_control_authorize
+    before_action :voice_control_no_store
+    before_action :voice_control_start_timer
+    rescue_from StandardError, with: :voice_control_error
+    rescue_from VoiceControl::Forbidden, with: :voice_control_forbidden
+    rescue_from VoiceControl::InvalidInput, with: :voice_control_invalid
+
+    def index
+      render json: { commands: conversation.catalog(page_path: params[:path]).map(&:as_json) }
+    end
+
+    def create
+      context = params[:context]
+      context = context.to_unsafe_h if context.is_a?(ActionController::Parameters)
+      browser_page = params[:browser_page]
+      browser_page = browser_page.to_unsafe_h if browser_page.is_a?(ActionController::Parameters)
+      render_result conversation.interpret(transcript: params[:transcript] || "", client_context: context || {},
+        command_key: params[:command], continuation: params[:continuation], browser_page: browser_page)
+    end
+
+    def execute
+      render_result conversation.execute(params[:ticket])
+    end
+
+    private
+
+    def voice_control_start_timer
+      @voice_control_started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def render_result(result, status: :ok)
+      if VoiceControl.configuration.debug == true && @voice_control_started_at
+        result = result.merge(debug: (@conversation&.diagnostics || {}).merge(
+          stage: action_name == "execute" ? "execute" : "interpret", outcome: result[:kind],
+          message: result[:message], duration_ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - @voice_control_started_at) * 1000).round))
+      end
+      render json: result, status: status
+    end
+
+    def conversation
+      @conversation ||= Conversation.new(self)
+    end
+
+    def voice_control_authorize
+      raise Forbidden unless instance_exec(&VoiceControl.configuration.authorize)
+    end
+
+    def voice_control_no_store
+      response.headers["Cache-Control"] = "no-store"
+    end
+
+    def voice_control_forbidden
+      render_result({ kind: "error", message: "You cannot run this command." }, status: :forbidden)
+    end
+
+    def voice_control_invalid(error)
+      render_result({ kind: "error", message: error.message }, status: :unprocessable_content)
+    end
+
+    def voice_control_error(error)
+      if error.is_a?(ActionController::InvalidAuthenticityToken)
+        render_result({ kind: "error", message: "Your session changed. Reload the page." }, status: :unprocessable_content)
+      else
+        begin
+          VoiceControl.configuration.on_error.call(error, { command: conversation.command_key || params[:command], controller: self })
+        rescue StandardError => reporting_error
+          Rails.logger.error("VoiceControl error callback failed: #{reporting_error.class}")
+        end
+        render_result({ kind: "error", message: "Something went wrong. Check the result before trying again." }, status: :internal_server_error)
+      end
+    end
+  end
+end