inquirex 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a1021c83f11e037c69736dd5fa9228d95af53c9f7967173dd21bf9b096d4f31
-  data.tar.gz: 5b3cec5558da5aa1f9c3850e77ff6021916b9652531862ba621b8a7ea65fd5a7
+  metadata.gz: 5457c529512019dbfcb838eb1a607d933d85cad7a2edc926bd0049eca271f2f0
+  data.tar.gz: f561ac674e088508c2bb33726016660dc5a29cbbeb085e17ec84de8833c45859
 SHA512:
-  metadata.gz: aba4ff0487e52177d96fdf385c3268f4ea3c888c7e0e711547ec7b78700c7b5b377d573235823a5d8fe2861553006bed2b7573cdc9c8c38c2fc480ae0af81aa9
-  data.tar.gz: d1f7ccf5705755923d240414abb3e688534a618a36f9607fd60d6a526b72886c5d7fd86d8b1b93589edf16f7627c0ac2c26be4d7d42f1a4109f9f0bf1376ee2e
+  metadata.gz: be941ae3435a8e114dce7234477afb5d29e2624f7ddf8ed07fe8118d23b031390dd4c59610251f8419469765e4c6db5bc5413522b9f1befcc5e218e95b295513
+  data.tar.gz: 831876215c0ee5cd29d7bf72549d9a430633b3dafe6f154e813df2891381bc9d269ddddbcef117a6b86697c32ae4708fdf30faf0a2d8f18e259b3f933f76c1a2

data/README.md

@@ -1,3 +1,5 @@
+[![Ruby](https://github.com/inquirex/inquirex/actions/workflows/main.yml/badge.svg)](https://github.com/inquirex/inquirex/actions/workflows/main.yml)   ![Coverage](docs/badges/coverage_badge.svg)
+
 # Inquirex
 
 `inquirex` is a pure Ruby, declarative, rules-driven questionnaire engine for building conditional intake forms, qualification wizards, and branching surveys.
@@ -6,6 +8,8 @@ It is the core gem in the Inquirex ecosystem and focuses on:
 
 - A conversational DSL (`ask`, `say`, `header`, `btw`, `warning`, `confirm`)
 - A serializable AST rule system (`contains`, `equals`, `greater_than`, `less_than`, `not_empty`, `all`, `any`)
+- Framework-agnostic widget rendering hints (`widget` DSL verb, `WidgetHint`, `WidgetRegistry`)
+- Named **accumulators** for running totals (pricing, complexity scoring, credit scoring, lead qualification)
 - An immutable flow definition graph
 - A runtime engine for stateful step traversal
 - JSON round-trip serialization for cross-platform clients
@@ -13,10 +17,10 @@ It is the core gem in the Inquirex ecosystem and focuses on:
 
 ## Status
 
-- Version: `0.1.0`
+- Version: `0.2.0`
 - Ruby: `>= 4.0.0` (project currently uses `4.0.2`)
-- Test suite: `109 examples, 0 failures`
-- Coverage: ~`92.5%` line coverage
+- Test suite: `220 examples, 0 failures`
+- Coverage: ~`94%` line coverage
 
 ## Why Inquirex
 
@@ -56,6 +60,8 @@ definition = Inquirex.define id: "tax-intake-2025", version: "1.0.0" do
     type :enum
     question "What is your filing status?"
     options single: "Single", married_jointly: "Married Filing Jointly"
+    widget target: :desktop, type: :radio_group, columns: 2
+    widget target: :mobile,  type: :dropdown
     transition to: :dependents
   end
 
@@ -98,7 +104,8 @@ engine.finished? # => true
 ### Flow-level methods
 
 - `start :step_id` sets the entry step
-- `meta title:, subtitle:, brand:` adds optional frontend metadata
+- `meta title:, subtitle:, brand:, theme:` adds optional frontend metadata (see [Theme](#theme-and-branding))
+- `accumulator :name, type:, default:` declares a running total (see [Accumulators](#accumulators))
 
 ### Step verbs
 
@@ -128,6 +135,212 @@ engine.finished? # => true
 - `skip_if rule`
 - `transition to: :next_step, if_rule: rule, requires_server: false`
 - `compute { |answers| ... }` (accepted by the DSL as a server-side hook; currently omitted from runtime JSON)
+- `widget target: :desktop, type: :radio_group, columns: 2` (rendering hint for frontend adapters)
+- `accumulate :name, lookup:|per_selection:|per_unit:|flat:` (contribution to a named running total; see [Accumulators](#accumulators))
+- `price ...` (sugar for `accumulate :price, ...`)
+
+## Widget Rendering Hints
+
+Every collecting step can carry framework-agnostic rendering hints via the `widget` DSL verb. Frontend adapters (JS widget, TTY, Rails) use these to pick the right UI control.
+
+```ruby
+ask :priority do
+  type :enum
+  question "How urgent is this?"
+  options low: "Low", medium: "Medium", high: "High"
+  widget target: :desktop, type: :radio_group, columns: 3
+  widget target: :mobile,  type: :dropdown
+  widget target: :tty,     type: :select
+  transition to: :next_step
+end
+```
+
+When no explicit `widget` is set, `WidgetRegistry` fills in sensible defaults per data type:
+
+| Data Type | Desktop | Mobile | TTY |
+|-----------|---------|--------|-----|
+| `:enum` | `radio_group` | `dropdown` | `select` |
+| `:multi_enum` | `checkbox_group` | `checkbox_group` | `multi_select` |
+| `:boolean` | `toggle` | `yes_no_buttons` | `yes_no` |
+| `:string` | `text_input` | `text_input` | `text_input` |
+| `:text` | `textarea` | `textarea` | `multiline` |
+| `:integer` | `number_input` | `number_input` | `number_input` |
+| `:currency` | `currency_input` | `currency_input` | `number_input` |
+| `:date` | `date_picker` | `date_picker` | `text_input` |
+
+Display verbs (`say`, `header`, `btw`, `warning`) have no widget hints.
+
+Widget hints are included in JSON serialization under a `"widget"` key, keyed by target:
+
+```json
+"widget": {
+  "desktop": { "type": "radio_group", "columns": 3 },
+  "mobile":  { "type": "dropdown" },
+  "tty":     { "type": "select" }
+}
+```
+
+### Accessing Hints at Runtime
+
+```ruby
+step = definition.step(:priority)
+step.widget_hint_for(target: :desktop)            # explicit hint or nil
+step.effective_widget_hint_for(target: :desktop)   # explicit hint or registry default
+```
+
+> **Note:** Widget hints were previously in a separate `inquirex-ui` gem. As of v0.2.0 they are part of core, since every frontend adapter needs them.
+
+## Accumulators
+
+Accumulators are **named running totals** that a flow maintains as the user answers questions. The canonical use case is **pricing** — totalling the cost of a tax return, a SaaS quote, or an insurance premium — but the same primitive generalizes to **complexity scoring**, **credit scoring**, **lead qualification scores**, **risk scores**, or any other numeric tally.
+
+Like rules, accumulator declarations are **pure data**. They serialize to JSON and evaluate identically on the Ruby server and in the JS widget — no lambdas, no server round-trips.
+
+### Declaring accumulators
+
+Each flow declares one or more accumulators with a name, a type, and a starting value:
+
+```ruby
+Inquirex.define id: "tax-pricing-2025" do
+  accumulator :price,      type: :currency, default: 0
+  accumulator :complexity, type: :integer,  default: 0
+  # ...
+end
+```
+
+### Contributing to an accumulator from a step
+
+Use the `accumulate` verb inside any `ask`/`confirm` step. Exactly one **shape** key must be provided:
+
+| Shape | Fits | Semantics |
+|-------|------|-----------|
+| `lookup: { ... }` | `:enum` | Adds the amount mapped to the chosen option value |
+| `per_selection: { ... }` | `:multi_enum` | Sums the amounts for every selected option |
+| `per_unit: N` | `:integer`, `:decimal` | Multiplies the numeric answer by `N` |
+| `flat: N` | any type | Adds `N` when the step has a truthy, non-empty answer |
+
+```ruby
+ask :filing_status do
+  type :enum
+  question "Filing status?"
+  options single: "Single", mfj: "Married Filing Jointly", hoh: "Head of Household"
+  accumulate :price,      lookup: { single: 200, mfj: 400, hoh: 300 }
+  accumulate :complexity, lookup: { mfj: 1 }
+  transition to: :dependents
+end
+
+ask :dependents do
+  type :integer
+  question "How many dependents?"
+  default 0
+  accumulate :price, per_unit: 25          # $25 per dependent
+  transition to: :schedules
+end
+
+ask :schedules do
+  type :multi_enum
+  question "Which schedules apply?"
+  options c: "Schedule C (Business)",
+    e: "Schedule E (Rental)",
+    d: "Schedule D (Capital Gains)"
+  accumulate :price,      per_selection: { c: 150, e: 75, d: 50 }
+  accumulate :complexity, per_selection: { c: 2, e: 1, d: 1 }
+  transition to: :done
+end
+```
+
+A single step can contribute to any number of accumulators.
+
+### The `price` sugar
+
+Since `:price` is the most common use case (lead qualification, tax prep, SaaS quotes), there's a one-liner:
+
+```ruby
+price single: 200, mfj: 400, hoh: 300   # => accumulate :price, lookup: { ... }
+price per_unit: 25                       # => accumulate :price, per_unit: 25
+price per_selection: { c: 150, e: 75 }   # => accumulate :price, per_selection: { ... }
+```
+
+If you pass a plain option-value → amount hash (no shape key), `price` treats it as a `lookup`.
+
+### Reading totals at runtime
+
+The engine maintains running totals as each answer comes in:
+
+```ruby
+engine = Inquirex::Engine.new(definition)
+engine.answer("mfj")     # filing_status: +$400, +1 complexity
+engine.answer(3)         # dependents:    +$75
+engine.answer(%w[c e])   # schedules:     +$225, +3 complexity
+
+engine.total(:price)      # => 700.0
+engine.total(:complexity) # => 4
+engine.totals             # => { price: 700.0, complexity: 4 }
+```
+
+`#to_state` includes `totals:` so persisted sessions resume with the correct running total.
+
+### JSON wire format
+
+Accumulators serialize predictably, keeping the contract with `inquirex-js` explicit:
+
+```json
+{
+  "accumulators": {
+    "price":      { "type": "currency", "default": 0 },
+    "complexity": { "type": "integer",  "default": 0 }
+  },
+  "steps": {
+    "filing_status": {
+      "verb": "ask",
+      "type": "enum",
+      "accumulate": {
+        "price":      { "lookup": { "single": 200, "mfj": 400, "hoh": 300 } },
+        "complexity": { "lookup": { "mfj": 1 } }
+      }
+    },
+    "dependents": {
+      "verb": "ask",
+      "type": "integer",
+      "accumulate": { "price": { "per_unit": 25 } }
+    },
+    "schedules": {
+      "verb": "ask",
+      "type": "multi_enum",
+      "accumulate": {
+        "price":      { "per_selection": { "c": 150, "e": 75, "d": 50 } },
+        "complexity": { "per_selection": { "c": 2, "e": 1, "d": 1 } }
+      }
+    }
+  }
+}
+```
+
+The `inquirex-js` widget reads this verbatim and reproduces the same totals client-side.
+
+## Theme and Branding
+
+The flow's `meta` hash carries optional branding and theme overrides for the JS widget. Identity (name, logo) goes in `brand:`; colors, fonts, and radii go in `theme:`.
+
+```ruby
+meta title: "Tax Preparation Intake",
+  subtitle: "Let's understand your situation",
+  brand: { name: "Agentica", logo: "https://cdn.example.com/logo.png" },
+  theme: {
+    brand:       "#2563eb",
+    on_brand:    "#ffffff",
+    background:  "#0b1020",
+    surface:     "#111827",
+    text:        "#f9fafb",
+    text_muted:  "#94a3b8",
+    border:      "#1f2937",
+    radius:      "18px",
+    font:        "Inter, system-ui, sans-serif",
+    header_font: "Inter, system-ui, sans-serif"
+  }
+```
+
+Snake-case keys (`on_brand`, `text_muted`, `header_font`) are idiomatic Ruby; they're automatically translated to the camelCase names (`onBrand`, `textMuted`, `headerFont`) the JS widget expects on the wire. Each theme key maps 1:1 to a CSS custom property on the widget's shadow root.
 
 ## Rule System (AST, JSON-serializable)
 
@@ -159,13 +372,32 @@ transition to: :complex_path,
 - `current_step`
 - `answers` (raw hash)
 - `history` (visited step IDs)
+- `totals` (running totals per accumulator — see [Accumulators](#accumulators))
 
 Behavior:
 
 - Use `answer(value)` on collecting steps
 - Use `advance` on display steps
 - Use `finished?` to detect completion
-- Use `to_state` / `.from_state` for persistence/resume
+- Use `total(:price)` / `totals` to read running totals
+- Use `to_state` / `.from_state` for persistence/resume (totals included)
+- Use `prefill!(hash)` to merge externally-supplied answers into the state,
+  e.g. fields extracted by an LLM from a free-text answer (see
+  [inquirex-llm](#extension-gems)). Existing answers are preserved; `nil`
+  and empty values are ignored so they don't spuriously satisfy
+  `not_empty` rules. The engine auto-advances past any newly-skippable step.
+
+```ruby
+engine = Inquirex::Engine.new(definition)
+engine.answer("I'm MFJ with two kids in California.") # free-text :describe
+
+# Step is now :extracted (a clarify node); adapter returns a Hash.
+result = adapter.call(engine.current_step, engine.answers)
+engine.answer(result)           # store under the clarify step's id
+engine.prefill!(result)         # splat into top-level answers
+# Downstream :filing_status, :dependents, :state are now auto-skipped by
+# `skip_if not_empty(:filing_status)` etc.
+```
 
 ### Validation Adapter
 
@@ -192,14 +424,18 @@ restored = Inquirex::Definition.from_json(json)
 Serialized structure includes:
 
 - Flow metadata (`id`, `version`, `meta`, `start`)
+- Branding and theme (`meta.brand`, `meta.theme`)
+- Accumulator declarations (`accumulators`) and per-step contributions (`accumulate`)
 - Steps and transitions
 - Rule AST payloads
+- Widget hints
 
 Important serialization details:
 
-- Rule objects serialize and deserialize cleanly
+- Rule objects and accumulator shapes serialize and deserialize cleanly
 - Proc/lambda defaults are stripped from JSON
 - `requires_server: true` transition flag is preserved
+- Snake-case theme keys are converted to camelCase on serialization to match the JS widget contract
 
 ## Answers Wrapper
 
@@ -274,15 +510,27 @@ just lint-fix
 just ci
 ```
 
-## Roadmap Context
+## Extension Gems
+
+The core gem is designed to be extended by optional gems that inject new DSL verbs at `require` time:
+
+```ruby
+require "inquirex"       # core DSL, rules, engine, widget hints
+require "inquirex-llm"   # adds: clarify, describe, summarize, detour
+
+Inquirex.define do       # one entry point, all verbs available
+  # ...
+end
+```
+
+### Ecosystem
 
-This repository is the core runtime (`inquirex`). The full ecosystem roadmap includes:
+- **`inquirex-llm`** -- LLM-powered verbs (`clarify`, `describe`, `summarize`, `detour`) for server-side AI processing
+- **`inquirex-tty`** -- terminal adapter using TTY Toolkit
+- **`inquirex-js`** -- embeddable browser widget (chat-style)
+- **`inquirex-rails`** -- Rails Engine for persistence, API, and asset serving
 
-- `inquirex-ui` for rendering metadata
-- `inquirex-tty` for terminal interaction
-- `inquirex-js` for embeddable web widget runtime
-- `inquirex-llm` for server-side LLM verbs
-- `inquirex-rails` for persistence/API integration
+> **Note:** `inquirex-ui` has been merged into core as of v0.2.0. Widget hints (`widget` DSL verb, `WidgetHint`, `WidgetRegistry`) are now built in.
 
 ## License
 

data/docs/badges/coverage_badge.svg

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="99" height="20">
+  <linearGradient id="b" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <mask id="a">
+    <rect width="99" height="20" rx="3" fill="#fff"/>
+  </mask>
+  <g mask="url(#a)">
+    <path fill="#555" d="M0 0h63v20H0z"/>
+    <path fill="#4c1" d="M63 0h36v20H63z"/>
+    <path fill="url(#b)" d="M0 0h99v20H0z"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+    <text x="31.5" y="15" fill="#010101" fill-opacity=".3">coverage</text>
+    <text x="31.5" y="14">coverage</text>
+    <text x="80" y="15" fill="#010101" fill-opacity=".3">95%</text>
+    <text x="80" y="14">95%</text>
+  </g>
+</svg>

data/lib/inquirex/accumulator.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Inquirex
+  # Declares a named running total (e.g. :price, :complexity, :credit_score) that
+  # flows accumulate into as the user answers questions. Pure data, serializable
+  # to JSON, evaluated identically on Ruby and JS sides.
+  #
+  # @attr_reader name [Symbol] accumulator identifier (e.g. :price)
+  # @attr_reader type [Symbol] one of Node::TYPES (typically :currency, :integer, :decimal)
+  # @attr_reader default [Numeric] starting value (default: 0)
+  class Accumulator
+    attr_reader :name, :type, :default
+
+    def initialize(name:, type: :decimal, default: 0)
+      @name = name.to_sym
+      @type = type.to_sym
+      @default = default
+      freeze
+    end
+
+    def to_h
+      { "type" => @type.to_s, "default" => @default }
+    end
+
+    def self.from_h(name, hash)
+      new(
+        name:    name,
+        type:    hash["type"] || hash[:type] || :decimal,
+        default: hash["default"] || hash[:default] || 0
+      )
+    end
+  end
+
+  # Per-step declaration of how a single answer contributes to one accumulator.
+  # A Node may carry zero or more Accumulation entries, one per target accumulator.
+  #
+  # Supported shapes (exactly one must be set):
+  #   lookup:        Hash of answer_value => amount (for :enum)
+  #   per_selection: Hash of option_value => amount (for :multi_enum, summed)
+  #   per_unit:      Numeric rate multiplied by the answer (for numeric types)
+  #   flat:          Numeric amount added if the step has any answer
+  #
+  # @attr_reader target [Symbol] accumulator name to contribute to (e.g. :price)
+  # @attr_reader shape [Symbol] one of :lookup, :per_selection, :per_unit, :flat
+  # @attr_reader payload [Object] shape-specific data (Hash or Numeric)
+  class Accumulation
+    SHAPES = %i[lookup per_selection per_unit flat].freeze
+
+    attr_reader :target, :shape, :payload
+
+    def initialize(target:, shape:, payload:)
+      @target = target.to_sym
+      @shape = shape.to_sym
+      raise Errors::DefinitionError, "Unknown accumulator shape: #{shape.inspect}" unless SHAPES.include?(@shape)
+
+      @payload = self.class.send(:normalize_payload, @shape, payload).freeze
+      freeze
+    end
+
+    # Computes this accumulation's contribution given the step's answer.
+    # Returns 0 when the answer is absent or does not match the shape.
+    #
+    # @param answer [Object] the user's answer for the owning step
+    # @return [Numeric]
+    def contribution(answer)
+      return 0 if answer.nil?
+
+      case @shape
+      when :lookup        then lookup_amount(answer)
+      when :per_selection then selection_amount(answer)
+      when :per_unit      then unit_amount(answer)
+      when :flat          then flat_amount(answer)
+      end
+    end
+
+    def to_h
+      { @shape.to_s => serialize_payload }
+    end
+
+    # Parses a single-key Hash like `{ "lookup" => {...} }` into an Accumulation.
+    #
+    # @param target [Symbol, String] accumulator name
+    # @param hash [Hash] serialized shape (string or symbol keys)
+    # @return [Accumulation]
+    def self.from_h(target, hash)
+      pair = hash.to_a.find { |k, _| SHAPES.include?(k.to_sym) }
+      raise Errors::SerializationError, "Invalid accumulation entry: #{hash.inspect}" unless pair
+
+      shape_key, payload = pair
+      new(target: target, shape: shape_key.to_sym, payload: payload)
+    end
+
+    def self.normalize_payload(shape, payload)
+      case shape
+      when :lookup, :per_selection
+        (payload || {}).each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+      else
+        payload
+      end
+    end
+    private_class_method :normalize_payload
+
+    private
+
+    def serialize_payload
+      case @shape
+      when :lookup, :per_selection
+        @payload.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+      else
+        @payload
+      end
+    end
+
+    def lookup_amount(answer)
+      @payload[answer.to_s] || 0
+    end
+
+    def selection_amount(answer)
+      return 0 unless answer.is_a?(Array)
+
+      answer.sum { |selected| @payload[selected.to_s] || 0 }
+    end
+
+    def unit_amount(answer)
+      numeric = numeric_for(answer)
+      return 0 if numeric.nil?
+
+      numeric * @payload
+    end
+
+    def flat_amount(answer)
+      return 0 if answer == false
+      return 0 if answer.respond_to?(:empty?) && answer.empty?
+
+      @payload
+    end
+
+    def numeric_for(value)
+      case value
+      when Numeric then value
+      when String  then Float(value, exception: false)
+      end
+    end
+  end
+end

data/lib/inquirex/definition.rb

@@ -13,20 +13,22 @@ module Inquirex
   # @attr_reader start_step_id [Symbol] id of the first step in the flow
   # @attr_reader steps [Hash<Symbol, Node>] frozen map of step id => node
   class Definition
-    attr_reader :id, :version, :meta, :start_step_id, :steps
+    attr_reader :id, :version, :meta, :start_step_id, :steps, :accumulators
 
     # @param start_step_id [Symbol] id of the initial step
     # @param nodes [Hash<Symbol, Node>] all steps keyed by id
     # @param id [String, nil] flow identifier
     # @param version [String] semver
     # @param meta [Hash] frontend metadata
+    # @param accumulators [Hash<Symbol, Accumulator>] named running totals
     # @raise [Errors::DefinitionError] if start_step_id is not present in nodes
-    def initialize(start_step_id:, nodes:, id: nil, version: "1.0.0", meta: {})
+    def initialize(start_step_id:, nodes:, id: nil, version: "1.0.0", meta: {}, accumulators: {})
       @id = id
       @version = version
       @meta = meta.freeze
       @start_step_id = start_step_id.to_sym
       @steps = nodes.freeze
+      @accumulators = accumulators.freeze
       validate!
       freeze
     end
@@ -65,6 +67,11 @@ module Inquirex
       hash["version"] = @version
       hash["meta"] = @meta unless @meta.empty?
       hash["start"] = @start_step_id.to_s
+      unless @accumulators.empty?
+        hash["accumulators"] = @accumulators.each_with_object({}) do |(name, acc), h|
+          h[name.to_s] = acc.to_h
+        end
+      end
       hash["steps"] = @steps.transform_keys(&:to_s).transform_values(&:to_h)
       hash
     end
@@ -89,13 +96,19 @@ module Inquirex
       meta = hash["meta"] || hash[:meta] || {}
       start = hash["start"] || hash[:start]
       steps_data = hash["steps"] || hash[:steps] || {}
+      acc_data = hash["accumulators"] || hash[:accumulators] || {}
 
       nodes = steps_data.each_with_object({}) do |(step_id, step_hash), acc|
         sym_id = step_id.to_sym
         acc[sym_id] = Node.from_h(sym_id, step_hash)
       end
 
-      new(start_step_id: start, nodes:, id:, version:, meta:)
+      accumulators = acc_data.each_with_object({}) do |(name, entry), h|
+        sym = name.to_sym
+        h[sym] = Accumulator.from_h(sym, entry)
+      end
+
+      new(start_step_id: start, nodes:, id:, version:, meta:, accumulators:)
     end
 
     private

data/lib/inquirex/dsl/flow_builder.rb

@@ -15,6 +15,19 @@ module Inquirex
         @start_step_id = nil
         @nodes = {}
         @meta = {}
+        @accumulators = {}
+      end
+
+      # Declares a named running total the flow accumulates into as answers come in.
+      # The `:price` accumulator is the common lead-qualification use case; others
+      # (e.g. :complexity, :credit_score) work identically.
+      #
+      # @param name [Symbol] e.g. :price
+      # @param type [Symbol] one of Node::TYPES (default :currency-ish: :decimal)
+      # @param default [Numeric] starting value (default: 0)
+      def accumulator(name, type: :decimal, default: 0)
+        sym = name.to_sym
+        @accumulators[sym] = Accumulator.new(name: sym, type:, default:)
       end
 
       # Sets the entry step id for the flow.
@@ -24,15 +37,28 @@ module Inquirex
         @start_step_id = step_id
       end
 
-      # Sets frontend metadata: title, subtitle, and brand information.
+      # Sets frontend metadata: title, subtitle, brand, and theme.
       #
       # @param title [String, nil]
       # @param subtitle [String, nil]
-      # @param brand [Hash, nil] e.g. { name: "Acme", color: "#2563eb" }
-      def meta(title: nil, subtitle: nil, brand: nil)
+      # @param brand [Hash, nil] identity — `{ name: "Acme", logo: "https://..." }`.
+      #   Colors and fonts belong in `theme:`, not here.
+      # @param theme [Hash, nil] visual overrides consumed by the JS widget.
+      #   Every key maps 1:1 to a CSS custom property on the widget's shadow root.
+      #   Supported keys: :brand, :on_brand (or :onBrand), :background, :surface,
+      #   :text, :text_muted (or :textMuted), :border, :radius, :font,
+      #   :header_font (or :headerFont).
+      #
+      # @example
+      #   meta title: "Tax Intake",
+      #     subtitle: "Let's get started",
+      #     brand: { name: "Agentica", logo: "https://cdn.example.com/logo.png" },
+      #     theme: { brand: "#2563eb", radius: "18px", font: "Inter, system-ui" }
+      def meta(title: nil, subtitle: nil, brand: nil, theme: nil)
         @meta[:title] = title if title
         @meta[:subtitle] = subtitle if subtitle
         @meta[:brand] = brand if brand
+        @meta[:theme] = normalize_theme(theme) if theme
       end
 
       # Defines a question step that collects typed input from the user.
@@ -91,12 +117,28 @@ module Inquirex
           nodes:         @nodes,
           id:            @flow_id,
           version:       @flow_version,
-          meta:          @meta
+          meta:          @meta,
+          accumulators:  @accumulators
         )
       end
 
+      # Maps snake_case theme keys (idiomatic in Ruby) to the camelCase names
+      # the JS widget (inquirex-js ThemeOverrides) expects on the wire.
+      THEME_KEY_ALIASES = {
+        on_brand:    :onBrand,
+        text_muted:  :textMuted,
+        header_font: :headerFont
+      }.freeze
+
       private
 
+      def normalize_theme(theme)
+        theme.each_with_object({}) do |(key, value), acc|
+          sym = key.to_sym
+          acc[THEME_KEY_ALIASES.fetch(sym, sym)] = value
+        end
+      end
+
       def add_step(id, verb, &block)
         builder = StepBuilder.new(verb)
         builder.instance_eval(&block) if block

data/lib/inquirex/dsl/step_builder.rb

@@ -18,6 +18,41 @@ module Inquirex
         @skip_if = nil
         @default = nil
         @compute = nil
+        @widget_hints = {}
+        @accumulations = []
+      end
+
+      # Declares how this step's answer contributes to a named accumulator.
+      # Exactly one shape key should be provided:
+      #   lookup:        Hash of answer_value => amount (for :enum)
+      #   per_selection: Hash of option_value => amount (for :multi_enum)
+      #   per_unit:      Numeric rate (multiplied by the numeric answer)
+      #   flat:          Numeric (added when the step has any answer)
+      #
+      # @example
+      #   accumulate :price, lookup: { single: 200, mfj: 400 }
+      #   accumulate :price, per_unit: 25
+      #   accumulate :price, per_selection: { c: 150, e: 75 }
+      #   accumulate :complexity, flat: 1
+      def accumulate(target, lookup: nil, per_selection: nil, per_unit: nil, flat: nil)
+        shape, payload = pick_accumulator_shape(lookup:, per_selection:, per_unit:, flat:)
+        @accumulations << Accumulation.new(target:, shape:, payload:)
+      end
+
+      # Sugar for the common `:price` accumulator. Accepts either a shape keyword
+      # (`lookup:`, `per_selection:`, `per_unit:`, `flat:`) or — when given plain
+      # option=>amount keys — treats it as a `lookup`. So both work:
+      #
+      #   price single: 200, mfj: 400           # => lookup
+      #   price per_unit: 25                    # => per_unit
+      #   price lookup: { single: 200, ... }    # => lookup (explicit)
+      def price(**kwargs)
+        shape_keys = %i[lookup per_selection per_unit flat]
+        if kwargs.keys.intersect?(shape_keys)
+          accumulate(:price, **kwargs.slice(*shape_keys))
+        else
+          accumulate(:price, lookup: kwargs)
+        end
       end
 
       # Sets the input data type for :ask steps.
@@ -45,6 +80,21 @@ module Inquirex
         @options = list
       end
 
+      # Sets a rendering hint for the given target context.
+      # Recognized targets: :desktop, :mobile, :tty (and any future targets).
+      #
+      # @param type [Symbol] widget type (e.g. :radio_group, :dropdown)
+      # @param target [Symbol] rendering context (default: :desktop)
+      # @param opts [Hash] widget-specific options (e.g. columns: 2)
+      #
+      # @example
+      #   widget target: :desktop, type: :radio_group, columns: 2
+      #   widget target: :mobile,  type: :dropdown
+      #   widget target: :tty,     type: :select
+      def widget(type:, target: :desktop, **opts)
+        @widget_hints[target.to_sym] = WidgetHint.new(type:, options: opts)
+      end
+
       # Adds a conditional transition. First matching transition wins.
       #
       # @param to [Symbol] target step id
@@ -85,25 +135,50 @@ module Inquirex
       def build(id)
         Node.new(
           id:,
-          verb:        @verb,
-          type:        resolve_type,
-          question:    @question,
-          text:        @text,
-          options:     @options,
-          transitions: @transitions,
-          skip_if:     @skip_if,
-          default:     @default
+          verb:          @verb,
+          type:          resolve_type,
+          question:      @question,
+          text:          @text,
+          options:       @options,
+          transitions:   @transitions,
+          skip_if:       @skip_if,
+          default:       @default,
+          widget_hints:  resolve_widget_hints,
+          accumulations: @accumulations
         )
       end
 
       private
 
+      def pick_accumulator_shape(lookup:, per_selection:, per_unit:, flat:)
+        provided = { lookup:, per_selection:, per_unit:, flat: }.compact
+        if provided.size != 1
+          raise Errors::DefinitionError,
+            "accumulate requires exactly one of :lookup, :per_selection, :per_unit, :flat (got #{provided.keys})"
+        end
+        provided.first
+      end
+
       def resolve_type
         # :confirm is sugar for :ask with type :boolean
         return :boolean if @verb == :confirm && @type.nil?
 
         @type
       end
+
+      # Fills in registry defaults for targets not explicitly set (collecting steps only).
+      # Display verbs get nil widget_hints.
+      def resolve_widget_hints
+        effective_type = resolve_type
+        return nil if effective_type.nil? && @widget_hints.empty?
+
+        hints = @widget_hints.dup
+        %i[desktop mobile].each do |target|
+          hints[target] ||= WidgetRegistry.default_hint_for(effective_type, context: target)
+        end
+        hints.compact!
+        hints.empty? ? nil : hints
+      end
     end
   end
 end

data/lib/inquirex/engine/state_serializer.rb

@@ -8,7 +8,8 @@ module Inquirex
       SYMBOLIZERS = {
         current_step_id: ->(v) { v&.to_sym },
         history:         ->(v) { Array(v).map { |e| e&.to_sym } },
-        answers:         ->(v) { symbolize_answers(v) }
+        answers:         ->(v) { symbolize_answers(v) },
+        totals:          ->(v) { symbolize_answers(v) }
       }.freeze
 
       # Normalizes a state hash so step ids and history entries are symbols.

data/lib/inquirex/engine.rb

@@ -10,7 +10,7 @@ module Inquirex
   # Validates each answer via an optional Validation::Adapter, then advances using
   # node transitions. Skips steps whose skip_if rule evaluates to true.
   class Engine
-    attr_reader :definition, :answers, :history, :current_step_id
+    attr_reader :definition, :answers, :history, :current_step_id, :totals
 
     # @param definition [Definition] the flow to run
     # @param validator [Validation::Adapter] optional (default: NullAdapter)
@@ -20,10 +20,19 @@ module Inquirex
       @history = []
       @current_step_id = definition.start_step_id
       @validator = validator
+      @totals = init_totals
       @history << @current_step_id
       skip_display_steps_if_needed
     end
 
+    # Convenience accessor for a single accumulator's running total.
+    #
+    # @param name [Symbol] accumulator name (e.g. :price)
+    # @return [Numeric]
+    def total(name)
+      @totals[name.to_sym] || 0
+    end
+
     # @return [Node, nil] current step node, or nil if flow is finished
     def current_step
       return nil if finished?
@@ -52,6 +61,7 @@ module Inquirex
       raise Errors::ValidationError, "Validation failed: #{result.errors.join(", ")}" unless result.valid?
 
       @answers[@current_step_id] = value
+      apply_accumulations(current_step, value)
       advance_step
     end
 
@@ -64,6 +74,33 @@ module Inquirex
       advance_step
     end
 
+    # Merges a hash of { step_id => value } into the top-level answers without
+    # clobbering answers the user has already provided. Used by LLM clarify
+    # steps to populate downstream answers from free-text extraction so that
+    # `skip_if not_empty(:id)` rules on later steps will fire.
+    #
+    # Nil/empty values in the hash are ignored so that "unknown" LLM outputs
+    # don't spuriously satisfy `not_empty` rules.
+    #
+    # If the engine's current step becomes skippable as a result of the prefill,
+    # it auto-advances past it.
+    #
+    # @param hash [Hash] answers keyed by step id
+    # @return [Hash] the updated answers
+    def prefill!(hash)
+      return @answers unless hash.is_a?(Hash)
+
+      hash.each do |key, value|
+        next if value.nil?
+        next if value.respond_to?(:empty?) && value.empty?
+
+        sym = key.to_sym
+        @answers[sym] = value unless @answers.key?(sym)
+      end
+      skip_if_needed unless finished?
+      @answers
+    end
+
     # Serializable state snapshot for persistence or resumption.
     #
     # @return [Hash]
@@ -71,7 +108,8 @@ module Inquirex
       {
         current_step_id: @current_step_id,
         answers:         @answers,
-        history:         @history
+        history:         @history,
+        totals:          @totals
       }
     end
 
@@ -96,6 +134,20 @@ module Inquirex
       @current_step_id = state[:current_step_id]
       @answers = state[:answers] || {}
       @history = state[:history] || []
+      @totals = state[:totals] || init_totals
+    end
+
+    def init_totals
+      @definition.accumulators.each_with_object({}) do |(name, acc), h|
+        h[name] = acc.default
+      end
+    end
+
+    def apply_accumulations(node, answer)
+      node.accumulations.each do |accumulation|
+        @totals[accumulation.target] ||= 0
+        @totals[accumulation.target] += accumulation.contribution(answer)
+      end
     end
 
     def advance_step

data/lib/inquirex/node.rb

@@ -23,6 +23,7 @@ module Inquirex
   # @attr_reader transitions [Array<Transition>] ordered conditional next-step edges
   # @attr_reader skip_if [Rules::Base, nil] rule to skip this step entirely
   # @attr_reader default [Object, nil] default value (pre-fill, user can change)
+  # @attr_reader widget_hints [Hash{Symbol => WidgetHint}, nil] rendering hints per target
   class Node
     # Valid DSL verbs and which ones collect input from the user.
     VERBS = %i[ask say header btw warning confirm].freeze
@@ -44,7 +45,9 @@ module Inquirex
       :option_labels,
       :transitions,
       :skip_if,
-      :default
+      :default,
+      :widget_hints,
+      :accumulations
 
     def initialize(id:,
       verb:,
@@ -54,7 +57,9 @@ module Inquirex
       options: nil,
       transitions: [],
       skip_if: nil,
-      default: nil)
+      default: nil,
+      widget_hints: nil,
+      accumulations: [])
       @id = id.to_sym
       @verb = verb.to_sym
       @type = type&.to_sym
@@ -63,10 +68,11 @@ module Inquirex
       @transitions = transitions.freeze
       @skip_if = skip_if
       @default = default
+      @widget_hints = widget_hints&.freeze
+      @accumulations = accumulations.freeze
       extract_options(options)
       freeze
     end
-    # rubocop:enable Metrics/ParameterLists
 
     # @return [Boolean] true if this step collects input from the user
     def collecting?
@@ -78,6 +84,23 @@ module Inquirex
       DISPLAY_VERBS.include?(@verb)
     end
 
+    # Returns the explicit widget hint for the given target, or nil.
+    #
+    # @param target [Symbol] e.g. :desktop, :mobile, :tty
+    # @return [WidgetHint, nil]
+    def widget_hint_for(target: :desktop)
+      @widget_hints&.fetch(target.to_sym, nil)
+    end
+
+    # Returns the explicit hint for the target, falling back to the
+    # registry default for this node's type when no explicit hint is set.
+    #
+    # @param target [Symbol] e.g. :desktop, :mobile, :tty
+    # @return [WidgetHint, nil]
+    def effective_widget_hint_for(target: :desktop)
+      widget_hint_for(target:) || WidgetRegistry.default_hint_for(@type, context: target)
+    end
+
     # Resolves the next step id from current answers by evaluating transitions in order.
     #
     # @param answers [Hash] current answer state
@@ -115,6 +138,18 @@ module Inquirex
       end
 
       hash["transitions"] = @transitions.map(&:to_h) unless @transitions.empty?
+
+      if @widget_hints && !@widget_hints.empty?
+        hash["widget"] = @widget_hints.transform_keys(&:to_s)
+                                      .transform_values(&:to_h)
+      end
+
+      unless @accumulations.empty?
+        hash["accumulate"] = @accumulations.to_h do |acc|
+          [acc.target.to_s, acc.to_h]
+        end
+      end
+
       hash
     end
 
@@ -132,10 +167,14 @@ module Inquirex
       transitions_data = hash["transitions"] || hash[:transitions] || []
       skip_if_data = hash["skip_if"] || hash[:skip_if]
       default = hash["default"] || hash[:default]
+      widget_data = hash["widget"] || hash[:widget]
+      accumulate_data = hash["accumulate"] || hash[:accumulate]
 
       transitions = transitions_data.map { |t| Transition.from_h(t) }
       skip_if = skip_if_data ? Rules::Base.from_h(skip_if_data) : nil
       options = deserialize_options(raw_options)
+      widget_hints = deserialize_widget_hints(widget_data)
+      accumulations = deserialize_accumulations(accumulate_data)
 
       new(
         id:,
@@ -146,7 +185,9 @@ module Inquirex
         options:,
         transitions:,
         skip_if:,
-        default:
+        default:,
+        widget_hints:,
+        accumulations:
       )
     end
 
@@ -159,7 +200,6 @@ module Inquirex
         @option_labels = raw.transform_keys(&:to_s).transform_values(&:to_s).freeze
       when Array
         if raw.first.is_a?(Hash)
-          # Already in [{ "value" => ..., "label" => ... }] format
           @options = raw.map { |o| (o["value"] || o[:value]).to_s }.freeze
           @option_labels = raw.to_h { |o| [(o["value"] || o[:value]).to_s, (o["label"] || o[:label]).to_s] }.freeze
         else
@@ -188,5 +228,21 @@ module Inquirex
       raw.to_h { |o| [(o["value"] || o[:value]).to_s, (o["label"] || o[:label]).to_s] }
     end
     private_class_method :deserialize_options
+
+    def self.deserialize_accumulations(data)
+      return [] unless data.is_a?(Hash)
+
+      data.map { |target, entry| Accumulation.from_h(target.to_sym, entry) }
+    end
+    private_class_method :deserialize_accumulations
+
+    def self.deserialize_widget_hints(widget_data)
+      return nil unless widget_data.is_a?(Hash) && widget_data.any? { |_, v| v.is_a?(Hash) }
+
+      widget_data.each_with_object({}) do |(target, hint_hash), acc|
+        acc[target.to_sym] = WidgetHint.from_h(hint_hash)
+      end
+    end
+    private_class_method :deserialize_widget_hints
   end
 end

data/lib/inquirex/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Inquirex
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end

data/lib/inquirex/widget_hint.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Inquirex
+  # Immutable rendering hint attached to a step node.
+  # Carries a widget type (e.g. :radio_group) and an optional options hash
+  # (e.g. { columns: 2 }). Framework-agnostic — consumed by the JS widget,
+  # TTY adapter, or any other frontend renderer.
+  #
+  # @example
+  #   hint = WidgetHint.new(type: :radio_group, options: { columns: 2 })
+  #   hint.to_h  # => { "type" => "radio_group", "columns" => 2 }
+  WidgetHint = Data.define(:type, :options) do
+    def initialize(type:, options: {})
+      super(type: type.to_sym, options: options.transform_keys(&:to_sym).freeze)
+    end
+
+    # Serializes to a flat hash: type key + option keys merged in.
+    #
+    # @return [Hash<String, Object>]
+    def to_h
+      { "type" => type.to_s }.merge(options.transform_keys(&:to_s))
+    end
+
+    # Deserializes from a plain hash (string or symbol keys).
+    #
+    # @param hash [Hash]
+    # @return [WidgetHint]
+    def self.from_h(hash)
+      type = hash["type"] || hash[:type]
+      options = hash.reject { |k, _| k.to_s == "type" }
+                    .transform_keys(&:to_sym)
+      new(type:, options:)
+    end
+  end
+end

data/lib/inquirex/widget_registry.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Inquirex
+  # Canonical mapping from Inquirex data types to default widget types per rendering context.
+  #
+  # Desktop defaults lean toward richer controls (radio groups, checkbox groups).
+  # Mobile defaults lean toward compact controls (dropdowns, toggles).
+  # TTY defaults align with tty-prompt methods.
+  #
+  # Adapters (TTY, JS, Rails) use this to pick an appropriate renderer when
+  # the DSL author has not specified an explicit `widget` hint.
+  module WidgetRegistry
+    WIDGET_TYPES = %i[
+      text_input
+      textarea
+      number_input
+      currency_input
+      toggle
+      yes_no_buttons
+      yes_no
+      radio_group
+      dropdown
+      checkbox_group
+      multi_select_dropdown
+      select
+      multi_select
+      enum_select
+      multiline
+      mask
+      slider
+      date_picker
+      email_input
+      phone_input
+    ].freeze
+
+    # Default widget per data type and rendering context.
+    DEFAULTS = {
+      string:     { desktop: :text_input,    mobile: :text_input,     tty: :text_input },
+      text:       { desktop: :textarea,      mobile: :textarea,       tty: :multiline },
+      integer:    { desktop: :number_input,  mobile: :number_input,   tty: :number_input },
+      decimal:    { desktop: :number_input,  mobile: :number_input,   tty: :number_input },
+      currency:   { desktop: :currency_input, mobile: :currency_input, tty: :number_input },
+      boolean:    { desktop: :toggle,        mobile: :yes_no_buttons, tty: :yes_no },
+      enum:       { desktop: :radio_group,   mobile: :dropdown,       tty: :select },
+      multi_enum: { desktop: :checkbox_group, mobile: :checkbox_group, tty: :multi_select },
+      date:       { desktop: :date_picker,   mobile: :date_picker,    tty: :text_input },
+      email:      { desktop: :email_input,   mobile: :email_input,    tty: :text_input },
+      phone:      { desktop: :phone_input,   mobile: :phone_input,    tty: :text_input }
+    }.freeze
+
+    # Returns the default widget type for a given data type and context.
+    #
+    # @param type [Symbol, String, nil] Inquirex data type (e.g. :enum, :integer)
+    # @param context [Symbol] :desktop, :mobile, or :tty (default: :desktop)
+    # @return [Symbol, nil] widget type symbol, or nil if type is unknown
+    def self.default_for(type, context: :desktop)
+      DEFAULTS.dig(type&.to_sym, context)
+    end
+
+    # Returns a WidgetHint with the default widget for the given type + context,
+    # or nil when no default exists (e.g. for display verbs with no type).
+    #
+    # @param type [Symbol, String, nil]
+    # @param context [Symbol]
+    # @return [WidgetHint, nil]
+    def self.default_hint_for(type, context: :desktop)
+      widget_type = default_for(type, context:)
+      widget_type ? WidgetHint.new(type: widget_type) : nil
+    end
+  end
+end

data/lib/inquirex.rb

@@ -13,9 +13,14 @@ require_relative "inquirex/rules/not_empty"
 require_relative "inquirex/rules/all"
 require_relative "inquirex/rules/any"
 
+# Widget hints
+require_relative "inquirex/widget_hint"
+require_relative "inquirex/widget_registry"
+
 # Core graph objects
 require_relative "inquirex/transition"
 require_relative "inquirex/evaluator"
+require_relative "inquirex/accumulator"
 require_relative "inquirex/node"
 require_relative "inquirex/definition"
 require_relative "inquirex/answers"

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: inquirex
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Konstantin Gredeskoul
-bindir: exe
+bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
@@ -18,8 +18,7 @@ description: Inquirex lets you define multi-step questionnaires as directed grap
   immutable definitions.
 email:
 - kigster@gmail.com
-executables:
-- inquirex
+executables: []
 extensions: []
 extra_rdoc_files: []
 files:
@@ -32,10 +31,11 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- exe/inquirex
+- docs/badges/coverage_badge.svg
 - justfile
 - lefthook.yml
 - lib/inquirex.rb
+- lib/inquirex/accumulator.rb
 - lib/inquirex/answers.rb
 - lib/inquirex/definition.rb
 - lib/inquirex/dsl.rb
@@ -60,15 +60,17 @@ files:
 - lib/inquirex/validation/adapter.rb
 - lib/inquirex/validation/null_adapter.rb
 - lib/inquirex/version.rb
+- lib/inquirex/widget_hint.rb
+- lib/inquirex/widget_registry.rb
 - sig/inquirex.rbs
-homepage: https://github.com/kigster/inquirex
+homepage: https://github.com/inquirex/inquirex
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/kigster/inquirex
-  source_code_uri: https://github.com/kigster/inquirex
-  changelog_uri: https://github.com/kigster/inquirex/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/inquirex/inquirex
+  source_code_uri: https://github.com/inquirex/inquirex
+  changelog_uri: https://github.com/inquirex/inquirex/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:

data/exe/inquirex

@@ -1,3 +0,0 @@
-#!/usr/bin/env ruby
-
-require "inquirex"