Studio

A Rails engine for storing, editing, trying and publishing definitions in a browser, mounted in your own app.

After reading this guide, you will know:

• How to mount Studio and what the host app provides.
• How a definition moves from a starting point, through drafts, to numbered versions.
• What Try it shows.
• How an app runs what Studio published.

Mounting It

# Gemfile, from the source your license gives you
gem 'reckoning'

# config/application.rb, or an initializer
require 'reckoning/studio'

# config/routes.rb
mount Reckoning::Studio::Engine, at: '/reckoning'

The engine adds its migration to the app’s migration paths, so bin/rails db:migrate creates its reckoning_studio_definitions and reckoning_studio_versions tables.

Rails comes from the host app, not the gemspec. The host provides:

• Rails and a database,
• resources_on_rails, which the list, show and new pages are built with,
• Sprockets, importmap with Stimulus, Turbo, Tailwind with the app colour scales, and Alpine,
• the visit and scroll_to_top Turbo stream actions.

The editor ships as ES modules through the engine’s importmap, with React and htm pinned from esm.sh, so the host needs no JavaScript build. sample/ in the gem’s repository shows all of it.

Authorization is a permissive policy for now. Mount Studio behind your own authentication:

authenticate :user, -> (user) { user.admin? } do
  mount Reckoning::Studio::Engine, at: '/reckoning'
end

A Definition’s Life

stateDiagram-v2
    [*] --> Draft: start from a starting point
    Draft --> Draft: autosave edits
    Draft --> Blocked: draft has problems
    Blocked --> Draft: fix them
    Draft --> Published: publish snapshots version n
    Published --> Draft: keep editing

• Start from a small blueprint that already runs (a sanity loss with a worked example), any shipped blueprint that does not import others, or any starting point a pack registers.
• Edit the draft in the browser. A blueprint is edited as YAML. It can import shipped blueprints by name, but not by path, since a draft is not a file. The draft autosaves and lists what stops it being published: the problems reckoning check would print.
• Try it from a form built from a calculation’s inputs, filled from its first worked example.
• Publish snapshots the draft as the next numbered version. A draft with problems is refused. Versions never change.

Studio checks the draft but does not run its worked examples when publishing, so keep running reckoning test on them (or prove them in a spec, see Worked Examples).

Try It

Trying a blueprint shows how every step was worked out: the formula, the table row, or each rule with whether it matched and the facts it read. A run over a list opens row by row. It is the same explanation reckoning run --trace prints.

Other Pages

• Blueprints lists every shipped blueprint on every shelf, with its YAML, its cases and its README.
• Fights plays the shipped coc_7e_duel blueprint: set up the fighters and a seed, play a Call of Cthulhu melee fight round by round with hit points after each round, choose for the investigators while the engine runs the monsters, or work out the odds over 50 fights.

Every route also answers .json, which the editor uses.

Running What Was Published

definition.template builds the latest published version, never the draft, so an edit in progress never reaches the app:

definition = Reckoning::Studio::Definition.find_by(name: 'Sales commission')
blueprint = definition&.published ? definition.template : Reckoning::Blueprint.shipped(:sales_commission)
blueprint.call(facts, calculation: :year)

See Running the Engine in a Rails App.

Trying It Locally

The gem’s repository has a sample app that mounts Studio:

bundle install
sample/bin/setup --skip-server
cd sample && bin/rails db:seed && bin/dev

Open http://localhost:3000/reckoning for Studio. The seed adds two of the shipped Call of Cthulhu blueprints as drafts, with their cases as worked examples. http://localhost:3000 is the sample’s keeper’s screen, a Call of Cthulhu table built only on the shipped blueprints.

Next Steps

• Packs - Add your own kind of definition, editor and starting points.
• The Hosted Service - Publish definitions to a service instead of your own app.