andromeda_cms 0.1.0-x86_64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7f68ee6edd705507759d73adf1053b7fd365b16b5189f8556f7481f8c85e6da3
+  data.tar.gz: 6d39ddf7cc77ab9b486350b1aa20b91e3a129dfb72ebe30b70a6a9f798546204
+SHA512:
+  metadata.gz: 9aa17d085177c1cca62daf1969b2dd1c2db6f19485c31381dea832b24073f24bba4e680c7c6361f32a31297bc54b7e27e5fcae9d48e26f72de8bdee664fdb2d0
+  data.tar.gz: 7b314110d6f9674f6f0be66269dd286282fa0af5ef6ba670980719ef9a65760d8137a496c956c22a5def3666149091e63408b9ac38626062eceddd649f00c539

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-27
+
+### Added
+
+- Astro-compatible content collections: entry classes with a schema DSL, an
+  Astro-compatible id scheme, and queries (`all`/`find`/`where`/`order`/scopes).
+- Markdown and MDX conversion through Sätteri, the engine Astro 7 uses by
+  default, with GFM, smart punctuation, github-slugger heading ids and Rouge
+  syntax highlighting.
+- MDX components rendered as Rails partials, including props, children and
+  named slots.
+- Frontmatter parsing with Astro-compatible semantics: YAML 1.2 scalars, TOML
+  (`+++`), and line numbers preserved for error messages.
+- Build pipeline: `andromeda:build` (hooked into `assets:precompile`),
+  `andromeda:check`, `andromeda:fix` and `andromeda:clobber`, writing to
+  `.andromeda/`; on-demand conversion in development.
+- Images referenced from content published through the asset pipeline.
+- View helpers: `andromeda_content`, `andromeda_toc`, `andromeda_meta_tags`,
+  `andromeda_image_url`.
+- Generators: `andromeda:install`, `andromeda:collection`,
+  `andromeda:component` and `andromeda:import_astro`.
+
+[0.1.0]: https://github.com/AndromedaCMS/andromeda_cms/releases/tag/v0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing
+
+**Andromeda is open source, but not open contribution.**
+
+The code is MIT licensed: use it, fork it, change it, ship it. What this
+project does not do is take patches into its own implementation. That keeps the
+copyright in one place, which in turn keeps relicensing, redistribution and
+long-term maintenance decisions simple — the same reasoning
+[SQLite](https://www.sqlite.org/copyright.html) gives for its own policy.
+
+So pull requests are generally closed unfixed, and that is not a judgement on
+the code in them. Please do not spend an afternoon on a patch expecting it to be
+merged.
+
+## What helps most
+
+**Bug reports.** They are the highest-value contribution here, and they are
+always welcome. A good one includes:
+
+- the versions of Ruby, Rails and `andromeda_cms`
+- the content file that triggers it, reduced to the smallest thing that still
+  fails (frontmatter plus a few lines of body is usually enough)
+- what you expected, and what happened, including the full error message
+- for a compatibility problem: what Astro does with the same file
+
+**Compatibility gaps.** Content that works in Astro and does not work here is a
+bug, even if the error message looks reasonable. Say which Astro version the
+content came from.
+
+**Documentation that is wrong or missing.** Point at the page and say what was
+confusing; that is enough.
+
+**Ideas.** Open an issue describing the problem you hit rather than the
+implementation you have in mind — the problem is the part that is hard to
+guess from the outside.
+
+## What to expect
+
+Issues are read. Not every one becomes a change: this gem deliberately keeps a
+small surface, and compatibility with Astro's behaviour outranks new options.
+When something is declined, the issue will say why.
+
+## Forking
+
+Forking is a legitimate outcome, not a hostile one. If this project will not go
+where you need it to go, the MIT licence exists precisely so you can take it
+there yourself.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LIMHAUS Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,276 @@
+# Andromeda
+
+Astro-compatible content collections for Ruby on Rails.
+
+[Documentation](https://www.andromedacms.dev/docs) · [Changelog](CHANGELOG.md)
+
+Copy the `.md` and `.mdx` files from an [Astro](https://astro.build) project
+into `app/content/`, and Andromeda validates their frontmatter against a schema
+and renders them as ordinary Rails pages. The heavy work — parsing Markdown and
+MDX and expanding components — happens once at deploy time; requests only read
+the result.
+
+> **Status: pre-release.** The API is not stable yet.
+
+## Why
+
+Adding a blog, docs or a marketing site to a Rails app has usually meant one of
+three things: standing up a separate Astro or Next.js project, installing a CMS
+gem with its own tables and admin screens, or wiring up a headless CMS over
+HTTP. Andromeda takes Astro's content model — collections, schemas, MDX
+components — and makes it a gem, so the content lives next to the application
+that already has your authentication, your layouts and your deploy pipeline.
+
+### Files are the interface
+
+Those three options all put content behind a database and a screen. That made
+sense while people were the only ones writing. They are not any more: much of
+the writing, editing and restructuring now happens with an assistant in the
+loop, and an assistant is good at exactly one thing here — reading and writing
+files in a repository it can already see. Pointing it at a CMS means first
+building it an API or an MCP server, giving that its own authentication, and
+keeping it in sync with the schema. A second system, to serve the first.
+
+Content as files needs none of that. Adding a post is adding a file, editing
+one is an edit, removing one is `rm`. The change arrives as a diff, is reviewed
+like any other, and ships with the deploy that carried it — and the tool doing
+the writing needs no integration at all, because it already has the repository.
+Of everything in Astro's design, this is the part that looks most like where
+things are going.
+
+### Alongside Astro, not against it
+
+I like [Astro](https://astro.build), and I have a great deal of respect for the
+team behind it. For a static site I still reach for it. But when a site needs
+sessions, forms, background jobs and a database, I want Rails. Andromeda exists
+so that this is not a choice between the two: the collection stays the same
+directory of files, parsed by the same engine Astro 7 uses, and moving it into
+Rails is a copy.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "andromeda_cms"
+```
+
+```bash
+bundle install
+bin/rails generate andromeda:install
+```
+
+Ruby 3.2+ and Rails 8.0+. The gem ships precompiled binaries for common
+platforms, so no Rust toolchain is needed to install it.
+
+## Getting started
+
+```bash
+bin/rails generate andromeda:collection blog title:string pub_date:date
+```
+
+That writes an entry class, a controller, views, a route and a first post:
+
+```ruby
+# app/models/content/blog.rb
+module Content
+  class Blog < Andromeda::Entry
+    collection :blog, base: "app/content/blog", pattern: "**/*.{md,mdx}"
+
+    attribute :title, :string
+    attribute :pub_date, :date
+
+    # scope :published, -> { where(draft: false) }
+  end
+end
+```
+
+```ruby
+# app/controllers/blog_controller.rb
+class BlogController < ApplicationController
+  def index
+    @entries = Content::Blog.all.order(pub_date: :desc)
+  end
+
+  def show
+    @entry = Content::Blog.find(params[:slug])
+  end
+end
+```
+
+```erb
+<%# app/views/blog/show.html.erb %>
+<article>
+  <h1><%= @entry.title %></h1>
+  <%= andromeda_content @entry %>
+</article>
+```
+
+From there it is your code. A typical next step is to make fields mandatory,
+add a draft flag, and add a table of contents:
+
+```ruby
+attribute :title, :string, required: true
+attribute :pub_date, :date, required: true
+attribute :draft, :boolean, default: false
+
+scope :published, -> { where(draft: false) }
+```
+
+```erb
+<%= andromeda_toc @entry %>
+```
+
+An unknown slug raises `Andromeda::EntryNotFound`, which Rails answers with a
+404.
+
+Pages are ordinary Rails, so layouts, `current_user`, CSRF tokens, caching and
+authorization all behave exactly as they normally do.
+
+## Content
+
+```markdown
+---
+title: Hello world
+pub_date: 2026-09-01
+tags: [rails, astro]
+---
+
+## Getting started
+
+Ordinary GFM Markdown, with smart punctuation and syntax highlighting.
+```
+
+Frontmatter is validated against the entry class: a missing `title` or an
+unparseable date fails the build with the file name and line number, rather
+than surfacing as `nil` in a view.
+
+### MDX components
+
+MDX components map to Rails partials — no ViewComponent dependency:
+
+```mdx
+import Callout from 'content_components/callout';
+
+<Callout type="tip" title="Note">
+  The body is **Markdown** too.
+</Callout>
+```
+
+```erb
+<%# app/views/content_components/_callout.html.erb %>
+<aside class="callout callout--<%= local_assigns.fetch(:type, "note") %>">
+  <% if local_assigns[:title] %><p class="callout__title"><%= title %></p><% end %>
+  <%= content %>
+</aside>
+```
+
+Props arrive as locals (`camelCase` becomes `snake_case`), the tag's children
+arrive as `content`, and `<Fragment slot="header">` becomes a `header` local.
+`bin/rails generate andromeda:component Callout type title` writes the stub.
+
+### Images
+
+Put an image next to the entry and reference it relatively:
+
+```
+app/content/blog/my-post/
+├── index.md
+└── cover.png
+```
+
+```markdown
+![Cover](./cover.png)
+```
+
+Referenced images are copied into `app/assets/builds/andromeda/` during the
+build and served, digest-stamped, by the asset pipeline. Images the app
+already ships (`app/assets/images/logo.png`, written as `logo.png`) resolve
+through the pipeline too; anything under `public/` or on another host is left
+untouched. Declare a frontmatter image with `attribute :hero_image, :image`
+and render it with `andromeda_image_url`.
+
+## Development and deployment
+
+```
+development:  request → entry is converted on demand when its source changed
+production:   deploy  → andromeda:build writes .andromeda/, requests only read it
+```
+
+There is no watcher process to run: in development a file is converted the
+first time something asks for it after it changes. In production the parser
+never runs while serving a request, and an unbuilt entry raises an error that
+names the fix instead of silently converting.
+
+`andromeda:build` is hooked into `assets:precompile`, so the Rails 8 Dockerfile
+(and Kamal, and Heroku) already runs it. `.andromeda/` is a build artifact:
+the installer adds it to `.gitignore` and `.dockerignore`.
+
+| Task | What it does |
+|------|--------------|
+| `andromeda:build` | Convert every entry into `.andromeda/` (runs during `assets:precompile`) |
+| `andromeda:check` | Report schema problems, missing components and non-snake_case keys; writes nothing (for CI) |
+| `andromeda:fix` | Rewrite non-snake_case frontmatter keys in place |
+| `andromeda:clobber` | Remove `.andromeda/` (runs during `assets:clobber`) |
+
+## Migrating from Astro
+
+```bash
+bin/rails generate andromeda:import_astro ../my-astro-site
+```
+
+It copies `src/content` and `src/assets`, rewrites frontmatter keys to
+snake_case and MDX imports to partial paths, converts `content.config.ts` into
+entry classes, generates stubs for the components your content imports, and
+prints what still needs a human. `--dry-run` shows the plan without writing.
+
+Astro's own [`examples/blog`](https://github.com/withastro/astro/tree/main/examples/blog)
+imports and renders unchanged; that is a test in this repository.
+
+## Compatibility
+
+Andromeda targets Astro 7 and later and uses
+[Sätteri](https://github.com/bruits/satteri) — the Markdown and MDX engine
+Astro 7 uses by default — so content is parsed by the same engine that parsed
+it in Astro. Heading ids use github-slugger, `headings` has the same shape as
+Astro's `render()`, and entry ids follow Astro's `glob()` loader rules.
+
+The goal is that content copied from an Astro project loads without errors and
+displays. Byte-identical output is a non-goal: syntax highlighting uses Rouge
+rather than Shiki (same markup shape, approximate colours), and images are
+served by the asset pipeline rather than Astro's image service.
+
+Not supported: Astro's pages and routing, islands and `client:*` directives,
+remark/rehype plugins, and arbitrary JavaScript in MDX expressions (literals,
+`{frontmatter.x}` and comments are evaluated; anything else is an error rather
+than a silent drop).
+
+## Development
+
+```bash
+bin/setup            # or: bundle install
+bundle exec rake     # compiles the Rust extension, then runs the tests
+bundle exec rake test:corpus  # after test/fetch_corpus.sh: parse ~370 real Astro files
+```
+
+## Troubleshooting
+
+**`ArgumentError: wrong number of arguments (given 2, expected 1)` from `JSON.parse`.**
+Not this gem: Rails 8.1 calls `JSON.parse` with a positional options hash, which
+version 3 of the `json` gem no longer accepts, and decrypting a session cookie
+hits that path — so pages fail only once a session exists. Pin the `json` gem
+until Rails ships a fix:
+
+```ruby
+# Gemfile
+gem "json", "~> 2.9"
+```
+
+## Contributing
+
+Bug reports are welcome; patches are not. Andromeda is open source but not open
+contribution — see [CONTRIBUTING.md](CONTRIBUTING.md) for why, and for what a
+useful bug report contains.
+
+## License
+
+Copyright (c) 2026 [LIMHAUS Inc.](https://www.limhaus.com/). Released under the [MIT License](LICENSE.txt).

data/lib/andromeda/assets.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Andromeda
+  # Publishes images that live next to content so the asset pipeline can serve
+  # them.
+  #
+  # Adding `app/content` to Propshaft's load path would be shorter, but
+  # Propshaft serves *every* file in a load path — the Markdown sources
+  # themselves would become public URLs. Copying only the referenced images
+  # into `app/assets/builds/andromeda/` keeps the content directory private and
+  # mirrors how tailwindcss-rails treats `app/assets/builds`.
+  module Assets
+    # Relative to `app/assets/builds`, and therefore also the prefix of the
+    # logical asset path the view helpers resolve.
+    DIRECTORY = "andromeda"
+
+    module_function
+
+    # Copies `source` under the builds directory and returns its logical path
+    # (what `asset_path` takes), or nil when the file is not a publishable
+    # asset under the content root.
+    #
+    # @param source [String] absolute path to a file inside the content root.
+    # @param content_root [String] the collection's base directory.
+    # @return [String, nil] e.g. "andromeda/blog/post/cover.png".
+    def publish(source, content_root:)
+      logical = logical_path(source, content_root: content_root)
+      return nil if logical.nil?
+
+      return logical if asset_pipeline_path(File.expand_path(source))
+
+      destination = File.join(builds_root, logical)
+      FileUtils.mkdir_p(File.dirname(destination))
+      # Copying only when the content changed keeps `andromeda:build` cheap on
+      # image-heavy sites, where the copy would otherwise dominate the run.
+      FileUtils.cp(source, destination) unless identical?(source, destination)
+      logical
+    end
+
+    # Conversion cannot know an image's final URL: Propshaft only learns the
+    # digest when `assets:precompile` runs, which is *after* `andromeda:build`
+    # (it depends on it), and in development the load path is indexed at boot.
+    # So the stored HTML carries this marker and the view resolves it, which
+    # costs one gsub per render and keeps digests correct in both environments.
+    MARKER = "andromeda-asset:"
+
+    def marker_for(logical_path)
+      "#{MARKER}#{logical_path}"
+    end
+
+    # @param html [String] stored HTML, possibly containing markers.
+    # @return [String] the same HTML with every marker replaced by a real URL.
+    def resolve(html)
+      return html unless html.include?(MARKER)
+
+      html.gsub(/#{Regexp.escape(MARKER)}([^"'\s)]+)/) { url_for(Regexp.last_match(1)) }
+    end
+
+    # @return [String] a URL for a logical path, digest-stamped when the asset
+    #   pipeline is available and a plain /assets path otherwise.
+    def url_for(logical_path)
+      if defined?(::ActionController::Base)
+        ::ActionController::Base.helpers.asset_path(logical_path)
+      else
+        File.join("/assets", logical_path)
+      end
+    rescue StandardError
+      # An image that has not been indexed yet (a fresh copy in development,
+      # or a precompile that has not run) must not take the whole page down.
+      File.join("/assets", logical_path)
+    end
+
+    def logical_path(source, content_root:)
+      source = File.expand_path(source)
+      root = File.expand_path(content_root)
+      project = project_root
+
+      # Nothing outside the project (or the content root, when a collection
+      # lives elsewhere) may be published: a `../` chain in a content file
+      # must not expose an arbitrary file on the machine.
+      inside = [project, root].any? { |boundary| source.start_with?("#{boundary}#{File::SEPARATOR}") }
+      return nil unless inside
+
+      if source.start_with?("#{root}#{File::SEPARATOR}")
+        File.join(DIRECTORY, File.basename(root), source.delete_prefix("#{root}#{File::SEPARATOR}"))
+      elsif (asset_relative = asset_pipeline_path(source))
+        asset_relative
+      else
+        # Somewhere else in the project (Astro's own example keeps hero
+        # images in `src/assets`): mirrored under the build directory so it
+        # still gets a digest, with the project-relative path kept to avoid
+        # collisions between same-named files.
+        File.join(DIRECTORY, "project", source.delete_prefix("#{project}#{File::SEPARATOR}"))
+      end
+    end
+
+    # A file the asset pipeline already serves needs no copy -- returning its
+    # logical path lets `asset_path` digest the original in place.
+    def asset_pipeline_path(source)
+      assets_root = File.join(project_root, "app/assets")
+      return nil unless source.start_with?("#{assets_root}#{File::SEPARATOR}")
+
+      relative = source.delete_prefix("#{assets_root}#{File::SEPARATOR}")
+      # Propshaft's load path is each directory under app/assets, so the
+      # first segment (images/, stylesheets/, builds/, ...) is not part of
+      # the logical path -- except for files sitting directly in app/assets.
+      relative.include?(File::SEPARATOR) ? relative.split(File::SEPARATOR, 2).last : relative
+    end
+
+    def project_root
+      Andromeda.config.project_root
+    end
+
+    def builds_root
+      File.join(project_root, "app/assets/builds")
+    end
+
+    # Compares bytes, not timestamps: a checkout or an extracted archive can
+    # give a changed image an old mtime, and a same-sized edit would then
+    # never be copied. The size check keeps the common case cheap.
+    def identical?(source, destination)
+      File.exist?(destination) && File.size(source) == File.size(destination) &&
+        FileUtils.compare_file(source, destination)
+    end
+  end
+end

data/lib/andromeda/check.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Andromeda
+  # The read-only counterpart of `andromeda:build`, for CI.
+  #
+  # It deliberately runs the *same* conversion the build runs, into a
+  # throwaway store, rather than re-implementing a subset of the checks: a
+  # check that passes while the build fails would be worse than no check at
+  # all. Everything it finds is reported together, because fixing content
+  # one error per CI run is miserable.
+  module Check
+    module_function
+
+    # @param entry_classes [Array<Class>] defaults to every registered collection.
+    # @return [Array<String>] human-readable problems; empty when content is healthy.
+    def run(entry_classes = Andromeda::Pipeline.default_entry_classes)
+      problems = []
+
+      entry_classes.each do |entry_class|
+        entries = load_entries(entry_class, problems)
+        next if entries.nil?
+
+        entries.each do |entry|
+          problems.concat(frontmatter_style_problems(entry))
+          problems.concat(conversion_problems(entry))
+        end
+      end
+
+      problems
+    end
+
+    def load_entries(entry_class, problems)
+      entry_class.reload!
+      entry_class.all.to_a
+    rescue Andromeda::LoaderError => e
+      problems.concat(e.messages.map { |message| "[#{entry_class.collection_name}] #{message}" })
+      nil
+    rescue Andromeda::Error => e
+      problems << "[#{entry_class.collection_name}] #{e.message}"
+      nil
+    end
+
+    # Non-snake_case keys are legal YAML but will not reach a declared
+    # attribute, so they are reported here with the command that rewrites
+    # them instead of failing later as a missing required field.
+    def frontmatter_style_problems(entry)
+      offenders = Andromeda::Frontmatter.non_snake_case_keys(entry.data)
+      return [] if offenders.empty?
+
+      offenders.map do |key|
+        "#{entry.file_path}: frontmatter key #{key} is not snake_case; run `bin/rails andromeda:fix`"
+      end
+    end
+
+    def conversion_problems(entry)
+      Andromeda::Pipeline.new(store: NullStore.new, mode: :development).convert(entry)
+      []
+    rescue Andromeda::Error => e
+      ["#{entry.file_path}: #{e.message}"]
+    end
+
+    # Swallows the writes so a check can never leave `.andromeda/` in a
+    # half-built state that a later production boot would happily serve.
+    class NullStore
+      def write_entry(*) = nil
+      def read_entry(*) = nil
+      def read_index(*) = nil
+      def replace_collection!(*) = nil
+    end
+  end
+end

data/lib/andromeda/components/errors.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Andromeda
+  class Components
+    # Raised when a component tag resolves to a partial name (by explicit
+    # registration, import path, or naming convention) but no such partial
+    # exists on disk. Names the tag, the content file, the line, and the
+    # exact path to create so the error is actionable straight out
+    # of a build log or a development error page, without having to go
+    # spelunking through the resolution rules to figure out what Andromeda
+    # was even looking for.
+    class MissingPartialError < Andromeda::Error
+      attr_reader :tag_name, :path, :line, :expected_path
+
+      def initialize(tag_name, path:, line:, expected_path:)
+        @tag_name = tag_name
+        @path = path
+        @line = line
+        @expected_path = expected_path
+
+        location = [path, line].compact.join(":")
+        super(
+          "#{location}: <#{tag_name}> has no matching partial. Create #{expected_path} " \
+          "(e.g. `rails g andromeda:component #{tag_name}`), register it explicitly with " \
+          "`Andromeda::Components.register(#{tag_name.to_s.inspect}, \"partial/path\")`, or " \
+          "import it from a path that points at an existing partial."
+        )
+      end
+    end
+
+    # Raised for a member-expression tag name (`<Tabs.Item>`) that
+    # was not explicitly registered. Convention-based resolution can't turn
+    # a dotted name into a partial path, and guessing would be more
+    # surprising than just saying so -- named-slot components (the
+    # `Tabs`/`Fragment slot=` pattern) cover the common case this syntax is
+    # usually reaching for.
+    class InvalidComponentNameError < Andromeda::Error
+      attr_reader :tag_name, :path, :line
+
+      def initialize(tag_name, path:, line:)
+        @tag_name = tag_name
+        @path = path
+        @line = line
+
+        location = [path, line].compact.join(":")
+        super(
+          "#{location}: <#{tag_name}> looks like a member expression (e.g. `Tabs.Item`), " \
+          "which Andromeda does not resolve by naming convention in v0 -- register it " \
+          "explicitly with `Andromeda::Components.register(#{tag_name.to_s.inspect}, " \
+          "\"partial/path\")`"
+        )
+      end
+    end
+
+    # Raised for a `{...}` expression that is neither a literal,
+    # a `frontmatter.x` reference, nor a comment -- the
+    # v0 static-expression subset. Everything else (`.map()`,
+    # ternaries, template interpolation, arrow functions, `await`, ...) is
+    # explicitly out of scope, and silently dropping it would hide content
+    # bugs, so this raises naming the file/line rather than degrading
+    # quietly.
+    class UnsupportedExpressionError < Andromeda::Error
+      attr_reader :source, :path, :line, :column
+
+      def initialize(source, path:, line:, column:)
+        @source = source
+        @path = path
+        @line = line
+        @column = column
+
+        location = [path, line].compact.join(":")
+        super(
+          "#{location}: unsupported MDX expression `{#{source}}` -- only literals, " \
+          "`frontmatter.x` references, and comments are supported"
+        )
+      end
+    end
+
+    # Raised when there is no Rails renderer to hand a partial to -- either
+    # `ApplicationController` is not defined (Rails is not loaded / not
+    # booted yet) and no `view:` was passed explicitly to
+    # `Andromeda::Components.new`. Components render through
+    # `ApplicationController.renderer`; there is no non-Rails fallback in
+    # v0 (a plain ActionView::Base renderer setup is enough of a project on
+    # its own -- view paths, compiled template caching, helpers -- that it
+    # is deferred rather than half-done here).
+    class NoRendererAvailableError < Andromeda::Error
+      def initialize(path)
+        super(
+          "no Rails renderer available to render MDX components in " \
+          "#{path || "(unknown file)"} -- define ApplicationController, or pass `view:` " \
+          "explicitly to Andromeda::Components.new"
+        )
+      end
+    end
+  end
+end