keystone_ui-pages 0.1.0

data/lib/keystone_ui/pages.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "keystone_ui/pages/version"
+require "keystone_ui/pages/catalog"
+require "keystone_ui/pages/values"
+require "keystone_ui/pages/keystone_elements"
+require "keystone_ui/pages/engine"
+
+module KeystoneUi
+  module Pages
+    class << self
+      attr_writer :base_controller, :layout, :editor_layout, :pdf_stylesheet
+      attr_accessor :edit_check_method, :view_check_method, :owner_method, :refusal_method, :chrome_path
+
+      def base_controller
+        @base_controller || "ActionController::Base"
+      end
+
+      def layout
+        @layout || "application"
+      end
+
+      def editor_layout
+        @editor_layout || "application"
+      end
+
+      def pdf_stylesheet
+        @pdf_stylesheet || "tailwind.css"
+      end
+    end
+
+    def self.pdf(page, values: {})
+      require "keystone_ui/pages/pdfs"
+      Pdfs.for(page, values: values)
+    end
+
+    def self.prepare_pdf(page, values: {})
+      PdfJob.perform_later(page, values.to_h.stringify_keys)
+    end
+
+    def self.catalog
+      @catalog ||= Catalog.new.tap { |catalog| KeystoneElements.register(catalog) }
+    end
+  end
+end

data/lib/keystone_ui-pages.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "keystone_ui/pages"

data/the_local/agents/keystone_ui-pages-develop.md

@@ -0,0 +1,277 @@
+---
+name: keystone_ui-pages-develop
+description: Use PROACTIVELY for working with Keystone UI Pages in a host app — its settings, host values, drawing a page in the host's own screens, making PDFs, linking editors to the builder, and adding or leaving out catalog elements — MUST BE USED instead of hand-building page drawing or PDF printing.
+tools: Read, Write, Edit, Grep
+scope: Pages — building, publishing and printing pages drawn with Keystone UI
+---
+
+This local works with Keystone UI Pages from the host app's side. It always
+works the same way: set what the engine asks the host for, hand it values, and
+draw or print the live version through the gem's own calls rather than reading
+page documents directly.
+
+## What Keystone UI Pages is
+
+Keystone UI Pages is a Rails engine that adds a page builder to a host app. A
+page is a JSON document of sections, rows, columns and elements, each element
+drawn by a Keystone UI component. Editors change a page's draft in the builder,
+and Publish saves it as a numbered live version. The host draws the live
+version in its own screens, prints it to PDF, and supplies values such as a
+client's name that bound fields and conditions read.
+
+Fire on any request to draw a page in a host screen, make or send a page as a
+PDF, give editors a link to the builder, supply values to pages, add a
+host-drawn element or remove one from the builder, or change who may view or
+edit pages. If the engine is not mounted or its migrations have not run, that
+is the `keystone_ui-pages-install` local's job, not this one's.
+
+## Interface
+
+All settings are plain writers, set in `config/initializers/keystone_ui_pages.rb`.
+Every method a setting names is called on the engine's controllers, which
+inherit from the base controller, so define it there.
+
+### Access and layout settings
+
+- `KeystoneUi::Pages.base_controller = "ApplicationController"` — a string
+  naming the class every engine controller inherits from. Defaults to
+  `"ActionController::Base"`. Its filters run on every engine request,
+  including published pages.
+- `KeystoneUi::Pages.owner_method = :current_team` — a method with no
+  arguments returning the record that owns pages, such as a team or account.
+  Every lookup, in the editor's screens and on published pages, is then limited
+  to `KeystoneUi::Pages::Page.where(owner: <that record>)`, and a new page is
+  created with it as owner. Unset, every page is visible to everyone and new
+  pages have no owner.
+- `KeystoneUi::Pages.view_check_method = :may_view_page?` — a method taking the
+  page and returning true when the current visitor may see the published page
+  at `/pages/:slug`. Unset, every published page is shown.
+- `KeystoneUi::Pages.edit_check_method = :may_edit_pages?` — a method with no
+  arguments returning true when the current user may use the editor's screens:
+  the page list, the builder, View live, History and the PDF link. It runs
+  before every one of those requests. Unset, everyone may.
+- `KeystoneUi::Pages.refusal_method = :refuse_page` — a method with no
+  arguments that renders the response when a request is refused: a failed view
+  or edit check, an unknown slug, or a page with no live version. Unset, the
+  response is an empty 404.
+- `KeystoneUi::Pages.layout = "application"` — the host layout published pages
+  and View live are drawn in. Defaults to `"application"`.
+- `KeystoneUi::Pages.editor_layout = "editor"` — the host layout the page
+  list, the builder and the version history are drawn in. Defaults to
+  `"application"`.
+
+### PDF settings
+
+- `KeystoneUi::Pages.chrome_path = "/usr/bin/chromium"` — the Chrome or
+  Chromium program that prints PDFs. Unset, the gem uses the `CHROME_BIN`
+  environment variable, then the first of `/usr/bin/google-chrome`,
+  `/usr/bin/google-chrome-stable`, `/usr/bin/chromium`,
+  `/usr/bin/chromium-browser`, and the Google Chrome and Chromium apps in
+  `/Applications` that can be run.
+- `KeystoneUi::Pages.pdf_stylesheet = "tailwind.css"` — the name of the host's
+  compiled stylesheet in Propshaft, written into every PDF. Defaults to
+  `"tailwind.css"`. A name Propshaft cannot find prints the PDF with no styles.
+
+### Host values
+
+- `KeystoneUi::Pages::Values.names = { "client_name" => "Client name" }` — a
+  hash of the value names the host supplies, each to the label the builder
+  shows. When it is not empty, an editor can bind a text, long text, address,
+  number, list or data field to one, with fallback text drawn when the value is
+  blank, and can show a section, row or element only when a value equals some
+  text.
+- `KeystoneUi::Pages::Values.chooser = ->(page) { [["Acme report", "acme"]] }`
+  — a callable taking the page and returning `[label, choice]` pairs. The
+  builder shows them in a "Preview with" choice, opening on the first pair, and
+  remembers the editor's choice per page for the session. Unset, the choice is
+  not shown.
+- `KeystoneUi::Pages::Values.provider = ->(page, choice) { { "client_name" => "Acme" } }`
+  — a callable taking the page and a choice from the chooser and returning a
+  hash of value names to values. The builder's canvas, View live and the page
+  list's PDF link draw the page with what it returns for the chosen choice.
+  Unset, they draw with no values.
+
+### Drawing and printing
+
+- `keystone_ui_page(page, values: {})` — a view helper, available in every host
+  view, that draws the page's live version with the values given, inside a
+  `<div class="@container">`. It returns nil when the page has never been
+  published. `values:` takes value names to values, with string or symbol keys.
+- `KeystoneUi::Pages.pdf(page, values: {})` — returns a
+  `KeystoneUi::Pages::Pdf` record for the page's live version drawn with the
+  values given. Its `file` is an Active Storage attachment, ready to download,
+  link or email. The same live version and values return the record already
+  kept, and a newly published version or different values print a new one.
+  When nothing is kept it prints in the current request.
+- `KeystoneUi::Pages.prepare_pdf(page, values: {})` — queues
+  `KeystoneUi::Pages::PdfJob`, which calls `KeystoneUi::Pages.pdf` with the same
+  page and values, so the file is kept before anyone asks for it.
+
+### The builder and the editor's screens
+
+- `/manage/pages` under the engine's mount path — the editor's page list, which
+  at the `/pages` mount is `/pages/manage/pages`, or
+  `keystone_ui_pages.manage_pages_path` from the host.
+- `/pages/manage/pages/:id?return_to=/admin/marketing` — the builder for one
+  page, or `keystone_ui_pages.manage_page_path(page, return_to: "/admin/marketing")`.
+  `return_to` must be a path on the host's own site, starting with a single
+  `/`. The builder's Back link returns there, even after Publish reloads the
+  builder. With no `return_to`, or one pointing at another site, Back goes to
+  the page list.
+
+### The element catalog
+
+- `KeystoneUi::Pages.catalog.register(key:, name:, component:, fields:, body: nil, icon: nil, group: nil, align: nil)`
+  — adds an element to the builder's palette, or replaces the one with the same
+  key. `key:` is a symbol stored in page documents. `name:` is the label in the
+  palette. `component:` is the name of a method the drawing calls with one
+  keyword argument per field, such as a `helper_method` on the base controller.
+  `body:` names one field whose value is passed as the method's block instead
+  of a keyword. `icon:` is one of `:cursor` `:tag` `:copy` `:heading` `:text`
+  `:list` `:info` `:code` `:alert` `:card` `:megaphone` `:chart` `:bars`
+  `:number` `:progress`, and any other value shows a box. `group:` is the
+  palette heading it sits under, `"Other"` when unset. `align:` is the default
+  placement in its column: `"stretch"`, `"start"`, `"center"` or `"end"`.
+- `KeystoneUi::Pages.catalog.leave_out(:copy_button)` — removes elements from
+  the palette by key. Takes several keys.
+
+Each entry in `fields:` is a hash. Its `key:` is the keyword the component
+receives and its `label:` is the label in the builder's field panel. Its
+`kind:` is one of `:text` (the default when no kind is given), `:long_text`,
+`:address`, `:number`, `:one_of`, `:yes_or_no`, `:list` or `:data`. A number
+arrives as an Integer, or a Float when it has a decimal point, a `:one_of`
+arrives as a symbol, and a `:yes_or_no` as true or false. Its `default:` is the
+value used until the editor sets one. A `:one_of` field takes `options:`, the
+list of choices as strings. A `:list` field takes `entry:`, an array of field
+hashes describing each entry's parts, and each entry arrives as a hash with
+symbol keys.
+
+A `:data` field cannot be typed in the builder. It holds data the host
+supplies through a bound value.
+
+The catalog offers these Keystone UI components by default: `button`,
+`progress`, `alert`, `code`, `heading`, `label`, `paragraph`, `hero`,
+`cta_banner`, `card`, `stat_card`, `figure`, `info`, `badge`, `copy_button`,
+`feature_grid`, `accordion`, `data_table`, `bar_chart`, `line_chart` and
+`value_list`.
+
+## How to use it
+
+1. Confirm the engine is mounted and its migrations have run: `config/routes.rb`
+   mounts `KeystoneUi::Pages::Engine` and `db/schema.rb` has
+   `keystone_ui_pages_pages`. If not, stop and hand off to
+   `keystone_ui-pages-install`.
+
+2. Read `config/initializers/keystone_ui_pages.rb` before changing a setting.
+   Every setting from the Interface is set there, and the methods they name are
+   on the controller named by `base_controller`.
+
+3. To change who may see or edit pages, set `owner_method`,
+   `view_check_method`, `edit_check_method` or `refusal_method`, and write the
+   method on the base controller. Who may see and change what is the
+   developer's decision. Ask before choosing a rule.
+
+4. To let pages use the host's data, set `Values.names` to the values the host
+   can supply. To let editors preview a page with real data, also set
+   `Values.chooser` and `Values.provider`. Ask the developer which records the
+   chooser lists, since it decides what editors see in the builder.
+
+5. To draw a page in a host screen with one client's values, find the page and
+   call the helper:
+
+   ```erb
+   <% page = KeystoneUi::Pages::Page.find_by(slug: "report", owner: current_team) %>
+   <%= keystone_ui_page(page, values: { "client_name" => @client.name, "score" => @client.score }) %>
+   ```
+
+   The drawing is kept in `Rails.cache` under the version and the values, so
+   the same version and values are drawn once. A page that uses host values
+   should be drawn this way, since the published address `/pages/:slug` draws
+   it with no values: bound fields show their fallback text there, and
+   conditions on a value hide what they guard unless they compare against blank.
+
+6. To make a PDF:
+
+   ```ruby
+   pdf = KeystoneUi::Pages.pdf(page, values: { "client_name" => "Acme" })
+   pdf.file
+   ```
+
+   To have it ready before anyone downloads it, such as when an invoice is
+   created, call `KeystoneUi::Pages.prepare_pdf(page, values: ...)` instead and
+   read `KeystoneUi::Pages.pdf` later with the same values. Publishing a page
+   that uses no host values queues its PDF straight away, since it looks the
+   same for everyone.
+
+   The page must be published, since only the live version is printed. The PDF
+   is the page drawn in light mode with the stylesheet named by
+   `pdf_stylesheet`, printed by Chrome or Chromium with no header or footer.
+   Printing keeps chart and cell colours on a white background and does not
+   split a section, a table row or a label and value row across pages.
+
+   When no Chrome or Chromium is found, the page list leaves out its PDF links
+   and `KeystoneUi::Pages.pdf` raises `KeystoneUi::Pages::PrintFailed` with a
+   message saying to install one or name it with `chrome_path` or `CHROME_BIN`.
+   It raises the same error when Chrome cannot be started or prints nothing.
+   Called from `prepare_pdf`, the error is raised inside the job, so the job
+   backend's retry rules apply. Ask the developer how a failed print should
+   reach the user before rescuing it.
+
+7. To give editors a way in, link to the page list, or to one page's builder
+   with a `return_to` of the screen they came from:
+
+   ```erb
+   <%= link_to "Edit page", keystone_ui_pages.manage_page_path(page, return_to: request.fullpath) %>
+   ```
+
+8. To add an element the host draws, write its component as a method that takes
+   the fields as keyword arguments, make it callable from views, and register
+   it:
+
+   ```ruby
+   Rails.application.config.after_initialize do
+     KeystoneUi::Pages.catalog.register(key: :testimonial, name: "Testimonial", component: :testimonial,
+       fields: [ { key: :quote, label: "Quote", kind: :long_text, default: "It works." } ])
+     KeystoneUi::Pages.catalog.leave_out(:copy_button)
+   end
+   ```
+
+   The method must be reachable in the engine's views and in any host view that
+   calls `keystone_ui_page`. A `helper_method` on the base controller covers
+   both. Leaving out an element that pages already use makes those pages fail
+   to draw, so search the pages' documents for its key before leaving it out.
+
+## Conventions
+
+- **Draw through the gem.** Use `keystone_ui_page` and `KeystoneUi::Pages.pdf`.
+  Never draw `page.document` or a version's document by hand, and never print a
+  PDF another way, because the gem's drawing applies bound values, conditions,
+  layout and print rules together.
+- **Only the live version leaves the builder.** The draft is what editors
+  change. Visitors, `keystone_ui_page` and PDFs show the live version, so an
+  unpublished change shows nowhere else.
+- **Value names are strings.** `Values.names`, the provider's hash and the
+  `values:` passed to the helper and to PDFs all use the same names. The gem
+  turns symbol keys into strings, so either works, but the names must match.
+- **The editor's page list** at `/pages/manage/pages` shows each page's name,
+  whether it is published or a draft, and when it was last published. Each row
+  links to Edit, and a published page also links to View live and, when Chrome
+  or Chromium is found, to its PDF.
+- **View live** draws the live version in `KeystoneUi::Pages.layout` with the
+  values of the sample chosen in the builder, behind the edit check. It is
+  linked from the page list and from the builder's top bar once the page is
+  published.
+- **History** lists every published version with its number, status and date.
+  Opening one draws it, and "Restore this version as the draft" replaces the
+  draft with that version's document. Restoring publishes nothing.
+- **Undo and Redo** are the builder's ↶ Undo and ↷ Redo buttons. They step
+  through the page's edits one at a time. The history is kept on the page, so
+  it survives a reload and a publish, and a new edit after an undo clears what
+  can be redone.
+- **The builder's top bar** also has a Mode choice of light, dark and system
+  (and custom for an editor in custom mode), a Look choice of the looks the host
+  registers with Keystone UI, and a Print choice that previews the printed
+  layout. None of them is saved.
+- Out of scope for this local: installing the gem, its migrations, the mount and
+  the layouts, which belong to `keystone_ui-pages-install`. Changing the
+  builder or the built-in elements belongs in the gem, not the host app.

data/the_local/agents/keystone_ui-pages-info.md

@@ -0,0 +1,71 @@
+---
+name: keystone_ui-pages-info
+description: Use to learn what Keystone UI Pages offers — the page builder, published versions, host values, PDFs and the element catalog — and the vocabulary the install and develop locals assume.
+tools: Read
+scope: Pages — building, publishing and printing pages drawn with Keystone UI
+---
+
+This local explains Keystone UI Pages and sends you to the local that does the
+work. It changes nothing and gives no steps.
+
+## What Keystone UI Pages is
+
+Keystone UI Pages is a Rails engine gem that adds a page builder to a host app.
+A page is a JSON document of sections, rows, columns and elements, and every
+element is drawn by a Keystone UI component, so a page looks like the rest of an
+app built with Keystone UI. Editors change the draft in a builder in the
+browser, and publishing it saves a numbered version. The live version is what
+visitors, the host's own screens and PDFs show.
+
+Reach for it when an app needs pages that people other than developers lay out
+and change: marketing pages, report templates, invoices. A page can hold values
+the host app supplies, such as a client's name, so one page serves as a template
+drawn with each client's values, on screen or as a PDF.
+
+## Interface
+
+This local declares no commands. The two working surfaces belong elsewhere:
+
+- **Getting the gem into a host app** — adding it, running the engine's and
+  Active Storage's migrations, mounting the engine, the layouts and the settings
+  file → **`keystone_ui-pages-install`**.
+- **Working with it** — what each setting does, host values, drawing a page in
+  the host's own screens, PDFs, linking to the builder and changing the element
+  catalog → **`keystone_ui-pages-develop`**.
+
+## How to use it
+
+One decision: is Keystone UI Pages already set up in the app?
+
+- No, or the setup is out of date → **`keystone_ui-pages-install`**.
+- Yes, and there is a page to draw, a PDF to make, a setting to change or an
+  element to add → **`keystone_ui-pages-develop`**.
+
+Keystone UI itself must be installed first. Its own install local,
+`keystone_ui-install`, does that.
+
+## Conventions
+
+- **Draft and versions.** A page's document is its draft. Publish copies the
+  draft into a new version marked live and marks the previous live version
+  superseded. Only the live version is ever shown outside the builder. A page
+  with no live version shows nothing.
+- **Pages belong to an owner.** A page has a name, a slug that is its address,
+  and an optional owner, which is any record. When the host names an owner
+  method, every lookup is limited to the current owner's pages, and a slug is
+  unique per owner.
+- **Host values.** The host names the values a page can use, such as a client's
+  name or a score. An editor binds an element's field to one, with fallback text
+  for when it is blank, or shows a section, row or element only when a value
+  equals something. The host supplies the values when it draws the page.
+- **The catalog.** The builder offers a fixed list of Keystone UI components as
+  elements. A host adds elements drawn by its own components and leaves out ones
+  it does not want. Navigation, form inputs, page frames and components whose
+  data the catalog cannot describe are not offered.
+- **PDFs are printed by Chrome or Chromium on the server** and kept in Active
+  Storage, one per live version and set of values.
+- **The editor's screens.** The page list, the builder, the version history and
+  View live all sit under the engine's `manage` routes and are open to whoever
+  passes the host's edit check.
+- Ruby >= 3.2. Rails >= 7.1. It depends on keystone_ui >= 0.49.0,
+  keystone_ui-styles >= 0.24.0 and keystone_ui-react >= 0.1.3.

data/the_local/agents/keystone_ui-pages-install.md

@@ -0,0 +1,167 @@
+---
+name: keystone_ui-pages-install
+description: Use to hook Keystone UI Pages into a project — adding the gem, installing and running the engine's migrations and Active Storage's, mounting the engine, preparing the live-page and editor layouts, and writing the settings file.
+tools: Bash, Read, Edit
+scope: Pages — building, publishing and printing pages drawn with Keystone UI
+---
+
+This local carries the steps for wiring Keystone UI Pages into a host app.
+Follow them in order, exactly as written, and invent none.
+
+## What Keystone UI Pages is
+
+A Rails engine gem that adds a page builder whose pages are drawn with Keystone
+UI components, published as versions and printed to PDF; hook it in before
+linking editors to the builder or drawing a page in the host's screens.
+
+## Interface
+
+- `bin/rails keystone_ui_pages:install:migrations` — copies the engine's
+  migrations into the host's `db/migrate`. They create the pages, versions and
+  PDFs tables and add the edit history columns that Undo and Redo use. Safe to
+  re-run, since a migration already copied is skipped.
+- `bin/rails active_storage:install` — Rails' own task that copies Active
+  Storage's migration. PDFs are kept as Active Storage attachments.
+- `mount KeystoneUi::Pages::Engine => "/pages"` — the line in
+  `config/routes.rb` that serves the builder, the editor's screens and the live
+  pages under the path given.
+
+## How to use it
+
+1. Confirm the prerequisites:
+
+   - Ruby >= 3.2 and Rails >= 7.1.
+   - Keystone UI installed and working. The gem brings keystone_ui,
+     keystone_ui-styles and keystone_ui-react with it, but Keystone UI's own
+     setup is the `keystone_ui-install` local's job. Do it first if it is
+     missing.
+   - Propshaft serving the host's stylesheet, since PDFs read the compiled
+     stylesheet from it.
+   - An Active Job backend. Publishing a page that uses no host values makes its
+     PDF in a job, and so does `KeystoneUi::Pages.prepare_pdf`.
+
+2. Add the gem to the Gemfile and install it:
+
+   ```ruby
+   gem "keystone_ui-pages"
+   ```
+
+   ```bash
+   bundle install
+   ```
+
+   If the project sources its own gems from somewhere other than RubyGems (a git
+   or path reference), ask the developer which to use rather than choosing.
+
+3. Install the migrations and run them:
+
+   ```bash
+   bin/rails keystone_ui_pages:install:migrations
+   bin/rails active_storage:install
+   bin/rails db:migrate
+   ```
+
+   Skip `active_storage:install` when the app already has the
+   `active_storage_blobs` table. Active Storage also needs a service set in each
+   environment's `config.active_storage.service` and defined in
+   `config/storage.yml`. If the app has none, ask the developer which service
+   production uses before choosing one.
+
+   The engine's migrations create `keystone_ui_pages_pages`,
+   `keystone_ui_pages_versions` and `keystone_ui_pages_pdfs`, and add
+   `undo_history` and `undone_changes` to the pages table. Without those two
+   columns, every edit in the builder fails, since each edit is recorded for
+   Undo and Redo.
+
+4. Mount the engine in `config/routes.rb`:
+
+   ```ruby
+   mount KeystoneUi::Pages::Engine => "/pages"
+   ```
+
+   Ask the developer which path to use; `/pages` is the README's choice and the
+   one the other locals assume. With it:
+
+   - `/pages/manage/pages` is the editor's page list.
+   - `/pages/manage/pages/new` creates a page.
+   - `/pages/manage/pages/:id` is the builder for one page.
+   - `/pages/:slug` is a published page, drawn for visitors.
+
+   Inside the host app, the engine's route helpers are reached through
+   `keystone_ui_pages`, such as `keystone_ui_pages.manage_pages_path`.
+
+5. Prepare the two layouts. Live pages are drawn in the layout named by
+   `KeystoneUi::Pages.layout`, and the page list, the builder and the version
+   history in the one named by `KeystoneUi::Pages.editor_layout`. Both default
+   to `application`. Each layout used must:
+
+   - add `<%= keystone_theme_attributes %>` inside its `<html` tag, so the page
+     follows the viewer's light, dark or custom mode and look;
+   - link the host's stylesheet, which carries keystone_ui-styles, the host's
+     looks and colours, and its own styles;
+   - render `<%= yield :head %>` inside `<head>`, because the builder puts its
+     two script tags, `keystone_ui/react` and `keystone_ui_pages/editor`, there.
+
+   The builder fills the whole window, so the host's own navigation in the
+   editor layout sits under it. The gem's test app uses a separate `editor`
+   layout holding only the head and the page's content. Ask the developer
+   whether to make one or use `application` for both.
+
+6. Write `config/initializers/keystone_ui_pages.rb`. Each setting is described
+   in `keystone_ui-pages-develop`. Ask the developer about each rather than
+   copying this whole block:
+
+   ```ruby
+   require "keystone_ui/pages"
+
+   KeystoneUi::Pages.base_controller = "ApplicationController"
+   KeystoneUi::Pages.owner_method = :current_team
+   KeystoneUi::Pages.view_check_method = :may_view_page?
+   KeystoneUi::Pages.edit_check_method = :may_edit_pages?
+   KeystoneUi::Pages.refusal_method = :refuse_page
+   KeystoneUi::Pages.layout = "application"
+   KeystoneUi::Pages.editor_layout = "editor"
+   ```
+
+   - `base_controller` is a string, read when the engine's controllers load, so
+     it belongs in this file. Set it to the controller that defines the methods
+     the other settings name, normally `ApplicationController`. Its filters,
+     such as a sign-in requirement, then run on every engine request, including
+     published pages.
+   - Without `edit_check_method`, anyone who can reach `/pages/manage` can
+     create, edit and publish pages. Without `view_check_method`, every
+     published page is public. Without `owner_method`, all pages are shared
+     across the whole app. Each of these is a decision about who may see and
+     change what, so put each to the developer.
+   - Host values, catalog changes, `chrome_path` and `pdf_stylesheet` go in the
+     same file once the developer wants them. The develop local carries them.
+
+7. Install Chrome or Chromium wherever the app makes PDFs, including the
+   production server or image. The gem looks for `KeystoneUi::Pages.chrome_path`,
+   then the `CHROME_BIN` environment variable, then these places:
+   `/usr/bin/google-chrome`, `/usr/bin/google-chrome-stable`,
+   `/usr/bin/chromium`, `/usr/bin/chromium-browser`, and the Google Chrome and
+   Chromium apps in `/Applications` on macOS. Ask the developer how the
+   deployment installs it. Without one, everything except PDFs still works.
+
+8. Check the install. Boot the app, open `/pages/manage/pages`, create a page,
+   add an element in the builder, publish it, and open `/pages/<slug>`. The page
+   list shows a PDF link only when Chrome or Chromium was found.
+
+## Conventions
+
+- **Re-run the migration install after upgrading the gem.** A later version can
+  add migrations, as the edit history one was added, and they reach the host
+  only through `bin/rails keystone_ui_pages:install:migrations` followed by
+  `bin/rails db:migrate`.
+- **The engine registers itself with Keystone UI's Tailwind build.** On boot it
+  appends its views, helpers, JavaScript and Ruby files to Keystone UI's
+  Tailwind sources, so the host adds nothing to its Tailwind setup for the
+  engine.
+- **The engine adds `keystone_ui_page` to every host view.** No helper include
+  is needed in the host.
+- **The methods the settings name live on the base controller.** The engine
+  calls them on its own controllers, which inherit from it, so a method defined
+  anywhere else is not found.
+- Drawing pages, making PDFs, host values and the catalog are out of scope here
+  and belong to `keystone_ui-pages-develop`.

data/the_local/interface.yml

@@ -0,0 +1,56 @@
+scope: Pages — building, publishing and printing pages drawn with Keystone UI
+
+install:
+  - bin/rails keystone_ui_pages:install:migrations
+  - bin/rails active_storage:install
+  - mount KeystoneUi::Pages::Engine
+
+develop:
+  - KeystoneUi::Pages.base_controller
+  - KeystoneUi::Pages.owner_method
+  - KeystoneUi::Pages.view_check_method
+  - KeystoneUi::Pages.edit_check_method
+  - KeystoneUi::Pages.refusal_method
+  - KeystoneUi::Pages.layout
+  - KeystoneUi::Pages.editor_layout
+  - KeystoneUi::Pages.chrome_path
+  - KeystoneUi::Pages.pdf_stylesheet
+  - KeystoneUi::Pages::Values.names
+  - KeystoneUi::Pages::Values.chooser
+  - KeystoneUi::Pages::Values.provider
+  - keystone_ui_page
+  - KeystoneUi::Pages.pdf
+  - KeystoneUi::Pages.prepare_pdf
+  - KeystoneUi::Pages.catalog.register
+  - KeystoneUi::Pages.catalog.leave_out
+  - /manage/pages
+
+sources:
+  - README.md
+  - config/routes.rb
+  - lib/keystone_ui/pages.rb
+  - lib/keystone_ui/pages/engine.rb
+  - lib/keystone_ui/pages/values.rb
+  - lib/keystone_ui/pages/catalog.rb
+  - lib/keystone_ui/pages/keystone_elements.rb
+  - lib/keystone_ui/pages/pdfs.rb
+  - lib/keystone_ui/pages/pdf_document.rb
+  - lib/keystone_ui/pages/printer.rb
+  - app/helpers/keystone_ui/pages/host_helper.rb
+  - app/helpers/keystone_ui/pages/drawing_helper.rb
+  - app/helpers/keystone_ui/pages/editor_helper.rb
+  - app/controllers/concerns/keystone_ui/pages/host_checks.rb
+  - app/controllers/keystone_ui/pages/pages_controller.rb
+  - app/controllers/keystone_ui/pages/manage/base_controller.rb
+  - app/controllers/keystone_ui/pages/manage/pages_controller.rb
+  - app/controllers/keystone_ui/pages/manage/lives_controller.rb
+  - app/controllers/keystone_ui/pages/manage/pdfs_controller.rb
+  - app/controllers/keystone_ui/pages/manage/versions_controller.rb
+  - app/controllers/keystone_ui/pages/manage/edit_history_controller.rb
+  - app/models/keystone_ui/pages/page.rb
+  - app/models/keystone_ui/pages/pdf.rb
+  - app/jobs/keystone_ui/pages/pdf_job.rb
+  - db/migrate/20261014120000_create_keystone_ui_pages_pages.rb
+  - db/migrate/20261014120001_create_keystone_ui_pages_versions.rb
+  - db/migrate/20261015130000_create_keystone_ui_pages_pdfs.rb
+  - db/migrate/20261016120000_add_edit_history_to_keystone_ui_pages_pages.rb