Rework extraction app for practitioner use (v3.0.0)

Move logic into testable functions under R/, read only the active input
tab, keep field definitions across tab and field-count changes, validate
and sanitize field labels, extract each item with a new chat and isolate
failures, add typed fields, templates, JSON save/load of field
definitions, generated R and Python code, help dialogs, per-item progress
and status, and keyboard-accessible tabs and dialogs. The model id is set
in one place (R/config.R, overridable with EXTRACTION_MODEL).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

R/_disable_autoload.R

@@ -0,0 +1,2 @@
+# The presence of this file tells Shiny not to source the files in R/ on its own.
+# app.R sources them explicitly, in a fixed order.

R/config.R

@@ -0,0 +1,55 @@
+# Configuration: the single place for the model id and the app limits.
+# Everything a user reads about the model or the limits is generated from these
+# values (see R/help.R and app.R), so the text cannot drift from the behaviour.
+
+# Default model used for extraction. This is the ONLY place a model id may be
+# written. Override it without editing code by setting the environment variable
+# EXTRACTION_MODEL (tests/testthat/test-no-model-literals.R enforces this).
+DEFAULT_EXTRACTION_MODEL = "gpt-6-luna"
+
+# Model id used for every call and every piece of UI text
+get_extraction_model = function() {
+  model = trimws(Sys.getenv("EXTRACTION_MODEL", unset = ""))
+  if (nchar(model) == 0) DEFAULT_EXTRACTION_MODEL else model
+}
+
+# Name of the provider behind ellmer::chat_openai(), used in UI text
+MODEL_PROVIDER = "OpenAI"
+
+# Maximum number of PDF pages (readable or scanned) or images per extraction
+MAX_PAGES_OR_IMAGES = 5
+
+# Maximum size of one uploaded file, in megabytes
+MAX_UPLOAD_MB = 5
+
+# Maximum number of fields per extraction
+MAX_FIELDS = 10
+
+# Number of fields shown when the app starts and when the demo data are loaded
+NUM_EXAMPLE_FIELDS = 2
+
+# Maximum number of characters in a field label
+MAX_LABEL_CHARS = 64
+
+# Column names the app adds to the results, so they cannot be field labels
+RESERVED_LABELS = c("source_id", "status", "status_message")
+
+# Separator used when a "list of text" field is written to the table and the CSV
+LIST_SEPARATOR = "; "
+
+# Zero-argument function returning the API key (the form ellmer expects)
+get_openai_api_key = function() {
+  Sys.getenv("OPENAI_API_KEY")
+}
+
+# All values the help text and the code snippets are generated from
+app_config = function() {
+  list(
+    model = get_extraction_model(),
+    provider = MODEL_PROVIDER,
+    max_pages_or_images = MAX_PAGES_OR_IMAGES,
+    max_upload_mb = MAX_UPLOAD_MB,
+    max_fields = MAX_FIELDS,
+    list_separator = LIST_SEPARATOR
+  )
+}

R/extraction.R

@@ -0,0 +1,156 @@
+# Extraction: one model call per item, with failures isolated per item, and
+# assembly of the results into a data frame.
+
+# TRUE when the app has an API key to call the model with
+api_key_available = function() {
+  nchar(get_openai_api_key()) > 0
+}
+
+# Returns a zero-argument function that creates a new chat each time it is
+# called. Tests pass their own factory to avoid calling the model.
+make_chat_factory = function(model = get_extraction_model()) {
+  function() {
+    ellmer::chat_openai(model = model, credentials = get_openai_api_key)
+  }
+}
+
+# What is sent to the model for one item
+item_content = function(item) {
+  if (identical(item$kind, "image")) {
+    # The type is read from the file content, so a JPEG saved as .png still works.
+    # Resizing needs the magick package.
+    mime = detect_mime(item$path)
+    ellmer::content_image_file(
+      item$path,
+      content_type = if (is.na(mime)) "auto" else mime,
+      resize = "high"
+    )
+  } else {
+    item$text
+  }
+}
+
+# One-line error message suitable for the results table
+clean_error_message = function(e, max_chars = 300) {
+  message = gsub("\\s+", " ", trimws(conditionMessage(e)))
+  if (nchar(message) == 0) message = "Unknown error."
+  if (nchar(message) > max_chars) message = paste0(substr(message, 1, max_chars), "...")
+  message
+}
+
+# Extract one item with a new chat, so that no earlier item is in its context
+extract_item = function(item, type, chat_factory, content_fn = item_content) {
+  chat = chat_factory()
+  chat$chat_structured(content_fn(item), type = type)
+}
+
+# Extract every item. A failure on one item is recorded and the loop goes on.
+#
+# on_progress  optional function(i, n, item) called before item i is processed
+# Returns a list with one entry per item:
+#   list(source_id, status = "ok" or "failed", message, data)
+extract_items = function(items, type, chat_factory, on_progress = NULL,
+                         content_fn = item_content) {
+  n = length(items)
+  lapply(seq_along(items), function(i) {
+    item = items[[i]]
+    if (is.function(on_progress)) on_progress(i, n, item)
+    tryCatch({
+      data = extract_item(item, type, chat_factory, content_fn = content_fn)
+      if (!is.list(data)) stop("The model returned no structured data.")
+      list(source_id = item$source_id, status = "ok", message = "", data = data)
+    }, error = function(e) {
+      list(
+        source_id = item$source_id,
+        status = "failed",
+        message = clean_error_message(e),
+        data = NULL
+      )
+    })
+  })
+}
+
+# Convert one returned value to a single cell of the given field type.
+# A missing value becomes NA; a list of text is joined with the separator.
+coerce_value = function(value, type, list_separator = LIST_SEPARATOR) {
+  flat = unlist(value, use.names = FALSE)
+  missing_value = is.null(flat) || length(flat) == 0 || all(is.na(flat))
+
+  if (type == "number") {
+    if (missing_value) return(NA_real_)
+    return(suppressWarnings(as.numeric(flat[1])))
+  }
+  if (type == "yes_no") {
+    if (missing_value) return(NA)
+    if (is.logical(flat)) return(flat[1])
+    answer = tolower(trimws(as.character(flat[1])))
+    if (answer %in% c("true", "yes", "y", "1")) return(TRUE)
+    if (answer %in% c("false", "no", "n", "0")) return(FALSE)
+    return(NA)
+  }
+  if (missing_value) {
+    # An empty list that was returned is an empty cell, not a missing value
+    if (type == "list" && !is.null(value) && length(value) == 0) return("")
+    return(NA_character_)
+  }
+  flat = as.character(flat[!is.na(flat)])
+  paste(flat, collapse = list_separator)
+}
+
+# Combine the per-item results into one data frame with the columns
+# source_id, one column per field, status and status_message.
+# Items that failed, and fields the model did not return, are NA.
+assemble_results = function(results, fields, list_separator = LIST_SEPARATOR) {
+  columns = list(
+    source_id = vapply(results, function(r) as.character(r$source_id), character(1))
+  )
+  for (field in fields) {
+    cells = lapply(results, function(r) {
+      value = if (identical(r$status, "ok")) r$data[[field$label]] else NULL
+      coerce_value(value, field$type, list_separator = list_separator)
+    })
+    columns[[field$label]] = switch(
+      field$type,
+      number = vapply(cells, as.numeric, numeric(1)),
+      yes_no = vapply(cells, as.logical, logical(1)),
+      vapply(cells, as.character, character(1))
+    )
+  }
+  columns$status = vapply(results, function(r) as.character(r$status), character(1))
+  columns$status_message = vapply(results, function(r) as.character(r$message), character(1))
+  as.data.frame(columns, stringsAsFactors = FALSE, check.names = FALSE)
+}
+
+# Version of the results for on-screen display: every column as text, with
+# empty cells for missing values and numbers printed without padding zeros.
+# The CSV download uses the typed table, not this one.
+display_table = function(results_table) {
+  shown = lapply(results_table, function(column) {
+    text = if (is.numeric(column)) {
+      vapply(column, function(x) {
+        if (is.na(x)) NA_character_ else format(x, scientific = FALSE, drop0trailing = TRUE, trim = TRUE)
+      }, character(1))
+    } else {
+      as.character(column)
+    }
+    text[is.na(text)] = ""
+    text
+  })
+  as.data.frame(shown, stringsAsFactors = FALSE, check.names = FALSE)
+}
+
+# One line describing the outcome, for example
+# "7 of 8 items extracted; 1 failed (source_id: 3)."
+summarize_results = function(results_table) {
+  n = nrow(results_table)
+  failed = results_table$source_id[results_table$status != "ok"]
+  n_ok = n - length(failed)
+  item_word = if (n == 1) "item" else "items"
+  if (length(failed) == 0) {
+    return(sprintf("%d of %d %s extracted.", n_ok, n, item_word))
+  }
+  sprintf(
+    "%d of %d %s extracted; %d failed (source_id: %s).",
+    n_ok, n, item_word, length(failed), paste(failed, collapse = ", ")
+  )
+}

R/fields.R

@@ -0,0 +1,303 @@
+# Field definitions: creation, validation, sanitizing, JSON import/export,
+# templates, and conversion to an ellmer type.
+#
+# A field is a list with three character elements:
+#   label        column name in the results (and property name in the schema)
+#   description  instruction the model receives for the field
+#   type         one of names(FIELD_TYPES)
+
+# Field types offered in the UI (value = label shown to the user)
+FIELD_TYPES = c(
+  text = "Text",
+  number = "Number",
+  yes_no = "Yes / No",
+  list = "List of text"
+)
+
+# Name used inside saved field-definition files
+FIELDS_FILE_FORMAT = "structured_text_extraction_fields"
+
+new_field = function(label = "", description = "", type = "text") {
+  list(
+    label = as.character(label),
+    description = as.character(description),
+    type = as.character(type)
+  )
+}
+
+# First "field_<k>" label that is not already used
+next_default_label = function(existing_labels) {
+  k = 1
+  while (paste0("field_", k) %in% existing_labels) k = k + 1
+  paste0("field_", k)
+}
+
+# Grow or shrink a list of fields to n entries, keeping the existing entries
+resize_fields = function(fields, n) {
+  n = as.integer(n)
+  if (is.na(n) || n < 1) return(fields)
+  if (length(fields) > n) return(fields[seq_len(n)])
+  while (length(fields) < n) {
+    labels = vapply(fields, function(f) f$label, character(1))
+    # Prefer the label that matches the field's position
+    label = paste0("field_", length(fields) + 1)
+    if (label %in% labels) label = next_default_label(labels)
+    fields[[length(fields) + 1]] = new_field(label)
+  }
+  fields
+}
+
+# Bring a user-supplied number of fields into the allowed range.
+# Returns NA when the value is not a usable number.
+clamp_num_fields = function(n, max_fields = MAX_FIELDS) {
+  n = suppressWarnings(as.numeric(n))
+  if (length(n) != 1 || is.na(n)) return(NA_integer_)
+  as.integer(min(max(round(n), 1), max_fields))
+}
+
+# Ids of the three inputs of field i. The generation number changes every
+# time the app rebuilds the field inputs, so values typed into an earlier set
+# of inputs can never overwrite a newly loaded template or file.
+field_input_ids = function(gen, i) {
+  list(
+    label = paste0("field_label_", gen, "_", i),
+    description = paste0("field_desc_", gen, "_", i),
+    type = paste0("field_type_", gen, "_", i)
+  )
+}
+
+# Overlay what the user has typed on the stored field definitions.
+# get_input is a function(id) returning the input value or NULL.
+merge_field_inputs = function(fields, get_input, gen = 0) {
+  lapply(seq_along(fields), function(i) {
+    ids = field_input_ids(gen, i)
+    field = fields[[i]]
+    for (part in names(ids)) {
+      value = get_input(ids[[part]])
+      if (!is.null(value) && length(value) == 1 && !is.na(value)) {
+        field[[part]] = as.character(value)
+      }
+    }
+    field
+  })
+}
+
+# Make a label safe to use as a JSON property name and a column name:
+# letters, digits and underscores only, not starting with a digit.
+sanitize_label = function(label, max_chars = MAX_LABEL_CHARS) {
+  label = trimws(as.character(label))
+  label = gsub("[^A-Za-z0-9_]+", "_", label)
+  label = gsub("^_+|_+$", "", label)
+  if (nchar(label) > 0 && grepl("^[0-9]", label)) label = paste0("field_", label)
+  substr(label, 1, max_chars)
+}
+
+# Check a list of fields. Returns
+#   ok      TRUE when the fields can be used for an extraction
+#   errors  problems that block the extraction
+#   notes   things the user should know that do not block it
+#   fields  the fields with sanitized labels and trimmed descriptions
+validate_fields = function(fields, max_fields = MAX_FIELDS, reserved = RESERVED_LABELS) {
+  errors = character(0)
+  notes = character(0)
+
+  if (!is.list(fields) || length(fields) == 0) {
+    return(list(ok = FALSE, errors = "Define at least one field.", notes = notes, fields = list()))
+  }
+  if (length(fields) > max_fields) {
+    errors = c(errors, sprintf(
+      "You defined %d fields. The maximum is %d.", length(fields), max_fields
+    ))
+  }
+
+  clean = list()
+  for (i in seq_along(fields)) {
+    field = fields[[i]]
+    raw_label = if (is.null(field$label)) "" else trimws(as.character(field$label)[1])
+    if (is.na(raw_label)) raw_label = ""
+    description = if (is.null(field$description)) "" else trimws(as.character(field$description)[1])
+    if (is.na(description)) description = ""
+    type = if (is.null(field$type)) "text" else as.character(field$type)[1]
+
+    if (nchar(raw_label) == 0) {
+      errors = c(errors, sprintf("Field %d has no label.", i))
+      next
+    }
+    label = sanitize_label(raw_label)
+    if (nchar(label) == 0) {
+      errors = c(errors, sprintf(
+        "The label of field %d ('%s') has no letters or digits.", i, raw_label
+      ))
+      next
+    }
+    if (label != raw_label) {
+      notes = c(notes, sprintf(
+        "The label of field %d ('%s') was changed to '%s' (letters, digits and underscores only).",
+        i, raw_label, label
+      ))
+    }
+    if (tolower(label) %in% tolower(reserved)) {
+      errors = c(errors, sprintf(
+        "The label '%s' (field %d) is used by the app for its own column. Choose another label.",
+        label, i
+      ))
+    }
+    if (is.na(type) || !(type %in% names(FIELD_TYPES))) {
+      errors = c(errors, sprintf(
+        "Field %d has an unknown type ('%s'). Allowed types: %s.",
+        i, type, paste(names(FIELD_TYPES), collapse = ", ")
+      ))
+      type = "text"
+    }
+    if (nchar(description) == 0) {
+      notes = c(notes, sprintf(
+        "Field %d ('%s') has no description, so the model only sees its label.", i, label
+      ))
+    }
+    clean[[length(clean) + 1]] = new_field(label, description, type)
+  }
+
+  labels = tolower(vapply(clean, function(f) f$label, character(1)))
+  duplicated_labels = unique(labels[duplicated(labels)])
+  for (dup in duplicated_labels) {
+    errors = c(errors, sprintf(
+      "The label '%s' is used by more than one field. Labels must be unique.", dup
+    ))
+  }
+
+  list(ok = length(errors) == 0, errors = errors, notes = notes, fields = clean)
+}
+
+# ellmer type for one field. All fields are optional so that the model can
+# return nothing when a document does not contain the information.
+field_to_type = function(field) {
+  description = if (nchar(field$description) > 0) field$description else NULL
+  switch(
+    field$type,
+    text = ellmer::type_string(description = description, required = FALSE),
+    number = ellmer::type_number(description = description, required = FALSE),
+    yes_no = ellmer::type_boolean(description = description, required = FALSE),
+    list = ellmer::type_array(
+      items = ellmer::type_string(),
+      description = description,
+      required = FALSE
+    ),
+    stop("Unknown field type: ", field$type)
+  )
+}
+
+# Build the ellmer type_object for a list of validated fields
+build_type_object = function(fields) {
+  if (length(fields) == 0) stop("At least one field is required.")
+  type_list = lapply(fields, field_to_type)
+  names(type_list) = vapply(fields, function(f) f$label, character(1))
+  do.call(ellmer::type_object, type_list)
+}
+
+# ---- JSON export and import -------------------------------------------------
+
+fields_to_json = function(fields) {
+  payload = list(
+    format = FIELDS_FILE_FORMAT,
+    version = 1,
+    fields = lapply(fields, function(f) {
+      list(label = f$label, description = f$description, type = f$type)
+    })
+  )
+  as.character(jsonlite::toJSON(payload, auto_unbox = TRUE, pretty = TRUE))
+}
+
+# Parse field definitions from JSON text. Accepts the format written by
+# fields_to_json(), a template file, or a bare array of fields.
+# Returns list(ok, error, fields).
+fields_from_json = function(json_text, max_fields = MAX_FIELDS) {
+  fail = function(message) list(ok = FALSE, error = message, fields = list())
+
+  json_text = paste(json_text, collapse = "\n")
+  if (!validUTF8(json_text)) return(fail("The file is not a text file with JSON content."))
+  if (nchar(trimws(json_text)) == 0) return(fail("The file is empty."))
+
+  parsed = tryCatch(
+    jsonlite::fromJSON(json_text, simplifyVector = FALSE),
+    error = function(e) NULL
+  )
+  if (is.null(parsed)) return(fail("The file is not valid JSON."))
+
+  raw_fields = if (is.list(parsed) && !is.null(names(parsed))) parsed$fields else parsed
+  if (!is.list(raw_fields) || length(raw_fields) == 0 || !is.null(names(raw_fields))) {
+    return(fail("The file does not contain a list of fields (expected a \"fields\" array)."))
+  }
+
+  is_text = function(x) is.character(x) && length(x) == 1 && !is.na(x)
+  fields = list()
+  for (i in seq_along(raw_fields)) {
+    entry = raw_fields[[i]]
+    if (!is.list(entry) || is.null(names(entry))) {
+      return(fail(sprintf("Field %d is not an object with a label, description and type.", i)))
+    }
+    if (!is_text(entry$label)) {
+      return(fail(sprintf("Field %d has no text label.", i)))
+    }
+    description = if (is.null(entry$description)) "" else entry$description
+    if (!is_text(description)) {
+      return(fail(sprintf("The description of field %d is not text.", i)))
+    }
+    type = if (is.null(entry$type)) "text" else entry$type
+    if (!is_text(type) || !(type %in% names(FIELD_TYPES))) {
+      return(fail(sprintf(
+        "Field %d has an unknown type. Allowed types: %s.",
+        i, paste(names(FIELD_TYPES), collapse = ", ")
+      )))
+    }
+    fields[[i]] = new_field(entry$label, description, type)
+  }
+
+  checked = validate_fields(fields, max_fields = max_fields)
+  if (!checked$ok) return(fail(paste(checked$errors, collapse = " ")))
+
+  list(ok = TRUE, error = "", fields = checked$fields)
+}
+
+read_fields_json = function(path, max_fields = MAX_FIELDS) {
+  json_text = tryCatch(
+    suppressWarnings(readLines(path, warn = FALSE, encoding = "UTF-8")),
+    error = function(e) NULL
+  )
+  if (is.null(json_text)) {
+    return(list(ok = FALSE, error = "The file could not be read.", fields = list()))
+  }
+  fields_from_json(json_text, max_fields = max_fields)
+}
+
+# ---- Templates --------------------------------------------------------------
+
+# Read the field templates (one JSON file each) from a directory.
+# Returns a list named by template id, in the order given by each file's
+# "order" value.
+load_templates = function(dir = file.path("config", "templates")) {
+  files = sort(list.files(dir, pattern = "\\.json$", full.names = TRUE))
+  templates = lapply(files, function(path) {
+    raw = jsonlite::fromJSON(
+      paste(readLines(path, warn = FALSE, encoding = "UTF-8"), collapse = "\n"),
+      simplifyVector = FALSE
+    )
+    list(
+      id = raw$id,
+      name = raw$name,
+      description = raw$description,
+      order = if (is.null(raw$order)) Inf else raw$order,
+      fields = lapply(raw$fields, function(f) new_field(f$label, f$description, f$type))
+    )
+  })
+  if (length(templates) == 0) return(list())
+  templates = templates[order(vapply(templates, function(t) as.numeric(t$order), numeric(1)))]
+  names(templates) = vapply(templates, function(t) t$id, character(1))
+  templates
+}
+
+# Choices for the template selector (name shown = template id)
+template_choices = function(templates) {
+  ids = names(templates)
+  names(ids) = vapply(templates, function(t) t$name, character(1))
+  ids
+}

R/help.R

@@ -0,0 +1,112 @@
+# Help text for the "?" buttons. Every number and name in the text comes from
+# app_config(), the same values that drive the app's behaviour.
+
+HELP_TOPICS = c("source", "fields", "extract", "results")
+
+# Returns list(title, paragraphs) for one help topic
+help_content = function(topic, cfg = app_config()) {
+  reserved = paste(RESERVED_LABELS, collapse = ", ")
+  type_names = paste(tolower(FIELD_TYPES), collapse = ", ")
+
+  switch(
+    topic,
+    source = list(
+      title = "Input source",
+      paragraphs = c(
+        "Choose one input source. Only the source on the tab that is open when you click Extract Data is used. Content loaded on the other tabs is kept, but it is not sent.",
+        "Demo Data and Paste Text: the text is split into items at blank lines, and each item is sent to the model as a separate request. Text File: a .txt or .md file is split in the same way. A .csv file gives one item per row of its first column, and its first row is treated as a header.",
+        sprintf(
+          "Readable PDF: the text of the first %d pages is read from the file and sent as a single item. Scanned PDF: each of the first %d pages is converted to an image and sent as one item. Upload Images: each image is one item, up to %d images.",
+          cfg$max_pages_or_images, cfg$max_pages_or_images, cfg$max_pages_or_images
+        ),
+        sprintf("Each uploaded file can be at most %d MB.", cfg$max_upload_mb),
+        sprintf(
+          "When you click Extract Data, the content of the active source and your field definitions are sent to the %s model %s. Do not submit confidential or proprietary records to this hosted app.",
+          cfg$provider, cfg$model
+        )
+      )
+    ),
+    fields = list(
+      title = "Field definitions",
+      paragraphs = c(
+        sprintf(
+          "Each field becomes one column of the results. You can define up to %d fields.",
+          cfg$max_fields
+        ),
+        sprintf(
+          "The label is the column name. Labels may contain letters, digits and underscores, and any other character is replaced with an underscore. Labels must be unique and cannot be one of the names the app uses for its own columns (%s).",
+          reserved
+        ),
+        "The description is the instruction the model receives for that field. The app adds no instructions of its own, so your descriptions are the prompt. State what to return, in what format, and what to return when the document does not contain the information.",
+        sprintf(
+          "The type sets the data type of the column (%s). The values of a list are joined with '%s' in the table and in the CSV file.",
+          type_names, cfg$list_separator
+        ),
+        "A template fills the fields with a starting set for a common quality document, and you can edit the fields afterwards. Save fields downloads the current definitions as a JSON file. Load fields restores them from such a file."
+      )
+    ),
+    extract = list(
+      title = "Extract Data",
+      paragraphs = c(
+        sprintf(
+          "Extract Data sends one request per item to the %s model %s. A request contains the item (text or an image) and the field definitions (labels, descriptions and types), which the model must follow as its output structure.",
+          cfg$provider, cfg$model
+        ),
+        "Each item is sent in a new conversation, so one item cannot influence the values extracted from another.",
+        "Items are processed one after another, and a progress bar shows the item being processed. If an item fails, the remaining items are still processed and the failure is recorded in the results.",
+        sprintf(
+          "Limits per run: %d PDF pages or images, %d fields, and %d MB per uploaded file.",
+          cfg$max_pages_or_images, cfg$max_fields, cfg$max_upload_mb
+        ),
+        "The model can return different values when the same item is submitted again."
+      )
+    ),
+    results = list(
+      title = "Results",
+      paragraphs = c(
+        "The table has one row per item. The source_id column identifies the item (its position in the text, or the image or page number). The status column is ok or failed, and status_message gives the reason for a failure.",
+        "An empty cell means that the model returned no value for that field.",
+        sprintf(
+          "Check the results against the source documents before you use them. The %s model %s can misread a document or return a value that the document does not contain. A status of ok means that the request completed. It does not mean that the values are correct.",
+          cfg$provider, cfg$model
+        ),
+        "Download as CSV saves the table with the source_id, status and status_message columns. Reproduce in code shows R and Python code that runs the same extraction, with your fields and the same model, on your own data."
+      )
+    ),
+    stop("Unknown help topic: ", topic)
+  )
+}
+
+# Small "?" button that opens the help for a topic
+help_button = function(topic) {
+  content = help_content(topic)
+  shiny::actionButton(
+    paste0("help_", topic),
+    "?",
+    class = "help-btn",
+    title = paste("How this works:", content$title),
+    `aria-label` = paste("Help:", content$title),
+    `aria-haspopup` = "dialog"
+  )
+}
+
+# Modal dialog with the help for a topic
+help_modal = function(topic, cfg = app_config()) {
+  content = help_content(topic, cfg)
+  shiny::modalDialog(
+    title = content$title,
+    lapply(content$paragraphs, shiny::tags$p),
+    easyClose = TRUE,
+    footer = shiny::modalButton("Close")
+  )
+}
+
+# Sentences about the limits, used in the page text
+limit_note = function(kind, max_items = MAX_PAGES_OR_IMAGES) {
+  switch(
+    kind,
+    pages = sprintf(" Free app limit: only the first %d pages will be processed.", max_items),
+    images = sprintf(" Free app limit: a maximum of %d images will be processed.", max_items),
+    stop("Unknown limit kind: ", kind)
+  )
+}

R/snippets.R

@@ -0,0 +1,128 @@
+# "Reproduce in code": R (ellmer) and Python (chatlas) snippets generated from
+# the current field definitions and the configured model.
+
+# Names that cannot be used as attribute names of a Python (pydantic) class
+PYTHON_RESERVED_NAMES = c(
+  "False", "None", "True", "and", "as", "assert", "async", "await", "break",
+  "class", "continue", "def", "del", "elif", "else", "except", "finally",
+  "for", "from", "global", "if", "import", "in", "is", "lambda", "nonlocal",
+  "not", "or", "pass", "raise", "return", "try", "while", "with", "yield",
+  "copy", "dict", "json", "schema", "validate", "construct"
+)
+
+# R string literal
+r_string = function(x) {
+  encodeString(enc2utf8(x), quote = "\"")
+}
+
+# Python string literal (a JSON string is a valid Python string)
+python_string = function(x) {
+  as.character(jsonlite::toJSON(enc2utf8(x), auto_unbox = TRUE))
+}
+
+r_field_line = function(field) {
+  description = r_string(field$description)
+  type_call = switch(
+    field$type,
+    text = sprintf("type_string(%s, required = FALSE)", description),
+    number = sprintf("type_number(%s, required = FALSE)", description),
+    yes_no = sprintf("type_boolean(%s, required = FALSE)", description),
+    list = sprintf(
+      "type_array(items = type_string(), description = %s, required = FALSE)",
+      description
+    ),
+    stop("Unknown field type: ", field$type)
+  )
+  sprintf("  %s = %s", field$label, type_call)
+}
+
+# R code that runs the same extraction with ellmer
+r_snippet = function(fields, model = get_extraction_model()) {
+  field_lines = paste(vapply(fields, r_field_line, character(1)), collapse = ",\n")
+  paste(c(
+    "# Structured extraction with ellmer (https://ellmer.tidyverse.org/)",
+    "# install.packages(\"ellmer\")",
+    "# The API key is read from the OPENAI_API_KEY environment variable.",
+    "library(ellmer)",
+    "",
+    "# One entry per field. The description is the instruction the model receives.",
+    "extraction_type = type_object(",
+    field_lines,
+    ")",
+    "",
+    "extract_one = function(content) {",
+    "  # A new chat per document keeps earlier documents out of the context",
+    sprintf("  chat = chat_openai(model = %s)", r_string(model)),
+    "  chat$chat_structured(content, type = extraction_type)",
+    "}",
+    "",
+    "# One document given as text",
+    "result = extract_one(\"Paste the text of one document here.\")",
+    "str(result)",
+    "",
+    "# An image or a PDF file",
+    "# result = extract_one(content_image_file(\"scan.png\", resize = \"high\"))",
+    "# result = extract_one(content_pdf_file(\"report.pdf\"))",
+    "",
+    "# Several documents, one call each",
+    "# documents = c(\"first document\", \"second document\")",
+    "# results = lapply(documents, extract_one)"
+  ), collapse = "\n")
+}
+
+python_field_line = function(field) {
+  annotation = switch(
+    field$type,
+    text = "str | None",
+    number = "float | None",
+    yes_no = "bool | None",
+    list = "list[str] | None",
+    stop("Unknown field type: ", field$type)
+  )
+  name = field$label
+  comment = ""
+  if (name %in% PYTHON_RESERVED_NAMES) {
+    comment = sprintf("  # '%s' cannot be used as a name in Python", name)
+    name = paste0(name, "_")
+  }
+  sprintf(
+    "    %s: %s = Field(description=%s)%s",
+    name, annotation, python_string(field$description), comment
+  )
+}
+
+# Python code that runs the same extraction with chatlas
+python_snippet = function(fields, model = get_extraction_model()) {
+  field_lines = paste(vapply(fields, python_field_line, character(1)), collapse = "\n")
+  paste(c(
+    "# Structured extraction with chatlas (https://posit-dev.github.io/chatlas/)",
+    "# pip install chatlas",
+    "# The API key is read from the OPENAI_API_KEY environment variable.",
+    "from chatlas import ChatOpenAI, content_image_file, content_pdf_file",
+    "from pydantic import BaseModel, Field",
+    "",
+    "",
+    "# One attribute per field. The description is the instruction the model receives.",
+    "class Extraction(BaseModel):",
+    field_lines,
+    "",
+    "",
+    "def extract_one(content):",
+    "    # A new chat per document keeps earlier documents out of the context",
+    sprintf("    chat = ChatOpenAI(model=%s)", python_string(model)),
+    "    return chat.chat_structured(content, data_model=Extraction)",
+    "",
+    "",
+    "# One document given as text",
+    "result = extract_one(\"Paste the text of one document here.\")",
+    "print(result.model_dump())",
+    "",
+    "# An image or a PDF file",
+    "# result = extract_one(content_image_file(\"scan.png\", resize=\"high\"))",
+    "# result = extract_one(content_pdf_file(\"report.pdf\"))",
+    "",
+    "# Several documents, one call each",
+    "# documents = [\"first document\", \"second document\"]",
+    "# results = [extract_one(d) for d in documents]"
+  ), collapse = "\n")
+}

R/sources.R

@@ -0,0 +1,185 @@
+# Input sources: reading uploaded files and resolving the active tab into the
+# list of items that will be sent to the model.
+
+# Ids of the input tabs, in display order
+INPUT_METHODS = c("demo", "paste", "textfile", "pdf", "scanned", "image")
+
+# Names of the input tabs as shown to the user
+INPUT_METHOD_LABELS = c(
+  demo = "Demo Data",
+  paste = "Paste Text",
+  textfile = "Text File",
+  pdf = "Readable PDF",
+  scanned = "Scanned PDF",
+  image = "Upload Images"
+)
+
+# Two NHTSA recall summaries used by the Demo Data tab
+DEMO_TEXT = "Ford Motor Company (Ford) is recalling certain 2021-2022 Bronco vehicles equipped with rearview camera systems and 8-inch screen displays. The rearview camera image may still be displayed after a backing event has ended. As such, these vehicles fail to comply with the requirements of Federal Motor Vehicle Safety Standard number 111, \"Rear Visibility.\"\n\nHonda (American Honda Motor Co.) is recalling certain 2022-2025 Acura MDX Type-S, 2023-2025 Honda Pilot, and 2021-2025 Acura TLX Type-S vehicles. A software error in the fuel injection electronic control unit (FI-ECU) may cause an engine stall or a loss of power."
+
+# Split text into items at blank lines
+split_text_blocks = function(text) {
+  if (is.null(text) || length(text) == 0) return(character(0))
+  text = paste(text, collapse = "\n")
+  text = gsub("\r\n?", "\n", text)
+  blocks = trimws(unlist(strsplit(text, "\n[ \t]*\n+")))
+  blocks[!is.na(blocks) & nchar(blocks) > 0]
+}
+
+# Shorten text for an on-screen preview
+preview_text = function(text, max_chars = 500) {
+  text = paste(text, collapse = "\n\n")
+  if (nchar(text) > max_chars) paste0(substr(text, 1, max_chars), "...") else text
+}
+
+# Read an uploaded text file into a character vector of items.
+# .csv: one item per row of the first column (first row is a header).
+# .txt and .md: items are separated by blank lines.
+read_text_file_items = function(path, name = path) {
+  file_ext = tolower(tools::file_ext(name))
+  if (file_ext == "csv") {
+    csv_data = utils::read.csv(path, header = TRUE, stringsAsFactors = FALSE)
+    if (ncol(csv_data) < 1) return(character(0))
+    items = trimws(as.character(csv_data[[1]]))
+    items[!is.na(items) & nchar(items) > 0]
+  } else {
+    split_text_blocks(readLines(path, warn = FALSE, encoding = "UTF-8"))
+  }
+}
+
+# Extract the text of the first max_pages pages of a machine-readable PDF.
+# Returns list(text, total_pages, used_pages); the text is one item.
+read_pdf_text = function(path, max_pages = MAX_PAGES_OR_IMAGES) {
+  pages = pdftools::pdf_text(path)
+  total_pages = length(pages)
+  pages = pages[seq_len(min(total_pages, max_pages))]
+  combined_text = paste(pages, collapse = "\n\n")
+  combined_text = trimws(gsub("\\s+", " ", combined_text))
+  list(text = combined_text, total_pages = total_pages, used_pages = length(pages))
+}
+
+# Convert the first max_pages pages of a PDF to PNG files.
+# Returns list(paths, total_pages).
+render_pdf_pages = function(path, max_pages = MAX_PAGES_OR_IMAGES, dpi = 150) {
+  total_pages = pdftools::pdf_info(path)$pages
+  n_pages = min(total_pages, max_pages)
+  out_files = vapply(
+    seq_len(n_pages),
+    function(i) tempfile(pattern = paste0("page_", i, "_"), fileext = ".png"),
+    character(1)
+  )
+  pdftools::pdf_convert(
+    path,
+    format = "png",
+    pages = seq_len(n_pages),
+    filenames = out_files,
+    dpi = dpi,
+    verbose = FALSE
+  )
+  list(paths = out_files, total_pages = total_pages)
+}
+
+# MIME type of an image, from its first bytes and, failing that, from the
+# extension of its name. Returns NA for anything that is not a supported image.
+detect_mime = function(path, name = path) {
+  header = tryCatch(
+    suppressWarnings(readBin(path, what = "raw", n = 12)),
+    error = function(e) raw(0)
+  )
+  starts_with = function(bytes) {
+    length(header) >= length(bytes) && all(header[seq_along(bytes)] == as.raw(bytes))
+  }
+  if (starts_with(c(0x89, 0x50, 0x4E, 0x47))) return("image/png")
+  if (starts_with(c(0xFF, 0xD8, 0xFF))) return("image/jpeg")
+  if (starts_with(c(0x47, 0x49, 0x46, 0x38))) return("image/gif")
+  if (starts_with(c(0x52, 0x49, 0x46, 0x46)) && length(header) >= 12 &&
+      all(header[9:12] == as.raw(c(0x57, 0x45, 0x42, 0x50)))) {
+    return("image/webp")
+  }
+  switch(
+    tolower(tools::file_ext(name)),
+    png = "image/png",
+    jpg = ,
+    jpeg = "image/jpeg",
+    gif = "image/gif",
+    webp = "image/webp",
+    NA_character_
+  )
+}
+
+# Turn the active input tab into the items to extract from.
+#
+# method   id of the active tab (one of INPUT_METHODS)
+# sources  list with what each tab currently holds:
+#            demo      text loaded by the demo button
+#            paste     text in the paste box
+#            textfile  character vector of items from the uploaded text file
+#            pdf       text extracted from the readable PDF
+#            scanned   paths of the page images of the scanned PDF
+#            image     paths of the uploaded images
+#
+# Only sources[[method]] is read, so content loaded on another tab can never
+# be extracted by mistake. Returns list(ok, error, items); each item is
+# list(source_id, kind = "text" or "image", text or path).
+resolve_source_items = function(method, sources, max_items = MAX_PAGES_OR_IMAGES) {
+  fail = function(message) list(ok = FALSE, error = message, items = list())
+  field_reminder = " Also check that the field labels and descriptions match your data."
+
+  text_items = function(blocks) {
+    lapply(seq_along(blocks), function(i) {
+      list(source_id = as.character(i), kind = "text", text = blocks[[i]])
+    })
+  }
+  image_items = function(paths, prefix) {
+    paths = paths[seq_len(min(length(paths), max_items))]
+    lapply(seq_along(paths), function(i) {
+      list(source_id = paste(prefix, i), kind = "image", path = paths[[i]])
+    })
+  }
+
+  if (is.null(method) || length(method) != 1 || !(method %in% INPUT_METHODS)) {
+    return(fail("Unknown input source. Select one of the input tabs."))
+  }
+
+  if (method == "demo") {
+    blocks = split_text_blocks(sources$demo)
+    if (length(blocks) == 0) {
+      return(fail("Please click 'Load Demo Data' first to load the sample data."))
+    }
+    items = text_items(blocks)
+  } else if (method == "paste") {
+    blocks = split_text_blocks(sources$paste)
+    if (length(blocks) == 0) {
+      return(fail(paste0("Please paste your text content in the text area.", field_reminder)))
+    }
+    items = text_items(blocks)
+  } else if (method == "textfile") {
+    blocks = sources$textfile
+    blocks = blocks[!is.na(blocks) & nchar(trimws(blocks)) > 0]
+    if (length(blocks) == 0) {
+      return(fail(paste0("Please upload a text file (.txt, .csv, or .md) first.", field_reminder)))
+    }
+    items = text_items(blocks)
+  } else if (method == "pdf") {
+    text = sources$pdf
+    if (is.null(text) || length(text) == 0 || nchar(trimws(text[1])) == 0) {
+      return(fail(paste0("Please upload a readable PDF file first.", field_reminder)))
+    }
+    # The whole document (up to the page limit) is one item
+    items = text_items(trimws(text[1]))
+  } else if (method == "image") {
+    paths = sources$image
+    if (is.null(paths) || length(paths) == 0) {
+      return(fail(paste0("Please upload one or more image files first.", field_reminder)))
+    }
+    items = image_items(paths, "Image")
+  } else {
+    paths = sources$scanned
+    if (is.null(paths) || length(paths) == 0) {
+      return(fail(paste0("Please upload a scanned PDF file first.", field_reminder)))
+    }
+    items = image_items(paths, "Page")
+  }
+
+  list(ok = TRUE, error = "", items = items)
+}

app.R

@@ -1,19 +1,69 @@
 library(shiny)
 library(ellmer)
-library(purrr)
 library(pdftools)
 library(magick)
 library(base64enc)
+library(jsonlite)
 
-# Maximum pages for image-based extraction (free app limit)
-MAX_IMAGE_PAGES = 5
+# App logic lives in R/ and is sourced here in a fixed order
+# (R/_disable_autoload.R stops Shiny from sourcing the directory a second time)
+for (r_file in c("config.R", "fields.R", "sources.R", "extraction.R", "snippets.R", "help.R")) {
+  source(file.path("R", r_file), local = TRUE)
+}
+
+# Uploads larger than this are rejected by Shiny
+options(shiny.maxRequestSize = MAX_UPLOAD_MB * 1024^2)
+
+# Model used for every call and named in every piece of UI text
+EXTRACTION_MODEL = get_extraction_model()
 
-num_example_fields = 2
+APP_VERSION = "Version 3.0.0 | October 2026"
 
+PAPER_TITLE = "What Quality Engineers Need to Know About Generative AI: Structured Data Extraction"
 
+# Field templates (one JSON file each in config/templates)
+FIELD_TEMPLATES = load_templates(file.path("config", "templates"))
+
+# Fields shown at start-up and loaded with the demo data
+demo_fields = function() {
+  FIELD_TEMPLATES[["recall_notice"]]$fields[seq_len(NUM_EXAMPLE_FIELDS)]
+}
+
+# One input tab button (the panels are shown and hidden by www/app.js)
+input_tab = function(id, label, icon_name, selected = FALSE) {
+  shiny::tags$button(
+    id = paste0("tab-", id),
+    type = "button",
+    class = if (selected) "input-tab active" else "input-tab",
+    role = "tab",
+    `aria-selected` = if (selected) "true" else "false",
+    `aria-controls` = paste0("panel-", id),
+    tabindex = if (selected) "0" else "-1",
+    shiny::icon(icon_name),
+    paste0(" ", label)
+  )
+}
+
+# Container of one input tab's content
+input_panel = function(id, ..., selected = FALSE) {
+  shiny::div(
+    id = paste0("panel-", id),
+    class = "input-panel",
+    role = "tabpanel",
+    `aria-labelledby` = paste0("tab-", id),
+    style = if (selected) NULL else "display: none;",
+    ...
+  )
+}
+
+# Heading followed by its "?" help button
+heading_with_help = function(heading, topic) {
+  shiny::div(class = "heading-with-help", heading, help_button(topic))
+}
 
 # Define UI for the app
 ui = shiny::fluidPage(
+  lang = "en",
   # Add Miami theme CSS and favicon
   shiny::tags$head(
     shiny::tags$link(rel = "icon", type = "image/svg+xml", href = "favicon.svg"),
@@ -33,10 +83,10 @@ ui = shiny::fluidPage(
       ),
       shiny::div(
         class = "header-right",
-        shiny::p("Version 2.0.1 | January 2026"),
+        shiny::p(APP_VERSION),
         shiny::p(
           shiny::tags$strong("Authors: "),
-          "Fadel M. Megahed, Ying-Ju (Tessa) Chen, Allison Jones-Farmer, Ibrahim Yousif, and Inez M. Zwetsloot"
+          "Fadel M. Megahed, Ying-Ju Chen, Yamin Dahwich, Arthur Carvalho, L. Allison Jones-Farmer, Ibrahim Yousif, and Inez M. Zwetsloot"
         ),
         shiny::p(
           shiny::tags$strong("Contact: "),
@@ -78,6 +128,8 @@ ui = shiny::fluidPage(
         shiny::tags$strong("Miami University,"),
         "the",
         shiny::tags$strong("University of Dayton,"),
+        "the",
+        shiny::tags$strong("University of Cambridge,"),
         "and the",
         shiny::tags$strong("University of Amsterdam")
       )
@@ -96,7 +148,9 @@ ui = shiny::fluidPage(
       ),
       shiny::tags$button(
         id = "open-video-modal",
+        type = "button",
         class = "btn btn-video-tutorial",
+        `aria-haspopup` = "dialog",
         shiny::icon("play-circle"),
         " Watch Video Tutorial"
       )
@@ -108,14 +162,14 @@ ui = shiny::fluidPage(
     ),
     shiny::p(
       "Click the ",
-      shiny::tags$strong("'Load Examples'"),
+      shiny::tags$strong("'Load Demo Data'"),
       " button to load two sample NHTSA recall notices with pre-configured extraction fields. ",
       "Then click ",
       shiny::tags$strong("'Extract Data'"),
-      " to see the AI extract structured information from the text. ",
-      "You can also add more fields, change field labels, and modify descriptions. ",
+      " to see the model extract structured information from the text. ",
+      "You can also add more fields, change field labels and types, and modify descriptions. ",
       shiny::tags$em(
-        "(Note: Field labels only affect how data is stored and displayed, not extraction performance.)"
+        "(Note: The field description is the instruction the model receives. The label names the column in the results.)"
       )
     ),
     shiny::tags$h5(
@@ -124,7 +178,7 @@ ui = shiny::fluidPage(
       " Input Methods"
     ),
     shiny::p(
-      "Choose from six input methods to provide your source content:"
+      "Choose from six input methods to provide your source content. Only the tab that is open when you click 'Extract Data' is used."
     ),
     shiny::tags$ul(
       style = "margin-bottom: 10px;",
@@ -150,21 +204,33 @@ ui = shiny::fluidPage(
       ),
       shiny::tags$li(
         shiny::tags$strong("Upload Images:"),
-        " Upload images (PNG, JPEG, WebP, GIF) for AI vision-based extraction."
+        " Upload images (PNG, JPEG, WebP, GIF) for vision-based extraction."
       )
     ),
-    shiny::p(
+    shiny::div(
       style = "font-size: 0.9em; color: #666;",
       shiny::icon("info-circle"),
       " ",
       shiny::tags$em("Notes:"),
       shiny::tags$ul(
-        style = "margin: -0.5em 0 0 1.25em; padding: 0; line-height: 1.2;",
-        shiny::tags$li(style = "margin: 0; padding: 0;",
-                       "PDF, Image, and Scanned PDF modes are limited to 5 pages/items in this free demo."
+        style = "margin: 0.25em 0 0 1.25em; padding: 0; line-height: 1.3;",
+        shiny::tags$li(
+          style = "margin: 0; padding: 0;",
+          sprintf(
+            "Readable PDF and Scanned PDF are limited to the first %d pages, and Upload Images to %d images, in this free app.",
+            MAX_PAGES_OR_IMAGES, MAX_PAGES_OR_IMAGES
+          )
         ),
-        shiny::tags$li(style = "margin: 0; padding: 0;",
-                       "Any uploaded file must be less than 5 MB (Shiny default for this free app) to keep the demo responsive and avoid upload timeouts."
+        shiny::tags$li(
+          style = "margin: 0; padding: 0;",
+          sprintf(
+            "Any uploaded file must be at most %d MB, to keep the app responsive and avoid upload timeouts.",
+            MAX_UPLOAD_MB
+          )
+        ),
+        shiny::tags$li(
+          style = "margin: 0; padding: 0;",
+          "The '?' buttons next to each part of the app explain what it does and what is sent to the model."
         )
       )
     ),
@@ -178,15 +244,25 @@ ui = shiny::fluidPage(
     ),
     shiny::tags$ul(
       style = "margin-bottom: 10px;",
-      shiny::tags$li("The ", shiny::tags$strong("number of fields"), " to extract"),
-      shiny::tags$li("Your own ", shiny::tags$strong("field labels"), " (for storage/display only)"),
-      shiny::tags$li("Detailed ", shiny::tags$strong("field descriptions"), " to guide the AI")
+      shiny::tags$li(
+        "The ", shiny::tags$strong("number of fields"), " to extract (up to ", MAX_FIELDS, ")"
+      ),
+      shiny::tags$li("Your own ", shiny::tags$strong("field labels"), " (the column names of the results)"),
+      shiny::tags$li("Detailed ", shiny::tags$strong("field descriptions"), " to guide the model"),
+      shiny::tags$li(
+        "The ", shiny::tags$strong("field type"), " (text, number, yes/no, or list of text)"
+      )
+    ),
+    shiny::p(
+      "You can start from a ",
+      shiny::tags$strong("template"),
+      " for a common quality document (recall notice, 8D / corrective action report, customer complaint record, inspection or nonconformance note), and save your field definitions to a file to reuse them later."
     ),
     shiny::p(
       shiny::icon("lightbulb"),
       " ",
       shiny::tags$em(
-        "The more specific your field descriptions, the better the extraction results."
+        "Specific field descriptions give the model less room for interpretation. Always check the extracted values against the source documents."
       )
     )
   ),
@@ -195,24 +271,31 @@ ui = shiny::fluidPage(
   shiny::div(
     id = "video-modal",
     class = "video-modal",
+    role = "dialog",
+    `aria-modal` = "true",
+    `aria-labelledby` = "video-modal-title",
     shiny::div(
       class = "video-modal-content",
-      shiny::tags$span(
+      shiny::tags$button(
         id = "close-video-modal",
+        type = "button",
         class = "video-modal-close",
+        `aria-label` = "Close video tutorial",
         shiny::HTML("×")
       ),
       shiny::tags$h4(
+        id = "video-modal-title",
         style = "color: #C41230; margin-top: 0; margin-bottom: 15px;",
         shiny::icon("play-circle"),
         " Video Tutorial"
       ),
       shiny::div(
         class = "video-modal-wrapper",
-        # Placeholder - replace VIDEO_ID_PLACEHOLDER with actual YouTube video ID
+        # The video address is set by www/app.js when the dialog opens
         shiny::tags$iframe(
           id = "tutorial-video",
-          src = "https://www.youtube.com/embed/y6Uit4Drf9w",
+          title = "Video tutorial",
+          src = "",
           allow = "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture",
           allowfullscreen = NA
         )
@@ -220,130 +303,53 @@ ui = shiny::fluidPage(
     )
   ),
 
-  # JavaScript for video modal
-  shiny::tags$script(shiny::HTML("
-    var videoUrl = 'https://www.youtube.com/embed/y6Uit4Drf9w';
-    var modal = document.getElementById('video-modal');
-    var openBtn = document.getElementById('open-video-modal');
-    var closeBtn = document.getElementById('close-video-modal');
-    var videoIframe = document.getElementById('tutorial-video');
-
-    openBtn.onclick = function() {
-      modal.style.display = 'flex';
-      videoIframe.src = videoUrl;
-    }
-
-    closeBtn.onclick = function() {
-      modal.style.display = 'none';
-      videoIframe.src = '';
-    }
-
-    window.onclick = function(event) {
-      if (event.target == modal) {
-        modal.style.display = 'none';
-        videoIframe.src = '';
-      }
-    }
-
-    document.addEventListener('keydown', function(event) {
-      if (event.key === 'Escape' && modal.style.display === 'flex') {
-        modal.style.display = 'none';
-        videoIframe.src = '';
-      }
-    });
-
-    // Input tab switching
-    function switchInputTab(tab) {
-      var tabs = ['demo', 'paste', 'textfile', 'pdf', 'scanned', 'image'];
-      tabs.forEach(function(t) {
-        var tabEl = document.getElementById('tab-' + t);
-        var panelEl = document.getElementById('panel-' + t);
-        if (t === tab) {
-          tabEl.classList.add('active');
-          panelEl.style.display = 'block';
-        } else {
-          tabEl.classList.remove('active');
-          panelEl.style.display = 'none';
-        }
-      });
-      // Update Shiny with the current input method
-      Shiny.setInputValue('input_method', tab);
-    }
-    // Initialize input method
-    Shiny.setInputValue('input_method', 'demo');
-  ")),
+  # JavaScript for the input tabs, the video dialog and the copy buttons
+  shiny::tags$script(src = "app.js"),
 
   shiny::sidebarLayout(
     shiny::sidebarPanel(
       width = 4,
       class = "sidebar-panel",
 
-      shiny::tags$h4(
-        style = "color: #C41230; margin-top: 0; margin-bottom: 15px;",
-        shiny::icon("file-alt"),
-        " Input Configuration"
+      heading_with_help(
+        shiny::tags$h4(
+          id = "input-heading",
+          style = "color: #C41230; margin-top: 0; margin-bottom: 0;",
+          shiny::icon("file-alt"),
+          " Input Configuration"
+        ),
+        "source"
       ),
 
-      # Input method tabs (3 rows for 5 tabs)
+      # Input method tabs (3 rows of 2 tabs)
       shiny::div(
         class = "input-tabs-container",
+        role = "tablist",
+        `aria-labelledby` = "input-heading",
         shiny::div(
           class = "input-tabs",
-          shiny::tags$button(
-            id = "tab-demo",
-            class = "input-tab active",
-            onclick = "switchInputTab('demo')",
-            shiny::icon("flask"),
-            " Demo Data"
-          ),
-          shiny::tags$button(
-            id = "tab-paste",
-            class = "input-tab",
-            onclick = "switchInputTab('paste')",
-            shiny::icon("paste"),
-            " Paste Text"
-          )
+          role = "presentation",
+          input_tab("demo", "Demo Data", "flask", selected = TRUE),
+          input_tab("paste", "Paste Text", "paste")
         ),
         shiny::div(
           class = "input-tabs",
-          shiny::tags$button(
-            id = "tab-textfile",
-            class = "input-tab",
-            onclick = "switchInputTab('textfile')",
-            shiny::icon("file-lines"),
-            " Text File"
-          ),
-          shiny::tags$button(
-            id = "tab-pdf",
-            class = "input-tab",
-            onclick = "switchInputTab('pdf')",
-            shiny::icon("file-pdf"),
-            " Readable PDF"
-          )
+          role = "presentation",
+          input_tab("textfile", "Text File", "file-lines"),
+          input_tab("pdf", "Readable PDF", "file-pdf")
         ),
         shiny::div(
           class = "input-tabs",
-          shiny::tags$button(
-            id = "tab-scanned",
-            class = "input-tab",
-            onclick = "switchInputTab('scanned')",
-            shiny::icon("file-image"),
-            " Scanned PDF"
-          ),
-          shiny::tags$button(
-            id = "tab-image",
-            class = "input-tab",
-            onclick = "switchInputTab('image')",
-            shiny::icon("images"),
-            " Upload Images"
-          )
+          role = "presentation",
+          input_tab("scanned", "Scanned PDF", "file-image"),
+          input_tab("image", "Upload Images", "images")
         )
       ),
 
       # Demo data panel
-      shiny::div(
-        id = "panel-demo",
-        class = "input-panel",
+      input_panel(
+        "demo",
+        selected = TRUE,
         shiny::p(
           "Try the app with pre-loaded NHTSA vehicle recall data. Click the button below to load sample text and pre-configured extraction fields."
         ),
@@ -357,26 +363,22 @@ ui = shiny::fluidPage(
       ),
 
       # Paste text panel
-      shiny::div(
-        id = "panel-paste",
-        class = "input-panel",
-        style = "display: none;",
+      input_panel(
+        "paste",
         shiny::textAreaInput(
           "input_text",
-          NULL,
+          shiny::tags$span(class = "sr-only", "Text to extract from"),
           rows = 8,
-          placeholder = "Paste your text content here.\n\nTo process multiple items at once, separate each block of text with a double line break (press Enter twice).\n\nIMPORTANT: Before extracting, scroll down to configure your extraction fields:\n1. Set the number of fields you need\n2. Update each field label (e.g., 'product_name', 'price')\n3. Write clear descriptions for each field\n\nThen click 'Extract Data' to see results."
+          placeholder = "Paste your text content here.\n\nTo process multiple items at once, separate each block of text with a double line break (press Enter twice).\n\nIMPORTANT: Before extracting, scroll down to configure your extraction fields:\n1. Choose a template or set the number of fields you need\n2. Update each field label (e.g., 'product_name', 'price')\n3. Write clear descriptions for each field\n\nThen click 'Extract Data' to see results."
         )
       ),
 
       # Text file upload panel
-      shiny::div(
-        id = "panel-textfile",
-        class = "input-panel",
-        style = "display: none;",
+      input_panel(
+        "textfile",
         shiny::fileInput(
           "text_file",
-          NULL,
+          shiny::tags$span(class = "sr-only", "Text file"),
           accept = c(".txt", ".csv", ".md"),
           placeholder = "No file selected",
           buttonLabel = shiny::tags$span(shiny::icon("upload"), " Browse...")
@@ -391,45 +393,41 @@ ui = shiny::fluidPage(
           shiny::tags$ul(
             style = "margin: 5px 0 0 0; padding-left: 20px; font-size: 0.85em;",
             shiny::tags$li(".txt: Plain text, separate items with double line breaks"),
-            shiny::tags$li(".csv: Single column of text entries (one per row)"),
-            shiny::tags$li(".md: Markdown file treated as plain text")
+            shiny::tags$li(".csv: Single column of text entries (one per row, first row is a header)"),
+            shiny::tags$li(".md: Markdown file treated as plain text, split at double line breaks")
           )
         ),
         shiny::uiOutput("textfile_preview_ui")
       ),
 
       # PDF upload panel (machine-readable)
-      shiny::div(
-        id = "panel-pdf",
-        class = "input-panel",
-        style = "display: none;",
+      input_panel(
+        "pdf",
         shiny::fileInput(
           "pdf_file",
-          NULL,
+          shiny::tags$span(class = "sr-only", "Readable PDF file"),
           accept = ".pdf",
           placeholder = "No file selected",
           buttonLabel = shiny::tags$span(shiny::icon("upload"), " Browse...")
         ),
         shiny::helpText(
           shiny::icon("info-circle"),
-          " Upload a machine-readable PDF. Text will be extracted automatically."
+          " Upload a machine-readable PDF. Text will be extracted automatically and sent as one item."
         ),
         shiny::div(
-          class = "image-limit-note",
+          class = "limit-note",
           shiny::icon("exclamation-circle"),
-          shiny::tags$em(paste(" Free app limit: Only the first", MAX_IMAGE_PAGES, "pages will be processed."))
+          shiny::tags$em(limit_note("pages"))
         ),
         shiny::uiOutput("pdf_preview_ui")
       ),
 
       # Image upload panel
-      shiny::div(
-        id = "panel-image",
-        class = "input-panel",
-        style = "display: none;",
+      input_panel(
+        "image",
         shiny::fileInput(
           "image_file",
-          NULL,
+          shiny::tags$span(class = "sr-only", "Image files"),
           accept = c(".png", ".jpg", ".jpeg", ".webp", ".gif"),
           multiple = TRUE,
           placeholder = "No file selected",
@@ -440,72 +438,98 @@ ui = shiny::fluidPage(
           " Upload image(s) containing text to extract. Supports PNG, JPEG, WebP, and GIF."
         ),
         shiny::div(
-          class = "image-limit-note",
+          class = "limit-note",
           shiny::icon("exclamation-circle"),
-          shiny::tags$em(paste(" Free app limit: Maximum", MAX_IMAGE_PAGES, "images will be processed."))
+          shiny::tags$em(limit_note("images"))
         ),
         shiny::uiOutput("image_preview_ui")
       ),
 
       # Scanned PDF panel
-      shiny::div(
-        id = "panel-scanned",
-        class = "input-panel",
-        style = "display: none;",
+      input_panel(
+        "scanned",
         shiny::fileInput(
           "scanned_pdf_file",
-          NULL,
+          shiny::tags$span(class = "sr-only", "Scanned PDF file"),
           accept = ".pdf",
           placeholder = "No file selected",
           buttonLabel = shiny::tags$span(shiny::icon("upload"), " Browse...")
         ),
         shiny::helpText(
           shiny::icon("info-circle"),
-          " Upload a scanned/image-based PDF. Pages will be converted to images for AI vision processing."
+          " Upload a scanned/image-based PDF. Pages will be converted to images for vision processing."
         ),
         shiny::div(
-          class = "image-limit-note",
+          class = "limit-note",
           shiny::icon("exclamation-circle"),
-          shiny::tags$em(paste(" Free app limit: Only the first", MAX_IMAGE_PAGES, "pages will be processed."))
+          shiny::tags$em(limit_note("pages"))
         ),
         shiny::uiOutput("scanned_pdf_preview_ui")
       ),
 
       shiny::hr(class = "field-separator"),
 
+      heading_with_help(
+        shiny::tags$h4(
+          style = "color: #C41230; margin-top: 0; margin-bottom: 0;",
+          shiny::icon("tags"),
+          " Field Definitions"
+        ),
+        "fields"
+      ),
+
+      shiny::div(
+        class = "template-row",
+        shiny::selectInput(
+          "template_id",
+          "Start from a template:",
+          choices = template_choices(FIELD_TEMPLATES),
+          selectize = FALSE
+        ),
+        shiny::actionButton("apply_template", "Use template", class = "btn-info")
+      ),
+      shiny::uiOutput("template_description_ui"),
+
       shiny::numericInput(
         "num_fields",
         shiny::tags$span(
           shiny::icon("list-ol"),
           " Number of Fields to Extract:"
         ),
-        value = num_example_fields,
+        value = NUM_EXAMPLE_FIELDS,
         min = 1,
-        max = 10
+        max = MAX_FIELDS
       ),
 
       shiny::helpText(
         shiny::icon("info-circle"),
-        " Define each field with a clear label (e.g., 'manufacturer') and description (e.g., 'The name of the company recalling the vehicles')."
+        " Define each field with a clear label (e.g., 'manufacturer') and description (e.g., 'Name of the company that is recalling the vehicles. Leave empty if no company is named.')."
       ),
 
-      shiny::hr(class = "field-separator"),
+      shiny::uiOutput("fields_ui"),
 
-      shiny::tags$h5(
-        style = "color: #C41230; margin-bottom: 10px;",
-        shiny::icon("tags"),
-        " Field Definitions"
+      shiny::div(
+        class = "fields-file-row",
+        shiny::downloadButton("download_fields", "Save fields (JSON)", class = "btn-info"),
+        shiny::fileInput(
+          "fields_upload",
+          "Load fields (JSON):",
+          accept = c(".json", "application/json"),
+          placeholder = "No file selected",
+          buttonLabel = shiny::tags$span(shiny::icon("upload"), " Browse...")
+        )
       ),
 
-      shiny::uiOutput("fields_ui"),
+      shiny::hr(class = "field-separator"),
 
       shiny::div(
-        style = "margin-top: 20px;",
+        class = "heading-with-help",
         shiny::actionButton(
           "extract_btn",
           shiny::tags$span(shiny::icon("magic"), " Extract Data"),
           class = "btn-primary"
-        )
+        ),
+        help_button("extract")
       )
     ),
 
@@ -513,32 +537,71 @@ ui = shiny::fluidPage(
       width = 8,
       class = "main-panel",
 
+      shiny::div(
+        class = "info-card",
+        shiny::div(
+          class = "heading-with-help section-heading",
+          shiny::tags$h3(
+            style = "color: #C41230; font-weight: 600; margin: 0;",
+            shiny::icon("table"),
+            " Structured Data Extracted Using AI"
+          ),
+          help_button("results")
+        ),
+        shiny::uiOutput("results_status_ui"),
+        shiny::div(class = "results-table-wrapper", shiny::tableOutput("extracted_table")),
+        shiny::uiOutput("download_btn_ui")
+      ),
+
       shiny::div(
         class = "info-card",
         shiny::tags$h3(
           class = "section-heading",
-          shiny::icon("table"),
-          " Structured Data Extracted Using AI"
+          shiny::icon("code"),
+          " Reproduce in Code"
         ),
-        shiny::div(
-          class = "results-placeholder",
-          id = "results-placeholder",
-          shiny::icon("arrow-left"),
-          " Configure your extraction fields and click 'Extract Data' to see results here"
+        shiny::p(
+          "The code below runs the same extraction, with your current field definitions and the model ",
+          shiny::tags$code(EXTRACTION_MODEL),
+          ", on your own computer and your own data. It needs your own ",
+          MODEL_PROVIDER,
+          " API key."
         ),
-        shiny::tableOutput("extracted_table"),
-        shiny::uiOutput("download_btn_ui")
+        shiny::uiOutput("snippet_status_ui"),
+        shiny::tags$details(
+          class = "code-details",
+          shiny::tags$summary("R code (ellmer package)"),
+          shiny::tags$button(
+            type = "button",
+            class = "btn btn-info copy-btn",
+            `data-target` = "snippet_r",
+            "Copy R code"
+          ),
+          shiny::verbatimTextOutput("snippet_r")
+        ),
+        shiny::tags$details(
+          class = "code-details",
+          shiny::tags$summary("Python code (chatlas package)"),
+          shiny::tags$button(
+            type = "button",
+            class = "btn btn-info copy-btn",
+            `data-target` = "snippet_python",
+            "Copy Python code"
+          ),
+          shiny::verbatimTextOutput("snippet_python")
+        )
       ),
 
       shiny::div(
         class = "tips-section",
         shiny::tags$h4(shiny::icon("lightbulb"), " Tips for Better Results"),
         shiny::tags$ul(
-          shiny::tags$li("Use ", shiny::tags$strong("specific field descriptions"), " to guide the AI accurately"),
+          shiny::tags$li("Use ", shiny::tags$strong("specific field descriptions"), " and say what to return when the information is absent"),
           shiny::tags$li("Start with ", shiny::tags$strong("more fields"), " and remove unnecessary ones later"),
           shiny::tags$li("If results are inaccurate, try ", shiny::tags$strong("rephrasing"), " your field descriptions"),
           shiny::tags$li("For ", shiny::tags$strong("multiple text blocks"), ", separate each with a double line break"),
-          shiny::tags$li("Each text block should contain ", shiny::tags$strong("complete information"), " for all fields you want to extract")
+          shiny::tags$li("Each text block should contain ", shiny::tags$strong("complete information"), " for all fields you want to extract"),
+          shiny::tags$li(shiny::tags$strong("Check the results"), " against the source documents before you use them")
         )
       ),
 
@@ -546,9 +609,19 @@ ui = shiny::fluidPage(
         class = "note-section",
         shiny::tags$h4(shiny::icon("cog"), " Technical Note"),
         shiny::p(
-          "To ensure timely results (since this is hosted on a CPU), we utilize ",
-          shiny::tags$code("gpt-5-mini-2025-08-07"),
-          " for this demo."
+          "This app sends its requests to the ",
+          MODEL_PROVIDER,
+          " model ",
+          shiny::tags$code(EXTRACTION_MODEL),
+          " through ",
+          shiny::tags$code("chat_openai()"),
+          " from the ",
+          shiny::tags$a(
+            href = "https://ellmer.tidyverse.org/",
+            target = "_blank",
+            "ellmer"
+          ),
+          " package. The app does not provide an option to change the model."
         ),
         shiny::p(
           "For ",
@@ -559,13 +632,7 @@ ui = shiny::fluidPage(
             target = "_blank",
             shiny::tags$code("chat_ollama()")
           ),
-          " from the ",
-          shiny::tags$a(
-            href = "https://ellmer.tidyverse.org/",
-            target = "_blank",
-            "ellmer"
-          ),
-          " library, which connects to ",
+          " from ellmer, which connects to ",
           shiny::tags$a(
             href = "https://ollama.com/",
             target = "_blank",
@@ -574,14 +641,7 @@ ui = shiny::fluidPage(
           " for running models locally on your machine."
         ),
         shiny::p(
-          "Alternatively, for higher accuracy requirements, users can leverage more performant closed models (e.g., ",
-          shiny::tags$em("gpt-5.2-2025-12-11"),
-          ", ",
-          shiny::tags$em("claude-opus-4-5-20251101"),
-          ", or ",
-          shiny::tags$em("gemini-3-pro-preview"),
-          ") depending on the application needs. ",
-          "Note that Claude models require ",
+          "ellmer also supports models from other providers. For example, Claude models require ",
           shiny::tags$a(
             href = "https://ellmer.tidyverse.org/reference/chat_anthropic.html",
             target = "_blank",
@@ -593,14 +653,10 @@ ui = shiny::fluidPage(
             target = "_blank",
             shiny::tags$code("chat_google_gemini()")
           ),
-          ", each with their respective API keys configured in the R environment."
-        ),
-        shiny::p(
-          shiny::tags$em(
-            "This demo uses ",
-            shiny::tags$code("chat_openai()"),
-            " only and does not provide an option to change the gpt-5-mini-2025-08-07 model."
-          )
+          ", each with their respective API keys configured in the R environment. ",
+          "The code under 'Reproduce in Code' can be adapted by replacing the ",
+          shiny::tags$code("chat_openai()"),
+          " call."
         )
       )
     )
@@ -615,63 +671,92 @@ ui = shiny::fluidPage(
       " and ",
       shiny::tags$a(href = "https://ellmer.tidyverse.org/", target = "_blank", "ellmer"),
       " | ",
-      "Powered by OpenAI"
+      "Powered by ",
+      MODEL_PROVIDER
     ),
     shiny::p(
       shiny::tags$em(
-        "Companion app to: 'What Should Quality Engineers Know about Generative AI', submitted by the app's authors to ",
+        paste0(
+          "Companion app to the paper '",
+          PAPER_TITLE,
+          "', in preparation by the app's authors for submission to "
+        ),
         shiny::tags$a(
           href = "https://www.tandfonline.com/journals/lqen20",
           target = "_blank",
           "Quality Engineering."
         )
       )
-    ),
-    # shiny::p(
-    #   "\u00A9 2026 Developed by researchers from Miami University, the University of Dayton, and the University of Amsterdam."
-    # )
+    )
   )
 )
 
 # Define server logic required to generate dynamic UI and extract data
 server = function(input, output, session) {
 
-  # Reactive value to store demo text
+  # ---- State ---------------------------------------------------------------
+
+  # What each input tab currently holds. Each tab has its own store, and the
+  # extraction reads only the store of the active tab.
   demo_text = shiny::reactiveVal("")
+  textfile_items = shiny::reactiveVal(character(0))
+  pdf_text = shiny::reactiveVal("")
+  image_files = shiny::reactiveVal(NULL)
+  scanned_pdf_paths = shiny::reactiveVal(NULL)
 
-  # Reactive value to store extracted results (for table display and CSV download)
-  extracted_results = shiny::reactiveVal(NULL)
+  # Result of the last extraction: list(table, summary, n_failed, source)
+  extraction = shiny::reactiveVal(NULL)
 
-  # Observer to clear data when switching tabs
-  shiny::observeEvent(input$input_method, {
-    # Clear the extracted results table
-    extracted_results(NULL)
-    output$extracted_table = shiny::renderTable(NULL)
+  # Field definitions. field_state holds the definitions the inputs were built
+  # from; field_gen is the generation number used in the input ids. The inputs
+  # are rebuilt only by set_fields(), never by a tab change.
+  field_state = shiny::reactiveVal(demo_fields())
+  field_gen = shiny::reactiveVal(0)
 
-    # Clear the text area when switching to paste tab (so placeholder shows)
-    if (input$input_method == "paste") {
-      shiny::updateTextAreaInput(session, "input_text", value = "")
-    }
-  }, ignoreInit = TRUE)
+  # Creates the chat for each item. Tests replace it through the option.
+  chat_factory = getOption("ste.chat_factory", default = make_chat_factory(EXTRACTION_MODEL))
 
-  # Load example data
-  shiny::observeEvent(input$load_example, {
-    example_text = "Ford Motor Company (Ford) is recalling certain 2021-2022 Bronco vehicles equipped with rearview camera systems and 8-inch screen displays. The rearview camera image may still be displayed after a backing event has ended. As such, these vehicles fail to comply with the requirements of Federal Motor Vehicle Safety Standard number 111, \"Rear Visibility.\"\n\nHonda (American Honda Motor Co.) is recalling certain 2022-2025 Acura MDX Type-S, 2023-2025 Honda Pilot, and 2021-2025 Acura TLX Type-S vehicles. A software error in the fuel injection electronic control unit (FI-ECU) may cause an engine stall or a loss of power."
+  # ---- Helpers -------------------------------------------------------------
 
-    # Store demo text
-    demo_text(example_text)
+  notify = function(message, type = "message", duration = 3) {
+    icon_name = switch(
+      type,
+      error = "exclamation-triangle",
+      warning = "exclamation-circle",
+      "check-circle"
+    )
+    shiny::showNotification(
+      shiny::tags$span(shiny::icon(icon_name), " ", message),
+      type = type,
+      duration = duration
+    )
+  }
 
-    # Also update the text area for extraction
-    shiny::updateTextAreaInput(session, "input_text", value = example_text)
+  # Active input tab (the client reports it through input$input_method)
+  active_method = shiny::reactive({
+    method = input$input_method
+    if (is.null(method) || !(method %in% INPUT_METHODS)) "demo" else method
+  })
 
-    # Set up example fields
-    shiny::updateNumericInput(session, "num_fields", value = num_example_fields)
+  # Field definitions as currently shown, including what the user has typed
+  current_fields = shiny::reactive({
+    merge_field_inputs(field_state(), function(id) input[[id]], field_gen())
+  })
 
-    shiny::showNotification(
-      "Demo data loaded! Click 'Extract Data' to see results.",
-      type = "message",
-      duration = 3
-    )
+  # Replace the field definitions and rebuild their inputs
+  set_fields = function(fields) {
+    field_state(fields)
+    field_gen(shiny::isolate(field_gen()) + 1)
+    shiny::updateNumericInput(session, "num_fields", value = length(fields))
+  }
+
+  # ---- Input sources -------------------------------------------------------
+
+  # Load example data
+  shiny::observeEvent(input$load_example, {
+    demo_text(DEMO_TEXT)
+    set_fields(demo_fields())
+    notify("Demo data loaded. Click 'Extract Data' to see results.")
   })
 
   # Render demo preview
@@ -679,67 +764,46 @@ server = function(input, output, session) {
     text = demo_text()
     if (is.null(text) || nchar(text) == 0) return(NULL)
 
-    preview_text = if (nchar(text) > 500) {
-      paste0(substr(text, 1, 500), "...")
-    } else {
-      text
-    }
-
     shiny::div(
       class = "pdf-preview",
       style = "margin-top: 15px;",
       shiny::tags$strong("Loaded Demo Text:"),
-      shiny::tags$pre(preview_text)
+      shiny::tags$pre(preview_text(text))
     )
   })
 
-  # Reactive value to store PDF extracted text
-  pdf_text = shiny::reactiveVal("")
-
   # Process uploaded PDF
   shiny::observeEvent(input$pdf_file, {
     shiny::req(input$pdf_file)
 
     tryCatch({
-      # Extract text from PDF
-      pdf_path = input$pdf_file$datapath
-      extracted = pdftools::pdf_text(pdf_path)
-
-      # Limit to MAX_IMAGE_PAGES
-      total_pages = length(extracted)
-      if (total_pages > MAX_IMAGE_PAGES) {
-        extracted = extracted[1:MAX_IMAGE_PAGES]
-        shiny::showNotification(
-          paste("Only the first", MAX_IMAGE_PAGES, "pages will be processed (free app limit)."),
+      extracted = read_pdf_text(input$pdf_file$datapath, MAX_PAGES_OR_IMAGES)
+
+      if (extracted$total_pages > extracted$used_pages) {
+        notify(
+          sprintf(
+            "The PDF has %d pages. Only the first %d will be processed (free app limit).",
+            extracted$total_pages, extracted$used_pages
+          ),
           type = "warning",
           duration = 5
         )
       }
 
-      # Combine all pages with double line breaks
-      combined_text = paste(extracted, collapse = "\n\n")
-
-      # Clean up the text (remove excessive whitespace)
-      combined_text = gsub("\\s+", " ", combined_text)
-      combined_text = trimws(combined_text)
-
-      # Store the extracted text
-      pdf_text(combined_text)
+      pdf_text(extracted$text)
 
-      # Update the text area with extracted text
-      shiny::updateTextAreaInput(session, "input_text", value = combined_text)
-
-      shiny::showNotification(
-        paste("PDF processed successfully!", length(extracted), "page(s) extracted."),
-        type = "message",
-        duration = 3
-      )
+      if (nchar(extracted$text) == 0) {
+        notify(
+          "No text was found in this PDF. If it is a scan, use the Scanned PDF tab.",
+          type = "warning",
+          duration = 8
+        )
+      } else {
+        notify(sprintf("PDF processed. Text of %d page(s) read.", extracted$used_pages))
+      }
     }, error = function(e) {
-      shiny::showNotification(
-        paste("Error reading PDF:", e$message),
-        type = "error",
-        duration = NULL
-      )
+      pdf_text("")
+      notify(paste("Error reading PDF:", conditionMessage(e)), type = "error", duration = NULL)
     })
   })
 
@@ -748,169 +812,116 @@ server = function(input, output, session) {
     text = pdf_text()
     if (is.null(text) || nchar(text) == 0) return(NULL)
 
-    preview_text = if (nchar(text) > 500) {
-      paste0(substr(text, 1, 500), "...")
-    } else {
-      text
-    }
-
     shiny::div(
       class = "pdf-preview",
       shiny::tags$strong("Extracted Text Preview:"),
-      shiny::tags$pre(preview_text)
+      shiny::tags$pre(preview_text(text))
     )
   })
 
-  # Reactive value for text file content
-  textfile_text = shiny::reactiveVal("")
-
   # Process uploaded text file
   shiny::observeEvent(input$text_file, {
     shiny::req(input$text_file)
 
     tryCatch({
-      file_path = input$text_file$datapath
-      file_name = input$text_file$name
-      file_ext = tolower(tools::file_ext(file_name))
-
-      extracted_text = ""
-
-      if (file_ext == "csv") {
-        # Read CSV - assume single column or use first column
-        csv_data = utils::read.csv(file_path, header = TRUE, stringsAsFactors = FALSE)
-        if (ncol(csv_data) >= 1) {
-          # Use first column, combine rows with double line breaks
-          extracted_text = paste(csv_data[[1]], collapse = "\n\n")
-        }
+      items = read_text_file_items(input$text_file$datapath, input$text_file$name)
+      textfile_items(items)
+
+      if (length(items) == 0) {
+        notify("No text was found in this file.", type = "warning", duration = 8)
       } else {
-        # Read txt or md as plain text
-        extracted_text = paste(readLines(file_path, warn = FALSE), collapse = "\n")
+        notify(sprintf("File processed. %d item(s) found.", length(items)))
       }
-
-      # Clean up the text
-      extracted_text = trimws(extracted_text)
-
-      # Store the extracted text
-      textfile_text(extracted_text)
-
-      # Update the text area with extracted text
-      shiny::updateTextAreaInput(session, "input_text", value = extracted_text)
-
-      shiny::showNotification(
-        paste("File processed successfully!"),
-        type = "message",
-        duration = 3
-      )
     }, error = function(e) {
-      shiny::showNotification(
-        paste("Error reading file:", e$message),
-        type = "error",
-        duration = NULL
-      )
+      textfile_items(character(0))
+      notify(paste("Error reading file:", conditionMessage(e)), type = "error", duration = NULL)
     })
   })
 
   # Render text file preview
   output$textfile_preview_ui = shiny::renderUI({
-    text = textfile_text()
-    if (is.null(text) || nchar(text) == 0) return(NULL)
-
-    preview_text = if (nchar(text) > 500) {
-      paste0(substr(text, 1, 500), "...")
-    } else {
-      text
-    }
+    items = textfile_items()
+    if (length(items) == 0) return(NULL)
 
     shiny::div(
       class = "pdf-preview",
-      shiny::tags$strong("Extracted Text Preview:"),
-      shiny::tags$pre(preview_text)
+      shiny::tags$strong(sprintf("Extracted Text Preview (%d item(s)):", length(items))),
+      shiny::tags$pre(preview_text(items))
     )
   })
 
-  # Reactive values to store image paths for vision-based extraction
-  image_paths = shiny::reactiveVal(NULL)
-  scanned_pdf_paths = shiny::reactiveVal(NULL)
-
   # Process uploaded images
   shiny::observeEvent(input$image_file, {
     shiny::req(input$image_file)
 
     tryCatch({
       files = input$image_file
-      # Limit to MAX_IMAGE_PAGES
-      n_files = min(nrow(files), MAX_IMAGE_PAGES)
+      files$mime = vapply(
+        seq_len(nrow(files)),
+        function(i) detect_mime(files$datapath[i], files$name[i]),
+        character(1)
+      )
 
-      if (nrow(files) > MAX_IMAGE_PAGES) {
-        shiny::showNotification(
-          paste("Only the first", MAX_IMAGE_PAGES, "images will be processed (free app limit)."),
+      not_images = files$name[is.na(files$mime)]
+      files = files[!is.na(files$mime), , drop = FALSE]
+      if (length(not_images) > 0) {
+        notify(
+          paste("Not a supported image, skipped:", paste(not_images, collapse = ", ")),
           type = "warning",
-          duration = 5
+          duration = 8
         )
       }
 
-      # Store paths of uploaded images
-      paths = files$datapath[1:n_files]
-      image_paths(paths)
+      if (nrow(files) > MAX_PAGES_OR_IMAGES) {
+        notify(
+          sprintf(
+            "Only the first %d images will be processed (free app limit).",
+            MAX_PAGES_OR_IMAGES
+          ),
+          type = "warning",
+          duration = 5
+        )
+        files = files[seq_len(MAX_PAGES_OR_IMAGES), , drop = FALSE]
+      }
 
-      shiny::showNotification(
-        paste(n_files, "image(s) uploaded successfully!"),
-        type = "message",
-        duration = 3
-      )
+      image_files(if (nrow(files) > 0) files else NULL)
+      if (nrow(files) > 0) notify(sprintf("%d image(s) uploaded.", nrow(files)))
     }, error = function(e) {
-      shiny::showNotification(
-        paste("Error uploading images:", e$message),
-        type = "error",
-        duration = NULL
-      )
+      image_files(NULL)
+      notify(paste("Error uploading images:", conditionMessage(e)), type = "error", duration = NULL)
     })
   })
 
   # Render image preview
   output$image_preview_ui = shiny::renderUI({
-    paths = image_paths()
-    if (is.null(paths) || length(paths) == 0) return(NULL)
+    files = image_files()
+    if (is.null(files) || nrow(files) == 0) return(NULL)
 
     shiny::tagList(
       shiny::div(
         class = "image-preview-grid",
-        lapply(seq_along(paths), function(i) {
+        lapply(seq_len(nrow(files)), function(i) {
           shiny::div(
             class = "image-preview-item",
             shiny::tags$img(
-              src = base64enc::dataURI(file = paths[i], mime = "image/png"),
-              alt = paste("Image", i)
+              src = base64enc::dataURI(file = files$datapath[i], mime = files$mime[i]),
+              alt = paste0("Image ", i, ": ", files$name[i])
             )
           )
         })
       ),
       shiny::div(
         class = "image-preview-count",
-        paste(length(paths), "image(s) ready for extraction")
+        paste(nrow(files), "image(s) ready for extraction")
       )
     )
   })
 
-  # Process scanned PDF (convert to images)
+  # Process scanned PDF (convert pages to images)
   shiny::observeEvent(input$scanned_pdf_file, {
     shiny::req(input$scanned_pdf_file)
 
     tryCatch({
-      pdf_path = input$scanned_pdf_file$datapath
-
-      # Get number of pages
-      pdf_info = pdftools::pdf_info(pdf_path)
-      n_pages = min(pdf_info$pages, MAX_IMAGE_PAGES)
-
-      if (pdf_info$pages > MAX_IMAGE_PAGES) {
-        shiny::showNotification(
-          paste("Only the first", MAX_IMAGE_PAGES, "pages will be processed (free app limit)."),
-          type = "warning",
-          duration = 5
-        )
-      }
-
       shiny::showNotification(
         "Converting PDF pages to images...",
         type = "message",
@@ -918,31 +929,25 @@ server = function(input, output, session) {
         id = "convert_notif"
       )
 
-      # Convert PDF pages to images using magick
-      pdf_images = magick::image_read_pdf(pdf_path, pages = 1:n_pages, density = 150)
-
-      # Save images to temp files
-      temp_paths = sapply(1:n_pages, function(i) {
-        temp_file = tempfile(fileext = ".png")
-        magick::image_write(pdf_images[i], temp_file, format = "png")
-        temp_file
-      })
-
-      scanned_pdf_paths(temp_paths)
+      rendered = render_pdf_pages(input$scanned_pdf_file$datapath, MAX_PAGES_OR_IMAGES)
+      scanned_pdf_paths(rendered$paths)
 
       shiny::removeNotification(id = "convert_notif")
-      shiny::showNotification(
-        paste(n_pages, "page(s) converted successfully!"),
-        type = "message",
-        duration = 3
-      )
+      if (rendered$total_pages > length(rendered$paths)) {
+        notify(
+          sprintf(
+            "The PDF has %d pages. Only the first %d will be processed (free app limit).",
+            rendered$total_pages, length(rendered$paths)
+          ),
+          type = "warning",
+          duration = 5
+        )
+      }
+      notify(sprintf("%d page(s) converted.", length(rendered$paths)))
     }, error = function(e) {
+      scanned_pdf_paths(NULL)
       shiny::removeNotification(id = "convert_notif")
-      shiny::showNotification(
-        paste("Error processing scanned PDF:", e$message),
-        type = "error",
-        duration = NULL
-      )
+      notify(paste("Error processing scanned PDF:", conditionMessage(e)), type = "error", duration = NULL)
     })
   })
 
@@ -958,7 +963,7 @@ server = function(input, output, session) {
           shiny::div(
             class = "image-preview-item",
             shiny::tags$img(
-              src = base64enc::dataURI(file = paths[i], mime = "image/png"),
+              src = base64enc::dataURI(file = paths[i], mime = detect_mime(paths[i])),
               alt = paste("Page", i)
             )
           )
@@ -971,279 +976,248 @@ server = function(input, output, session) {
     )
   })
 
-  # Dynamically generate UI elements for each field's label and description
-  output$fields_ui = shiny::renderUI({
-    n = input$num_fields
-    input_method = input$input_method
-    if (is.null(n) || n < 1) return(NULL)
-    if (is.null(input_method)) input_method = "demo"
-
-    # Use NHTSA example fields only for demo mode
-    if (input_method == "demo") {
-      example_labels = c("manufacturer", "defect_summary", "models", "model_years", "component", "fmvss_number", "root_cause", "risk")
-      example_descs = c(
-        "The name of the company recalling the vehicles.",
-        "Summary of the main defect.",
-        "List of affected vehicle models.",
-        "List of model years affected.",
-        "The part or system affected by the defect.",
-        "The FMVSS number mentioned, if any.",
-        "The root cause of the defect.",
-        "The risk or consequence posed by the defect."
+  # The previews sit in panels that www/app.js shows and hides
+  for (preview_id in c("demo_preview_ui", "pdf_preview_ui", "textfile_preview_ui",
+                       "image_preview_ui", "scanned_pdf_preview_ui")) {
+    shiny::outputOptions(output, preview_id, suspendWhenHidden = FALSE)
+  }
+
+  # What each tab holds right now, in the form resolve_source_items() expects
+  current_sources = function() {
+    files = image_files()
+    list(
+      demo = demo_text(),
+      paste = input$input_text,
+      textfile = textfile_items(),
+      pdf = pdf_text(),
+      scanned = scanned_pdf_paths(),
+      image = if (is.null(files)) NULL else files$datapath
+    )
+  }
+
+  # ---- Field definitions ---------------------------------------------------
+
+  # Change the number of fields, keeping everything the user has entered
+  shiny::observeEvent(input$num_fields, {
+    n = clamp_num_fields(input$num_fields, MAX_FIELDS)
+    if (is.na(n)) return()
+
+    if (!isTRUE(n == input$num_fields)) {
+      shiny::updateNumericInput(session, "num_fields", value = n)
+      notify(
+        sprintf("The number of fields must be between 1 and %d.", MAX_FIELDS),
+        type = "warning",
+        duration = 5
       )
-    } else {
-      # Generic placeholders for non-demo modes
-      example_labels = character(0)
-      example_descs = character(0)
     }
 
-    fields = purrr::map(1:n, function(i) {
-      # Set default values - use examples for demo, generic for others
-      if (input_method == "demo" && i <= length(example_labels)) {
-        default_label = example_labels[i]
-        default_desc = example_descs[i]
-      } else {
-        default_label = paste0("field_", i)
-        default_desc = "Describe what to extract for this field"
-      }
+    fields = current_fields()
+    if (n == length(fields)) return()
+    field_state(resize_fields(fields, n))
+    field_gen(field_gen() + 1)
+  }, ignoreInit = TRUE)
+
+  # Fill the fields from a template
+  shiny::observeEvent(input$apply_template, {
+    template = FIELD_TEMPLATES[[input$template_id]]
+    if (is.null(template)) return()
+    set_fields(template$fields)
+    notify(sprintf("Template '%s' loaded. You can edit the fields.", template$name))
+  })
+
+  output$template_description_ui = shiny::renderUI({
+    template = FIELD_TEMPLATES[[input$template_id]]
+    if (is.null(template)) return(NULL)
+    shiny::helpText(sprintf("%s %d fields.", template$description, length(template$fields)))
+  })
+
+  # Restore the fields from an uploaded JSON file
+  shiny::observeEvent(input$fields_upload, {
+    shiny::req(input$fields_upload)
+    loaded = read_fields_json(input$fields_upload$datapath, MAX_FIELDS)
+    if (!loaded$ok) {
+      notify(
+        paste("The field definitions were not loaded.", loaded$error),
+        type = "error",
+        duration = NULL
+      )
+      return()
+    }
+    set_fields(loaded$fields)
+    notify(sprintf("%d field(s) loaded from the file.", length(loaded$fields)))
+  })
+
+  # Download the current field definitions as JSON
+  output$download_fields = shiny::downloadHandler(
+    filename = function() {
+      paste0("field_definitions_", format(Sys.time(), "%Y%m%d_%H%M%S"), ".json")
+    },
+    content = function(file) {
+      writeLines(fields_to_json(current_fields()), file, useBytes = TRUE)
+    }
+  )
+
+  # Generate the inputs for each field's label, description and type.
+  # Depends only on field_gen, so typing and tab changes never rebuild them.
+  output$fields_ui = shiny::renderUI({
+    gen = field_gen()
+    fields = shiny::isolate(field_state())
+
+    do.call(shiny::tagList, lapply(seq_along(fields), function(i) {
+      ids = field_input_ids(gen, i)
+      field = fields[[i]]
 
       shiny::div(
-        style = "background-color: #EDECE2; padding: 12px; border-radius: 6px; margin-bottom: 12px;",
+        class = "field-card",
         shiny::tags$span(
           style = "color: #C41230; font-weight: 600; font-size: 0.9em;",
           paste("Field", i)
         ),
-        shiny::textInput(
-          paste0("field_label_", i),
-          "Label:",
-          value = default_label
-        ),
-        shiny::textInput(
-          paste0("field_desc_", i),
+        shiny::textInput(ids$label, "Label:", value = field$label),
+        shiny::textAreaInput(
+          ids$description,
           "Description:",
-          value = default_desc
+          value = field$description,
+          rows = 3,
+          placeholder = "Describe what to extract for this field, and what to return when it is absent"
+        ),
+        shiny::selectInput(
+          ids$type,
+          "Type:",
+          choices = stats::setNames(names(FIELD_TYPES), FIELD_TYPES),
+          selected = if (field$type %in% names(FIELD_TYPES)) field$type else "text",
+          selectize = FALSE
         )
       )
-    })
-    do.call(shiny::tagList, fields)
+    }))
   })
 
-  # Build a custom type_object based on user-specified fields
-  create_type_object = shiny::reactive({
-    n = input$num_fields
-    if (is.null(n) || n < 1) return(NULL)
-
-    # Build a list of field definitions
-    type_list = list()
-    for (i in 1:n) {
-      label = input[[paste0("field_label_", i)]]
-      desc = input[[paste0("field_desc_", i)]]
-      if (!is.null(label) && label != "") {
-        type_list[[label]] = ellmer::type_string(desc, required = FALSE)
-      }
-    }
-    # Dynamically create the type object
-    do.call(ellmer::type_object, type_list)
+  # ---- Help ----------------------------------------------------------------
+
+  lapply(HELP_TOPICS, function(topic) {
+    shiny::observeEvent(input[[paste0("help_", topic)]], {
+      shiny::showModal(help_modal(topic))
+    })
   })
 
+  # ---- Extraction ----------------------------------------------------------
+
   # When the extract button is clicked, perform extraction
   shiny::observeEvent(input$extract_btn, {
-    # Get the current input method
-    input_method = input$input_method
-    if (is.null(input_method)) input_method = "demo"
-
-    # Validate input based on method with helpful error messages
-    has_data = FALSE
-    error_msg = ""
-
-    # Suffix to add to error messages reminding about field configuration
-    field_reminder = " Also, make sure to update the field labels and descriptions for your data."
-
-    if (input_method == "demo") {
-      # Check if demo data was loaded
-      if (is.null(demo_text()) || nchar(demo_text()) == 0) {
-        error_msg = "Please click 'Load Demo Data' first to load the sample data."
-      } else {
-        has_data = TRUE
-      }
-    } else if (input_method == "paste") {
-      # Check if text was pasted
-      if (is.null(input$input_text) || nchar(trimws(input$input_text)) == 0) {
-        error_msg = paste0("Please paste your text content in the text area.", field_reminder)
-      } else {
-        has_data = TRUE
-      }
-    } else if (input_method == "textfile") {
-      # Check if text file was uploaded
-      if (is.null(textfile_text()) || nchar(textfile_text()) == 0) {
-        error_msg = paste0("Please upload a text file (.txt, .csv, or .md) first.", field_reminder)
-      } else {
-        has_data = TRUE
-      }
-    } else if (input_method == "pdf") {
-      # Check if PDF was uploaded
-      if (is.null(pdf_text()) || nchar(pdf_text()) == 0) {
-        error_msg = paste0("Please upload a readable PDF file first.", field_reminder)
-      } else {
-        has_data = TRUE
-      }
-    } else if (input_method == "image") {
-      # Check if images were uploaded
-      if (is.null(image_paths()) || length(image_paths()) == 0) {
-        error_msg = paste0("Please upload one or more image files first.", field_reminder)
-      } else {
-        has_data = TRUE
-      }
-    } else if (input_method == "scanned") {
-      # Check if scanned PDF was uploaded
-      if (is.null(scanned_pdf_paths()) || length(scanned_pdf_paths()) == 0) {
-        error_msg = paste0("Please upload a scanned PDF file first.", field_reminder)
-      } else {
-        has_data = TRUE
-      }
+    # Items come from the active tab only
+    resolved = resolve_source_items(active_method(), current_sources(), MAX_PAGES_OR_IMAGES)
+    if (!resolved$ok) {
+      notify(resolved$error, type = "error", duration = 5)
+      return()
     }
 
-    # Show error if no data
-    if (!has_data) {
-      shiny::showNotification(
-        shiny::tags$span(
-          shiny::icon("exclamation-triangle"),
-          " ",
-          error_msg
+    checked = validate_fields(current_fields(), MAX_FIELDS)
+    if (!checked$ok) {
+      notify(
+        shiny::tagList(
+          "Please correct the field definitions:",
+          shiny::tags$ul(lapply(checked$errors, shiny::tags$li))
         ),
         type = "error",
-        duration = 5
+        duration = NULL
       )
       return()
     }
-
-    # Show processing indicator
-    shiny::showNotification(
-      shiny::tags$span(
-        shiny::icon("spinner", class = "fa-spin"),
-        " Processing extraction request..."
-      ),
-      type = "message",
-      duration = NULL,
-      id = "extract_notif"
-    )
-
-    custom_type_object = create_type_object()
-
-    # Initialize the chat object using the OpenAI API key from your environment
-    tryCatch({
-      # Check if API key is available
-      if (Sys.getenv("OPENAI_API_KEY") == "") {
-        stop("OpenAI API key not found. Please set the OPENAI_API_KEY environment variable.")
-      }
-
-      chat = ellmer::chat_openai(
-        model = "gpt-5-mini-2025-08-07",
+    if (length(checked$notes) > 0) {
+      notify(
+        shiny::tags$ul(lapply(checked$notes, shiny::tags$li)),
+        type = "warning",
+        duration = 10
       )
+    }
 
-      all_results = list()
-
-      if (input_method %in% c("demo", "paste", "pdf", "textfile")) {
-        # Text-based extraction
-        # Split text by double linebreaks to process multiple entities
-        text_blocks = unlist(strsplit(input$input_text, "\n\n"))
-        text_blocks = text_blocks[text_blocks != ""] # Remove empty blocks
+    if (is.null(getOption("ste.chat_factory")) && !api_key_available()) {
+      notify(
+        "The extraction service is not available right now. Please try again later, or contact the authors if the problem continues.",
+        type = "error",
+        duration = NULL
+      )
+      return()
+    }
 
-        # Process each text block
-        for (i in seq_along(text_blocks)) {
-          result = chat$chat_structured(text_blocks[i], type = custom_type_object)
-          if (is.list(result)) {
-            result$source_id = i
-            all_results[[i]] = result
-          }
-        }
-
-      } else if (input_method == "image") {
-        # Vision-based extraction from uploaded images
-        paths = image_paths()
-
-        for (i in seq_along(paths)) {
-          # Create image content for the model
-          image_content = ellmer::content_image_file(paths[i], resize = "high")
-          result = chat$chat_structured(image_content, type = custom_type_object)
-          if (is.list(result)) {
-            result$source_id = paste("Image", i)
-            all_results[[i]] = result
-          }
-        }
-
-      } else if (input_method == "scanned") {
-        # Vision-based extraction from scanned PDF pages
-        paths = scanned_pdf_paths()
-
-        for (i in seq_along(paths)) {
-          # Create image content for the model
-          image_content = ellmer::content_image_file(paths[i], resize = "high")
-          result = chat$chat_structured(image_content, type = custom_type_object)
-          if (is.list(result)) {
-            result$source_id = paste("Page", i)
-            all_results[[i]] = result
+    items = resolved$items
+    source_label = INPUT_METHOD_LABELS[[active_method()]]
+    custom_type_object = build_type_object(checked$fields)
+
+    results = shiny::withProgress(
+      message = "Extracting",
+      value = 0,
+      {
+        extracted = extract_items(
+          items,
+          custom_type_object,
+          chat_factory,
+          on_progress = function(i, n, item) {
+            shiny::setProgress(
+              value = (i - 1) / n,
+              detail = sprintf("item %d of %d (source_id: %s)", i, n, item$source_id)
+            )
           }
-        }
-      }
-
-      # Combine all results into a single data frame
-      if (length(all_results) > 0) {
-        combined_results = do.call(rbind, lapply(all_results, function(x) {
-          # Ensure all results have the same columns by converting to data frame
-          as.data.frame(x)
-        }))
-
-        # Store results for CSV download
-        extracted_results(combined_results)
-
-        # Render the output as a table
-        output$extracted_table = shiny::renderTable(
-          {
-            combined_results
-          },
-          rownames = TRUE,
-          striped = TRUE,
-          hover = TRUE,
-          bordered = TRUE
         )
-      } else {
-        # Handle the case when no valid results are returned
-        extracted_results(NULL)
-        output$extracted_table = shiny::renderTable({
-          data.frame(Message = "No valid data could be extracted. Please check your input and field definitions.")
-        })
+        shiny::setProgress(value = 1, detail = "done")
+        extracted
       }
+    )
 
-      # Remove notification
-      shiny::removeNotification(id = "extract_notif")
-      shiny::showNotification(
-        shiny::tags$span(
-          shiny::icon("check-circle"),
-          " Extraction complete!"
-        ),
-        type = "message",
-        duration = 3
-      )
-    }, error = function(e) {
-      # Handle errors
-      shiny::removeNotification(id = "extract_notif")
-      shiny::showNotification(
-        shiny::tags$span(
-          shiny::icon("exclamation-triangle"),
-          " Error: ",
-          e$message
-        ),
-        type = "error",
-        duration = NULL
-      )
-    })
+    results_table = assemble_results(results, checked$fields)
+    n_failed = sum(results_table$status != "ok")
+    extraction(list(
+      table = results_table,
+      summary = summarize_results(results_table),
+      n_failed = n_failed,
+      source = source_label
+    ))
+
+    if (n_failed == 0) {
+      notify("Extraction complete.")
+    } else {
+      notify(summarize_results(results_table), type = "warning", duration = 8)
+    }
   })
 
+  # Summary line above the table, or the placeholder before the first run
+  output$results_status_ui = shiny::renderUI({
+    result = extraction()
+    if (is.null(result)) {
+      return(shiny::div(
+        class = "results-placeholder",
+        shiny::icon("arrow-left"),
+        " Configure your extraction fields and click 'Extract Data' to see results here"
+      ))
+    }
+
+    shiny::div(
+      class = if (result$n_failed > 0) "results-summary has-failures" else "results-summary",
+      role = "status",
+      shiny::tags$strong(result$summary),
+      sprintf(" Source: %s.", result$source),
+      if (result$n_failed > 0) {
+        " The status_message column gives the reason for each failure."
+      },
+      " Check the values against the source documents before you use them."
+    )
+  })
+
+  output$extracted_table = shiny::renderTable(
+    {
+      result = extraction()
+      if (is.null(result)) return(NULL)
+      display_table(result$table)
+    },
+    striped = TRUE,
+    hover = TRUE,
+    bordered = TRUE
+  )
+
   # Render download button only when results are available
   output$download_btn_ui = shiny::renderUI({
-    results = extracted_results()
-    if (is.null(results) || nrow(results) == 0) return(NULL)
+    result = extraction()
+    if (is.null(result) || nrow(result$table) == 0) return(NULL)
 
     shiny::div(
       style = "margin-top: 15px;",
@@ -1261,12 +1235,45 @@ server = function(input, output, session) {
       paste0("extracted_data_", format(Sys.time(), "%Y%m%d_%H%M%S"), ".csv")
     },
     content = function(file) {
-      results = extracted_results()
-      if (!is.null(results)) {
-        utils::write.csv(results, file, row.names = FALSE)
+      result = extraction()
+      if (!is.null(result)) {
+        utils::write.csv(result$table, file, row.names = FALSE, na = "")
       }
     }
   )
+
+  # ---- Reproduce in code ---------------------------------------------------
+
+  # Fields used in the snippets (sanitized, as they would be sent)
+  snippet_fields = shiny::reactive({
+    validate_fields(current_fields(), MAX_FIELDS)
+  })
+
+  output$snippet_status_ui = shiny::renderUI({
+    checked = snippet_fields()
+    if (checked$ok) return(NULL)
+    shiny::div(
+      class = "limit-note",
+      "The code is shown once the field definitions are valid: ",
+      paste(checked$errors, collapse = " ")
+    )
+  })
+
+  output$snippet_r = shiny::renderText({
+    checked = snippet_fields()
+    if (!checked$ok) return("")
+    r_snippet(checked$fields, EXTRACTION_MODEL)
+  })
+
+  output$snippet_python = shiny::renderText({
+    checked = snippet_fields()
+    if (!checked$ok) return("")
+    python_snippet(checked$fields, EXTRACTION_MODEL)
+  })
+
+  # The code blocks sit inside collapsed <details> elements
+  shiny::outputOptions(output, "snippet_r", suspendWhenHidden = FALSE)
+  shiny::outputOptions(output, "snippet_python", suspendWhenHidden = FALSE)
 }
 
 # Run the Shiny app

config/templates/corrective_action_8d.json

@@ -0,0 +1,53 @@
+{
+  "id": "corrective_action_8d",
+  "name": "8D / corrective action report",
+  "description": "8D problem-solving report or corrective action report (CAR, SCAR).",
+  "order": 2,
+  "fields": [
+    {
+      "label": "report_id",
+      "description": "The identifier of the report (for example, an 8D, CAR or SCAR number), exactly as written. Leave empty if the report has no identifier.",
+      "type": "text"
+    },
+    {
+      "label": "part_number",
+      "description": "The part number or product identifier that the report concerns, exactly as written. If several are listed, return the first one. Leave empty if none is given.",
+      "type": "text"
+    },
+    {
+      "label": "problem_description",
+      "description": "One or two sentences stating the problem as the report describes it (what failed, where it was found, and how many units, when stated). Use only facts in the report. Leave empty if the report gives no problem description.",
+      "type": "text"
+    },
+    {
+      "label": "containment_actions",
+      "description": "The interim containment actions taken to protect the customer (for example, sorting stock or quarantining a lot), one entry per action. Do not include permanent corrective actions. Return an empty list if none are stated.",
+      "type": "list"
+    },
+    {
+      "label": "root_cause",
+      "description": "The root cause of why the problem occurred, as stated in the report. Do not infer a cause. Leave empty if the report states none or says the analysis is still open.",
+      "type": "text"
+    },
+    {
+      "label": "escape_point",
+      "description": "Why the problem was not detected before it reached the customer (the escape point or detection root cause), as stated in the report. Leave empty if the report does not state it.",
+      "type": "text"
+    },
+    {
+      "label": "corrective_actions",
+      "description": "The permanent corrective actions chosen or implemented to remove the root cause, one entry per action. Do not include containment actions. Return an empty list if none are stated.",
+      "type": "list"
+    },
+    {
+      "label": "preventive_actions",
+      "description": "The actions taken to prevent recurrence on this and similar products or processes (for example, updates to the FMEA, control plan or work instructions), one entry per action. Return an empty list if none are stated.",
+      "type": "list"
+    },
+    {
+      "label": "effectiveness_verified",
+      "description": "True if the report states that the effectiveness of the corrective actions was verified. False if the report states that verification is pending or was not done. Leave empty if the report does not mention verification.",
+      "type": "yes_no"
+    }
+  ]
+}

config/templates/customer_complaint.json

@@ -0,0 +1,48 @@
+{
+  "id": "customer_complaint",
+  "name": "Customer complaint record",
+  "description": "Customer complaint, warranty claim or service call record.",
+  "order": 3,
+  "fields": [
+    {
+      "label": "complaint_date",
+      "description": "The date the complaint was made or received, in YYYY-MM-DD format. If only the month and year are given, return YYYY-MM. Leave empty if no date is stated.",
+      "type": "text"
+    },
+    {
+      "label": "product",
+      "description": "The product the complaint is about, including the model name or number when given, as written in the record. Leave empty if no product is identified.",
+      "type": "text"
+    },
+    {
+      "label": "lot_or_serial",
+      "description": "The lot, batch or serial number of the product, exactly as written. Leave empty if none is given.",
+      "type": "text"
+    },
+    {
+      "label": "complaint_summary",
+      "description": "One or two sentences stating what the customer reported, using only facts in the record. Leave empty if the record does not describe the complaint.",
+      "type": "text"
+    },
+    {
+      "label": "failure_mode",
+      "description": "The way the product failed, as a short phrase (for example, 'cracked housing', 'will not power on' or 'leaking seal'). Leave empty if the record describes no failure.",
+      "type": "text"
+    },
+    {
+      "label": "units_affected",
+      "description": "The number of units the customer reports as affected, as a number. Leave empty if the record states no quantity.",
+      "type": "number"
+    },
+    {
+      "label": "injury_or_safety_issue",
+      "description": "True if the record reports an injury, a fire, or another safety hazard. False if the record states that there was none. Leave empty if the record does not mention safety.",
+      "type": "yes_no"
+    },
+    {
+      "label": "customer_request",
+      "description": "What the customer asks for (for example, a refund, a replacement, a repair or an explanation), as a short phrase. Leave empty if the customer makes no request.",
+      "type": "text"
+    }
+  ]
+}

config/templates/nonconformance_note.json

@@ -0,0 +1,48 @@
+{
+  "id": "nonconformance_note",
+  "name": "Inspection or nonconformance note",
+  "description": "Inspection record, nonconformance report (NCR) or shop-floor defect note.",
+  "order": 4,
+  "fields": [
+    {
+      "label": "part_number",
+      "description": "The part number of the inspected item, exactly as written. Leave empty if none is given.",
+      "type": "text"
+    },
+    {
+      "label": "lot_number",
+      "description": "The lot, batch, work order or serial number of the inspected material, exactly as written. Leave empty if none is given.",
+      "type": "text"
+    },
+    {
+      "label": "characteristic",
+      "description": "The feature or characteristic that was found nonconforming (for example, 'bore diameter', 'surface finish' or 'weld penetration'). If several are reported, return the first one. Leave empty if the note reports no nonconformance.",
+      "type": "text"
+    },
+    {
+      "label": "specification",
+      "description": "The requirement for that characteristic, with tolerance and units as written (for example, '25.00 +/- 0.05 mm'). Leave empty if the note states no requirement.",
+      "type": "text"
+    },
+    {
+      "label": "measured_value",
+      "description": "The measured or observed value for that characteristic, with units as written (for example, '25.12 mm'). If several measurements are given, return the one farthest from the requirement. Leave empty if no value is recorded.",
+      "type": "text"
+    },
+    {
+      "label": "quantity_inspected",
+      "description": "The number of units inspected, as a number. Leave empty if not stated.",
+      "type": "number"
+    },
+    {
+      "label": "quantity_nonconforming",
+      "description": "The number of units found nonconforming, as a number. Leave empty if not stated.",
+      "type": "number"
+    },
+    {
+      "label": "disposition",
+      "description": "The disposition of the nonconforming material as one of: use as is, rework, repair, scrap, return to supplier, or hold. If the note uses another term, return it as written. Leave empty if no disposition is recorded.",
+      "type": "text"
+    }
+  ]
+}

config/templates/recall_notice.json

@@ -0,0 +1,48 @@
+{
+  "id": "recall_notice",
+  "name": "Recall notice",
+  "description": "Vehicle safety recall notice, such as an NHTSA recall summary.",
+  "order": 1,
+  "fields": [
+    {
+      "label": "manufacturer",
+      "description": "Name of the company that is recalling the vehicles, as written in the notice. If both a short name and a full name are given, return the full name. Leave empty if no company is named.",
+      "type": "text"
+    },
+    {
+      "label": "defect_summary",
+      "description": "One or two sentences that describe the defect or noncompliance, using only facts stated in the notice. Leave empty if the notice describes no defect.",
+      "type": "text"
+    },
+    {
+      "label": "models",
+      "description": "Every affected vehicle model named in the notice, one entry per model, including the make (for example, 'Acura MDX Type-S'). Do not include model years. Return an empty list if no model is named.",
+      "type": "list"
+    },
+    {
+      "label": "model_years",
+      "description": "The affected model years as written in the notice, one entry per year or year range (for example, '2021-2022'). If several models have different years, give one entry per distinct range. Return an empty list if no model year is stated.",
+      "type": "list"
+    },
+    {
+      "label": "component",
+      "description": "The part or system affected by the defect (for example, 'rearview camera' or 'fuel injection electronic control unit'). Leave empty if the notice does not name one.",
+      "type": "text"
+    },
+    {
+      "label": "fmvss_number",
+      "description": "The number of the Federal Motor Vehicle Safety Standard (FMVSS) that the vehicles fail to comply with, digits only (for example, '111'). Leave empty if the notice cites no FMVSS.",
+      "type": "text"
+    },
+    {
+      "label": "root_cause",
+      "description": "The cause of the defect as stated in the notice (for example, a software error or a supplier manufacturing error). Do not infer a cause. Leave empty if the notice does not state one.",
+      "type": "text"
+    },
+    {
+      "label": "risk",
+      "description": "The safety risk or consequence described in the notice (for example, an increased risk of a crash). Leave empty if the notice does not state one.",
+      "type": "text"
+    }
+  ]
+}

www/app.js

@@ -0,0 +1,142 @@
+// Client-side behaviour: input tabs, the video dialog, and the copy buttons.
+(function() {
+  var INPUT_TABS = ['demo', 'paste', 'textfile', 'pdf', 'scanned', 'image'];
+  var currentTab = 'demo';
+
+  // ---- Input tabs ----------------------------------------------------------
+
+  function sendInputMethod() {
+    if (window.Shiny && Shiny.setInputValue) {
+      Shiny.setInputValue('input_method', currentTab);
+    }
+  }
+
+  function switchInputTab(tab, moveFocus) {
+    if (INPUT_TABS.indexOf(tab) === -1) return;
+    currentTab = tab;
+    INPUT_TABS.forEach(function(t) {
+      var tabEl = document.getElementById('tab-' + t);
+      var panelEl = document.getElementById('panel-' + t);
+      if (!tabEl || !panelEl) return;
+      var selected = (t === tab);
+      tabEl.classList.toggle('active', selected);
+      tabEl.setAttribute('aria-selected', selected ? 'true' : 'false');
+      tabEl.setAttribute('tabindex', selected ? '0' : '-1');
+      panelEl.style.display = selected ? 'block' : 'none';
+      if (selected && moveFocus) tabEl.focus();
+    });
+    sendInputMethod();
+    // Let Shiny render outputs in the panel that just became visible
+    if (window.jQuery) window.jQuery('#panel-' + tab).trigger('shown');
+  }
+  window.switchInputTab = switchInputTab;
+
+  function onTabKeydown(event) {
+    var index = INPUT_TABS.indexOf(currentTab);
+    var next = null;
+    if (event.key === 'ArrowRight' || event.key === 'ArrowDown') {
+      next = INPUT_TABS[(index + 1) % INPUT_TABS.length];
+    } else if (event.key === 'ArrowLeft' || event.key === 'ArrowUp') {
+      next = INPUT_TABS[(index + INPUT_TABS.length - 1) % INPUT_TABS.length];
+    } else if (event.key === 'Home') {
+      next = INPUT_TABS[0];
+    } else if (event.key === 'End') {
+      next = INPUT_TABS[INPUT_TABS.length - 1];
+    }
+    if (next !== null) {
+      event.preventDefault();
+      switchInputTab(next, true);
+    }
+  }
+
+  // ---- Video dialog --------------------------------------------------------
+
+  var videoUrl = 'https://www.youtube.com/embed/y6Uit4Drf9w';
+  var lastFocused = null;
+
+  function videoModal() { return document.getElementById('video-modal'); }
+
+  function openVideo() {
+    var modal = videoModal();
+    lastFocused = document.activeElement;
+    document.getElementById('tutorial-video').src = videoUrl;
+    modal.style.display = 'flex';
+    document.getElementById('close-video-modal').focus();
+  }
+
+  function closeVideo() {
+    var modal = videoModal();
+    if (modal.style.display !== 'flex') return;
+    modal.style.display = 'none';
+    document.getElementById('tutorial-video').src = '';
+    if (lastFocused && lastFocused.focus) lastFocused.focus();
+  }
+
+  // Keep keyboard focus inside the open dialog
+  function trapVideoFocus(event) {
+    if (event.key !== 'Tab') return;
+    var closeBtn = document.getElementById('close-video-modal');
+    var iframe = document.getElementById('tutorial-video');
+    if (event.shiftKey && document.activeElement === closeBtn) {
+      event.preventDefault();
+      iframe.focus();
+    } else if (!event.shiftKey && document.activeElement === iframe) {
+      event.preventDefault();
+      closeBtn.focus();
+    }
+  }
+
+  // ---- Copy buttons --------------------------------------------------------
+
+  function copyFrom(button) {
+    var target = document.getElementById(button.getAttribute('data-target'));
+    if (!target) return;
+    var text = target.textContent;
+    var label = button.getAttribute('data-label') || button.textContent;
+    button.setAttribute('data-label', label);
+    function done(message) {
+      button.textContent = message;
+      window.setTimeout(function() { button.textContent = label; }, 2000);
+    }
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(text).then(
+        function() { done('Copied'); },
+        function() { done('Copy failed. Select the code and copy it manually.'); }
+      );
+    } else {
+      done('Copy is not available. Select the code and copy it manually.');
+    }
+  }
+
+  // ---- Wiring --------------------------------------------------------------
+
+  document.addEventListener('DOMContentLoaded', function() {
+    INPUT_TABS.forEach(function(t) {
+      var tabEl = document.getElementById('tab-' + t);
+      if (!tabEl) return;
+      tabEl.addEventListener('click', function() { switchInputTab(t, false); });
+      tabEl.addEventListener('keydown', onTabKeydown);
+    });
+
+    var modal = videoModal();
+    document.getElementById('open-video-modal').addEventListener('click', openVideo);
+    document.getElementById('close-video-modal').addEventListener('click', closeVideo);
+    modal.addEventListener('click', function(event) {
+      if (event.target === modal) closeVideo();
+    });
+    modal.addEventListener('keydown', trapVideoFocus);
+    document.addEventListener('keydown', function(event) {
+      if (event.key === 'Escape') closeVideo();
+    });
+
+    document.addEventListener('click', function(event) {
+      var button = event.target.closest ? event.target.closest('.copy-btn') : null;
+      if (button) copyFrom(button);
+    });
+  });
+
+  // Tell the server which tab is open as soon as the session starts
+  if (window.jQuery) {
+    window.jQuery(document).on('shiny:connected', sendInputMethod);
+  }
+})();

www/miami-theme.css

@@ -205,18 +205,22 @@ body {
 }
 
 .video-modal-close {
+  background: none;
+  border: none;
+  padding: 0 4px;
   position: absolute;
   top: 10px;
   right: 18px;
   font-size: 32px;
   font-weight: bold;
-  color: var(--miami-medium-tan);
+  color: #666;
   cursor: pointer;
   transition: color 0.2s;
   line-height: 1;
 }
 
-.video-modal-close:hover {
+.video-modal-close:hover,
+.video-modal-close:focus {
   color: var(--miami-red);
 }
 
@@ -248,7 +252,8 @@ body {
 .form-control:focus {
   border-color: var(--miami-red);
   box-shadow: 0 0 0 3px rgba(196, 18, 48, 0.15);
-  outline: none;
+  outline: 2px solid var(--miami-red);
+  outline-offset: 1px;
 }
 
 /* Text area styling */
@@ -510,7 +515,8 @@ hr {
 }
 
 /* File input browse button - make it red */
-.input-panel .btn-file {
+.input-panel .btn-file,
+.fields-file-row .btn-file {
   background-color: var(--miami-red);
   color: var(--miami-white);
   border: none;
@@ -519,13 +525,15 @@ hr {
 }
 
 .input-panel .btn-file:hover,
-.input-panel .btn-file:focus {
+.input-panel .btn-file:focus,
+.fields-file-row .btn-file:hover,
+.fields-file-row .btn-file:focus {
   background-color: var(--miami-dark-red);
   color: var(--miami-white);
 }
 
-/* Image limit note */
-.image-limit-note {
+/* Page and image limit note */
+.limit-note {
   background-color: rgba(239, 219, 114, 0.3);
   border: 1px solid var(--miami-yellow);
   border-radius: 4px;
@@ -577,6 +585,149 @@ hr {
   margin-top: 8px;
 }
 
+/* Visible keyboard focus for every interactive element */
+a:focus-visible,
+button:focus-visible,
+summary:focus-visible,
+select:focus-visible,
+.btn:focus-visible,
+.input-tab:focus-visible,
+[tabindex]:focus-visible {
+  outline: 3px solid var(--miami-black);
+  outline-offset: 2px;
+}
+
+.app-header a:focus-visible {
+  outline-color: var(--miami-white);
+}
+
+/* Heading (or button) with its "?" help button */
+.heading-with-help {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin-bottom: 15px;
+}
+
+.heading-with-help.section-heading {
+  padding-bottom: 10px;
+}
+
+.help-btn {
+  flex: none;
+  width: 26px;
+  height: 26px;
+  padding: 0;
+  margin: 0;
+  border: 1px solid var(--miami-red);
+  border-radius: 50%;
+  background-color: var(--miami-white);
+  color: var(--miami-red);
+  font-weight: 700;
+  font-size: 0.9em;
+  line-height: 1;
+}
+
+.help-btn:hover,
+.help-btn:focus {
+  background-color: var(--miami-red);
+  color: var(--miami-white);
+}
+
+.heading-with-help .btn-primary {
+  margin: 0;
+}
+
+/* Help dialog */
+.modal-title {
+  color: var(--miami-red);
+  font-weight: 600;
+}
+
+.modal-body p {
+  line-height: 1.5;
+}
+
+/* Field definitions */
+.field-card {
+  background-color: var(--miami-light-tan);
+  padding: 12px;
+  border-radius: 6px;
+  margin-bottom: 12px;
+}
+
+.field-card textarea.form-control {
+  min-height: 70px;
+}
+
+.field-card .form-group {
+  margin-bottom: 8px;
+}
+
+.template-row {
+  display: flex;
+  align-items: flex-end;
+  gap: 10px;
+}
+
+.template-row .form-group {
+  flex: 1;
+  margin-bottom: 0;
+}
+
+.template-row .btn {
+  margin: 0;
+}
+
+.fields-file-row {
+  margin-top: 5px;
+}
+
+.fields-file-row .shiny-input-container {
+  width: 100%;
+  margin-top: 12px;
+}
+
+/* Results */
+.results-summary {
+  border-left: 4px solid var(--miami-medium-tan);
+  background-color: var(--miami-light-tan);
+  padding: 10px 14px;
+  margin-bottom: 15px;
+  border-radius: 0 6px 6px 0;
+}
+
+.results-summary.has-failures {
+  border-left-color: var(--miami-red);
+}
+
+.results-table-wrapper {
+  overflow-x: auto;
+}
+
+/* Reproduce in code */
+.code-details {
+  border: 1px solid var(--miami-medium-tan);
+  border-radius: 6px;
+  padding: 10px 14px;
+  margin-top: 10px;
+}
+
+.code-details summary {
+  cursor: pointer;
+  font-weight: 600;
+}
+
+.code-details pre {
+  margin-top: 10px;
+  max-height: 420px;
+  overflow: auto;
+  white-space: pre;
+  font-size: 0.85em;
+  background-color: var(--miami-light-tan);
+  border: none;
+}
+
 /* Responsive adjustments */
 @media (max-width: 768px) {
   .header-content {