Date: 2026-08-21

Status: Proposed. This document records what GitHub's card system actually

does, measured from production responses, and specifies how OpenAgents builds

its own version with strictly more information per card.

Status: Implemented. Meta tags ship on every public page; the signed,

content-versioned card endpoint serves repository, issue, blob, and commit

cards; rasterization runs through librsvg with a committed fallback card when

the binary is absent. One operations requirement remains: fleet images need

`librsvg2-bin` (and, for exact brand type, the Geist TTFs) installed — until

then nodes serve the fallback card by design.

## What links to our pages look like today

## Delivery sequence

1. **Meta tags plus the static brand card.** No new dependencies, immediate

   improvement everywhere links are shared. Ships alone.

2. **Repository and issue cards.** Lands the SVG pipeline, the signed

   endpoint, the rasterizer requirement in the release image, and the two

   highest-value templates.

3. **Blob and commit cards.** The beyond-GitHub information layer.

Phase 2 is gated on the release-image change shipping to staging first,

since a node without `rsvg-convert` silently serves the fallback card — a

degradation worth catching in a staging check rather than in production

analytics.

All three phases shipped together on 2026-08-21: the meta-tag layer, the

signed endpoint with the SVG-to-PNG pipeline, and the deep-surface cards.

The implementation notes below record what landed and where.

1. **Meta tags plus the static brand card.** `Layouts.og_tags/1` renders the

   block in the root layout; views without a card get honest site-level

   tags pointing at the committed brand PNG.

2. **Repository and issue cards.** `OpenAgentsWeb.OG` builds cards from page

   data, signs content-versioned URLs, and

   `OpenAgentsWeb.OgImageController` renders them through

   `OG.Templates` + `OG.Rasterizer` (librsvg port, concurrency-limited,

   hard timeout).

3. **Blob and commit cards.** The beyond-GitHub information layer: language,

   size, line count, and ref for files; subject, author, and changed-file

   count for commits.

Remaining operations work, tracked here so it cannot be forgotten:

* Add `librsvg2-bin` (and optionally the Geist TTF faces) to the release

  image. Until that lands, production nodes serve the fallback card for all

  dynamic URLs — correct, branded, but generic.

* The staging check should assert a dynamic card URL returns bytes other

  than the committed fallback, proving rasterization end to end.

  @foreign_key_type :binary_id

  @timestamps_opts [type: :utc_datetime_usec]

  @reserved_slugs ~w(

    admin api assets auth changelog chat components computers controller data dev device docs git

    admin api assets auth changelog chat components computers controller data dev device docs git og

    health healthz leaderboard machines memory repositories settings status voice

  )

  def documented_modules do

    %{

      OpenAgentsWeb.UI => [],

      OpenAgentsWeb.Layouts => [:app, :flash_group],

      # og_tags renders head metadata for crawlers, not a visible surface, so

      # it has no demoable page.

      OpenAgentsWeb.Layouts => [:app, :flash_group, :og_tags],

      # graph_defs/1 emits marker definitions into a parent graph surface; it

      # renders nothing on its own, so it has no demoable page. graph_surface/1

      # is the host element and is demoed through the components that use it.

    end

  end

  @doc """

  The `og:*` / `twitter:*` block for the root layout.

  Views that build an `OpenAgentsWeb.OG` card assign `:og` (via `OG.meta/2`)

  and this renders it; every other page gets honest site-level tags rather

  than nothing. Crawlers read the initial server-rendered HTML, so these tags

  ride the first paint only — exactly where they are consumed.

  """

  attr :og, :map, default: nil, doc: "an `OpenAgentsWeb.OG.meta/2` map"

  def og_tags(assigns) do

    og =

      assigns[:og] ||

        %{

          title: "OpenAgents",

          description: "Code hosting, issues, and projects on the agent-native forge.",

          type: "website",

          url: OpenAgentsWeb.OG.site_url(),

          image_url: OpenAgentsWeb.OG.static_card_url(),

          alt: "OpenAgents — code hosting, issues, and projects."

        }

    assigns = assign(assigns, :og, og)

    ~H"""

    <meta property="og:site_name" content="OpenAgents" />

    <meta property="og:type" content={@og.type} />

    <meta property="og:title" content={@og.title} />

    <meta property="og:description" content={@og.description} />

    <meta property="og:url" content={@og.url} />

    <meta property="og:image" content={@og.image_url} />

    <meta property="og:image:width" content="1200" />

    <meta property="og:image:height" content="630" />

    <meta property="og:image:alt" content={@og.alt} />

    <meta name="twitter:card" content="summary_large_image" />

    <meta name="twitter:title" content={@og.title} />

    <meta name="twitter:description" content={@og.description} />

    <meta name="twitter:image" content={@og.image_url} />

    """

  end

  @doc """

  One browser analytics identity field from the session-written map, or nil.

    which applies it to `default` as well: a page with no title of its own

    rendered the brand twice. --%>

    <.live_title default="OpenAgents" phx-no-format>{page_title(assigns)}</.live_title>

    <Layouts.og_tags og={assigns[:og]} />

    <%!-- The faces the first paint actually uses, fetched in parallel with the

    stylesheet instead of after it. Every face is `font-display: swap`, so one

    arriving late re-lays-out text that is already on screen -- and the hero

defmodule OpenAgentsWeb.OgImageController do

  @moduledoc """

  Serves server-generated Open Graph card PNGs.

  Contract, from `docs/2026-08-21-open-graph-cards.md`:

    * Every request path is HMAC-signed (`?sig=`); an invalid or missing

      signature is the same 404 as everything else this endpoint refuses.

    * Repositories resolve through the public visibility predicate only. A

      private repository, a missing repository, and a bad signature are

      indistinguishable.

    * The version segment is advisory: it exists so a page's emitted URL is

      content-addressed and caches immutably. The controller always renders

      current data for any well-formed request, so stale shared links heal

      instead of pinning old facts.

    * When rasterization is unavailable, busy, or fails, the committed

      fallback card ships under identical headers — previews degrade,

      nothing errors.

  """

  use OpenAgentsWeb, :controller

  require Logger

  alias OpenAgents.Forge

  alias OpenAgents.Forge.Browse

  alias OpenAgents.Issues

  alias OpenAgents.Repositories

  alias OpenAgentsWeb.{OG, RepositoryAccess}

  @cache_control "public, max-age=21600, immutable"

  @not_found_cache_control "public, max-age=60"

  # Last-resort bytes if even the committed fallback asset cannot be read: a

  # valid transparent 1x1 PNG keeps responses well-formed.

  @transparent_png Base.decode64!(

                     "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="

                   )

  ## Actions -------------------------------------------------------------------

  def static(conn, _params) do

    send_png(conn)

  end

  def repo(conn, params) do

    authorize_and_run(conn, params, fn owner, name ->

      with {:ok, repository} <- public_repository(owner, name) do

        OG.repo_card_for(repository)

      else

        _error -> :error

      end

    end)

  end

  def issue(conn, params) do

    authorize_and_run(conn, params, fn owner, name ->

      with {number, ""} <- Integer.parse(strip_png(params["number"])),

           %Issues.Issue{} = issue <-

             safe(fn -> Issues.get_issue_by_path!(owner, name, number) end) do

        OG.issue(owner, name, issue)

      else

        _error -> :error

      end

    end)

  end

  def commit(conn, params) do

    authorize_and_run(conn, params, fn owner, name ->

      sha = strip_png(params["sha"])

      with {:ok, repository} <- public_repository(owner, name),

           true <- Forge.enabled?(),

           true <- Browse.valid_ref?(sha),

           {:ok, commit} <- safe(fn -> Browse.commit(repository, sha) end) do

        files =

          case safe(fn -> Browse.changed_files(repository, commit.sha) end) do

            {:ok, list} when is_list(list) -> list

            _other -> nil

          end

        OG.commit(owner, name, commit, files && length(files))

      else

        _error -> :error

      end

    end)

  end

  # The blob card must never show what the anonymous file page would not:

  # the same disclosure gate as `OpenAgentsWeb.CodeBlobLive` runs here, with

  # no user (crawlers carry no session).

  def blob(conn, params) do

    authorize_and_run(conn, params, fn owner, name ->

      ref = strip_png(params["ref"])

      path = joined_path(params["path"])

      with {:ok, repository} <- public_repository(owner, name),

           true <- Forge.enabled?() and repository.lifecycle_state == "ready",

           true <- Browse.valid_ref?(ref) and Browse.valid_path?(path),

           {:ok, sha} <- safe(fn -> Browse.resolve_commit(repository, ref) end),

           head <- resolved_head(repository),

           true <- RepositoryAccess.allows_file?(repository, nil, path, sha, head),

           {:ok, blob_info} <- safe(fn -> Browse.blob(repository, sha, path) end) do

        OG.blob(owner, name, path, %{

          ref: ref,

          size: blob_info.size,

          lines: blob_lines(blob_info),

          truncated: blob_info.truncated

        })

      else

        _refused -> :error

      end

    end)

  end

  ## Pipeline ------------------------------------------------------------------

  # One response for every refusal — bad signature, unknown repository,

  # private repository, missing resource — so none of them can be told apart.

  defp authorize_and_run(conn, params, build) do

    if OG.valid_signature?(conn.request_path, conn.query_params["sig"]) do

      case build.(strip_png(params["owner"]), strip_png(params["repo"])) do

        %OG{} = card -> respond_with_card(conn, card)

        _refused -> not_found(conn)

      end

    else

      not_found(conn)

    end

  end

  defp respond_with_card(conn, card) do

    svg = OG.Templates.render(card)

    case OG.Rasterizer.rasterize(svg) do

      {:ok, png} ->

        send_png(conn, png)

      {:error, reason} ->

        # Exit tuples can carry payloads; log the safe classification only.

        safe_reason =

          case reason do

            {:exit, _payload} -> :exit

            other -> other

          end

        Logger.warning("og_card_fallback kind=#{card.kind} reason=#{safe_reason}")

        send_png(conn, fallback_png())

    end

  end

  defp send_png(conn, bytes \\ nil) do

    conn

    |> put_resp_header("content-type", "image/png")

    |> put_resp_header("cache-control", @cache_control)

    |> put_resp_header("x-content-type-options", "nosniff")

    |> send_resp(200, bytes || default_card_bytes())

  end

  defp not_found(conn) do

    conn

    |> put_resp_header("cache-control", @not_found_cache_control)

    |> send_resp(404, "")

  end

  ## Helpers -------------------------------------------------------------------

  defp public_repository(owner, name) do

    case safe(fn -> Repositories.get_public_by_path!(owner, name) end) do

      %Repositories.Repository{} = repository -> {:ok, repository}

      _other -> :error

    end

  end

  # `Browse.head/1` reports emptiness as an error tuple; the disclosure gate

  # only wants a sha or nil, exactly as the file page derives it.

  defp resolved_head(repository) do

    case safe(fn -> Browse.head(repository) end) do

      {:ok, sha} -> sha

      _other -> nil

    end

  end

  # ".png" rides at the end of the last path segment; a resource genuinely

  # named "*.png" arrives doubled and survives one strip intact.

  defp strip_png(nil), do: nil

  defp strip_png(value) when is_binary(value),

    do: String.replace_suffix(value, ".png", "")

  defp joined_path(segments) when is_list(segments) do

    segments

    |> Enum.join("/")

    |> String.replace_suffix(".png", "")

  end

  defp joined_path(_other), do: ""

  defp blob_lines(%{binary: true}), do: nil

  defp blob_lines(%{content: content}) when is_binary(content),

    do: content |> String.split("\n") |> length()

  defp blob_lines(_blob_info), do: nil

  defp safe(fun) do

    fun.()

  rescue

    _error -> nil

  catch

    :exit, _reason -> nil

  end

  # The committed brand card doubles as the rasterization fallback, cached in

  # process-global storage after its first read.

  defp fallback_png do

    key = {__MODULE__, :fallback_png}

    case :persistent_term.get(key, nil) do

      nil ->

        path = Application.app_dir(:openagents, "priv/static/images/og-card-default.png")

        case File.read(path) do

          {:ok, bytes} ->

            :persistent_term.put(key, bytes)

            bytes

          _unreadable ->

            @transparent_png

        end

      bytes ->

        bytes

    end

  end

  defp default_card_bytes do

    # The static route serves exactly the committed asset; the fallback bytes

    # are the same file, so both paths share one read.

    fallback_png()

  end

end

  use OpenAgentsWeb, :live_view

  alias OpenAgents.Forge.Browse

  alias OpenAgentsWeb.OG

  alias OpenAgentsWeb.RepositoryAccess

  @impl true

     |> assign(:sha, sha)

     |> assign(:path, path)

     |> assign(:blob, blob)

     |> assign(

       :og,

       OG.meta(

         OG.blob(repository.namespace.slug, repository.name, path, %{

           ref: ref,

           size: blob.size,

           lines: if(blob.binary, do: nil, else: blob.content |> String.split("\n") |> length()),

           truncated: blob.truncated

         })

       )

     )

     |> assign(:browsable, RepositoryAccess.full_source?(repository, socket.assigns.current_user))

     |> assign(:markdown?, markdown?(path) and not plain and not blob.binary)}

  rescue

  alias OpenAgents.Forge

  alias OpenAgents.Forge.Browse

  alias OpenAgentsWeb.OG

  alias OpenAgentsWeb.RepositoryAccess

  @impl true

     |> assign(:base, base)

     |> assign(:commit, commit)

     |> assign(:files, files)

     |> assign(

       :og,

       OG.meta(

         OG.commit(repository.namespace.slug, repository.name, commit, files && length(files))

       )

     )

     |> assign(:diff, diff)

     |> assign(:diff_truncated, diff_truncated)

     |> assign(:diff_files, diff_files)

  alias OpenAgents.Forge

  alias OpenAgents.Forge.Browse

  alias OpenAgents.Repositories

  alias OpenAgentsWeb.OG

  alias OpenAgentsWeb.RepositoryAccess

  @impl true

     |> assign(:branch_count, Enum.count(refs, &(&1.kind == :branch)))

     |> assign(:tag_count, Enum.count(refs, &(&1.kind == :tag)))

     |> assign(:open_issue_count, open_issue_count(repository))

     |> assign(:og, OG.meta(OG.repo_card_for(repository)))

     |> assign(:clone_url, RepositoryAccess.clone_url(repository))

     |> assign(:delete_allowed?, delete_allowed?)

     |> assign(:delete_error, nil)

  alias OpenAgents.Labels

  alias OpenAgents.Milestones

  alias OpenAgents.Repositories

  alias OpenAgentsWeb.OG

  alias OpenAgentsWeb.UI.Circle

  @filter_keys ~w(label assignee milestone q)

        |> assign(:assignable, Repositories.list_assignable_users(repository))

        |> assign(:milestone_options, Milestones.list_milestones(repository))

        |> load()

        |> assign(:og, OG.meta(OG.repo_card_for(repository)))

      {:noreply, socket}

    else

  alias OpenAgents.Markdown

  alias OpenAgents.Milestones

  alias OpenAgents.Repositories

  alias OpenAgentsWeb.OG

  alias OpenAgentsWeb.UI.Circle

  def mount(%{"owner" => owner, "repo" => repo, "number" => number}, _session, socket) do

       :assignable,

       if(can_write, do: Repositories.list_assignable_users(repository), else: [])

     )

     |> assign(

       :og,

       OG.meta(OG.issue(repository.namespace.slug, repository.name, issue))

     )

     |> load(issue)}

  end

defmodule OpenAgentsWeb.OG do

  @moduledoc """

  Server-generated Open Graph cards.

  A `%Card{}` is the single unit that flows through the whole pipeline: views

  build one from data they already rendered, this module turns it into a

  content-versioned signed URL for the `<meta>` tags, and

  `OpenAgentsWeb.OgImageController` rebuilds it at request time and renders it

  to PNG. See `docs/2026-08-21-open-graph-cards.md`.

  The security posture of cards matches the pages they describe: a card may

  contain only data the anonymous page already displays, every dynamic string

  is escaped and clamped before it reaches a template, and the image endpoint

  resolves repositories through the public visibility predicate.

  """

  @enforce_keys [:kind]

  defstruct [

    :kind,

    :kicker,

    :heading,

    :description,

    :avatar,

    :provenance,

    chips: [],

    stats: [],

    title: nil,

    # Canonical page URL this card describes (for og:url), e.g.

    # "/OpenAgentsInc/openagents.com/issues/12".

    page_path: nil,

    # Path segments under "/og/v/{version}/repos/", e.g.

    # ["Owner", "repo"] or ["Owner", "repo", "blob", "main", "lib/a.ex"].

    path_suffix: []

  ]

  @type kind :: :site | :repo | :issue | :blob | :commit

  @type t :: %__MODULE__{

          kind: kind(),

          kicker: String.t() | nil,

          heading: String.t() | nil,

          description: String.t() | nil,

          avatar: String.t() | nil,

          provenance: String.t() | nil,

          chips: [%{required(:label) => String.t(), optional(:tone) => atom}],

          stats: [String.t()],

          title: String.t() | nil,

          page_path: String.t() | nil,

          path_suffix: [String.t()]

        }

  @version_bytes 12

  @signature_bytes 16

  # ── builders ────────────────────────────────────────────────────────────────

  @doc "The site-level card every page falls back to."

  def site do

    %__MODULE__{

      kind: :site,

      kicker: "OPENAGENTS",

      heading: "The agent-native forge",

      description: "Host your code, track your issues, and work with agents."

    }

  end

  @doc """

  A repository card. Nil inputs simply drop their stat; a repository without

  a description says so rather than showing a blank band.

  """

  def repo(repository, opts \\ []) when is_list(opts) do

    owner = namespace_slug(repository)

    suffix = [owner, repository.name]

    %__MODULE__{

      kind: :repo,

      kicker: "#{owner} /",

      heading: repository.name,

      description: present(repository.description) || "No description yet.",

      chips: [%{label: "Public"}],

      stats:

        clean_stats([

          opt_stat(opts[:default_branch]),

          issue_stat(opts[:open_issues], opts[:closed_issues]),

          dated_stat("Updated", opts[:updated_at])

        ]),

      provenance: if(opts[:imported], do: "Imported from GitHub"),

      title: meta_title("#{owner}/#{repository.name}"),

      page_path: Path.join(["/" | suffix]),

      path_suffix: suffix

    }

  end

  @doc "An issue card: state, title, author, labels, and conversation size."

  def issue(repository_owner, repository_name, issue) do

    labels = Enum.take(issue.labels || [], 3)

    hidden = max(length(issue.labels || []) - length(labels), 0)

    number_string = Integer.to_string(issue.number)

    chips =

      [%{label: state_label(issue), tone: state_tone(issue)}] ++

        Enum.map(labels, &%{label: &1["name"]}) ++

        List.wrap(if(hidden > 0, do: %{label: "+#{hidden}"}, else: nil))

    author = author_login(issue)

    %__MODULE__{

      kind: :issue,

      kicker: "#{repository_owner}/#{repository_name} · ##{number_string}",

      heading: issue.title || "(no title)",

      avatar: author,

      chips: chips,

      stats:

        clean_stats([

          opt_stat(author),

          dated_stat("Opened", issue.inserted_at),

          comments_stat(issue.comments)

        ]),

      title: meta_title("#{issue.title || "(no title)"} · Issue ##{number_string}"),

      page_path: "/#{repository_owner}/#{repository_name}/issues/#{number_string}",

      path_suffix: [repository_owner, repository_name, "issues", number_string]

    }

  end

  @doc """

  A file card — the layer GitHub does not have. `info` accepts `:ref`,

  `:size`, `:lines`, and `:truncated`; anything missing drops its stat.

  """

  def blob(repository_owner, repository_name, path, info) when is_map(info) do

    filename = basename(path)

    language = language_for_path(path)

    %__MODULE__{

      kind: :blob,

      kicker: "#{repository_owner}/#{repository_name}",

      heading: filename,

      description: display_path(path),

      chips: chip_wrap(language),

      stats:

        clean_stats([

          opt_stat(info[:ref]),

          opt_stat(size_stat(info[:size])),

          lines_stat(info[:lines], info[:truncated])

        ]),

      title: meta_title(filename),

      page_path: "/#{repository_owner}/#{repository_name}/blob/#{info[:ref]}/#{path}",

      path_suffix: [repository_owner, repository_name, "blob", info[:ref], path]

    }

  end

  @doc "A commit card: subject, author, date, and changed-file count."

  def commit(repository_owner, repository_name, commit_info, file_count) do

    subject = present(commit_info[:subject]) || present(commit_info[:sha]) || "Commit"

    sha = commit_info[:sha]

    %__MODULE__{

      kind: :commit,

      kicker: "#{repository_owner}/#{repository_name}",

      heading: subject,

      avatar: commit_info[:author],

      chips: chip_wrap(sha && short_sha(sha)),

      stats:

        clean_stats([

          opt_stat(commit_info[:author]),

          dated_stat("Committed", commit_info[:committed_at]),

          file_count && plural(file_count, "changed file", "changed files")

        ]),

      title: meta_title(subject),

      page_path: "/#{repository_owner}/#{repository_name}/commit/#{sha}",

      path_suffix: [repository_owner, repository_name, "commit", sha]

    }

  end

  defp clean_stats(stats), do: Enum.reject(stats, &(is_nil(&1) or &1 == ""))

  defp opt_stat(value), do: present(value)

  defp issue_stat(open, closed) when is_integer(open) and is_integer(closed),

    do: "#{open} open · #{closed} closed"

  defp issue_stat(open, _) when is_integer(open), do: plural(open, "open issue", "open issues")

  defp issue_stat(_, closed) when is_integer(closed), do: plural(closed, "closed", "closed")

  defp issue_stat(_, _), do: nil

  defp comments_stat(count) when is_integer(count) and count > 0,

    do: plural(count, "comment", "comments")

  defp comments_stat(_), do: nil

  defp size_stat(bytes) when is_integer(bytes), do: format_size(bytes)

  defp size_stat(_), do: nil

  defp lines_stat(lines, true) when is_integer(lines) and lines > 0, do: ">#{lines}+ lines"

  defp lines_stat(lines, _) when is_integer(lines) and lines > 0,

    do: plural(lines, "line", "lines")

  defp lines_stat(_, _), do: nil

  defp dated_stat(prefix, %Date{} = date),

    do: "#{prefix} #{Calendar.strftime(date, "%b %-d, %Y")}"

  defp dated_stat(prefix, %DateTime{} = dt),

    do: dated_stat(prefix, DateTime.shift_zone!(dt, "Etc/UTC") |> DateTime.to_date())

  defp dated_stat(prefix, %NaiveDateTime{} = dt),

    do: dated_stat(prefix, DateTime.from_naive!(dt, "Etc/UTC"))

  defp dated_stat(prefix, text) when is_binary(text) do

    case DateTime.from_iso8601(text) do

      {:ok, dt, _offset} -> dated_stat(prefix, dt)

      _ -> nil

    end

  end

  defp dated_stat(_prefix, _other), do: nil

  defp chip_wrap(nil), do: []

  defp chip_wrap(label), do: [%{label: label}]

  @doc """

  Repository card assembled defensively from an already-loaded repository:

  issue counts, last-commit date, and import provenance become best-effort

  stats. A repository whose Git lane or issues cannot be read still gets a

  complete-looking card rather than no card at all.

  """

  def repo_card_for(%OpenAgents.Repositories.Repository{} = repository) do

    repo(repository,

      default_branch: repository.default_branch,

      open_issues: safe(fn -> OpenAgents.Issues.count_issues(repository, state: "open") end),

      closed_issues: safe(fn -> OpenAgents.Issues.count_issues(repository, state: "closed") end),

      updated_at: latest_commit_date(repository),

      imported: imported?(repository)

    )

  end

  defp latest_commit_date(repository) do

    safe(fn ->

      case OpenAgents.Forge.Browse.log(repository, repository.default_branch, 1) do

        {:ok, [latest | _rest]} -> latest.committed_at

        _other -> nil

      end

    end)

  end

  defp imported?(repository) do

    case Map.get(repository, :repository_import) do

      %OpenAgents.Repositories.RepositoryImport{} -> true

      _other -> false

    end

  end

  # Stats are decoration over another context's data; any failure degrades

  # that stat to nil instead of failing the card.

  defp safe(fun) do

    fun.()

  rescue

    _error -> nil

  catch

    :exit, _reason -> nil

  end

  ## Meta-tag projection -------------------------------------------------------

  @doc """

  The map the root layout renders into `og:*` / `twitter:*` tags.

  `page_url` is the canonical absolute URL of the page emitting the tags.

  """

  def meta(%__MODULE__{} = card, page_url) do

    description = card.description || default_description()

    %{

      title: card.title || card.heading || "OpenAgents",

      description: description,

      type: "object",

      url: page_url,

      image_url: card_url(card),

      alt: description

    }

  end

  @doc "Absolute URL of the committed fallback card."

  def static_card_url, do: base_url() <> "/og/static/card.png"

  @doc "The configured absolute origin, e.g. https://openagents.com."

  def site_url, do: base_url()

  @doc "Meta tags for a card, canonicalized against the card's own page path."

  def meta(%__MODULE__{} = card), do: meta(card, base_url() <> (card.page_path || "/"))

  @doc "Absolute signed URL for a card's image."

  def card_url(%__MODULE__{kind: :site}), do: static_card_url()

  def card_url(%__MODULE__{} = card) do

    path = request_path(card)

    base_url() <> path <> "?sig=" <> signature(path)

  end

  @doc """

  The canonical request path for a card, versioned by its content digest:

      /og/v/{version}/repos/{owner}/{repo}[/{rest}].png

  """

  def request_path(%__MODULE__{} = card) do

    version = version(card)

    segments =

      ["og", "v", version, "repos" | Enum.map(card.path_suffix, &path_segment/1)]

    "/" <> Enum.join(segments, "/") <> ".png"

  end

  defp path_segment(value), do: URI.encode(value, &URI.char_unreserved?/1)

  @doc "Content digest over exactly what the template will draw."

  def version(%__MODULE__{} = card) do

    inputs = {

      card.kind,

      card.kicker,

      card.heading,

      card.description,

      card.avatar,

      card.provenance,

      Enum.map(card.chips, &{&1.label, Map.get(&1, :tone)}),

      card.stats,

      template_revision()

    }

    serialized =

      inputs

      |> :erlang.term_to_binary([:deterministic])

      |> then(&:crypto.hash(:sha256, &1))

      |> Base.encode16(case: :lower)

    binary_part(serialized, 0, @version_bytes)

  end

  @doc "HMAC over the request path; a query string never participates."

  def signature(request_path) when is_binary(request_path) do

    :crypto.mac(:hmac, :sha256, signing_key(), request_path)

    |> binary_part(0, @signature_bytes)

    |> Base.url_encode64(padding: false)

  end

  @doc "Constant-time signature check; anything malformed is simply invalid."

  def valid_signature?(request_path, sig) when is_binary(request_path) and is_binary(sig) do

    expected = signature(request_path)

    if byte_size(sig) == byte_size(expected) do

      Plug.Crypto.secure_compare(expected, sig)

    else

      false

    end

  end

  def valid_signature?(_request_path, _sig), do: false

  defp signing_key do

    secret =

      OpenAgentsWeb.Endpoint.config(:secret_key_base) ||

        Application.get_env(:openagents, :og_signing_key) ||

        "openagents-og-development-key"

    :crypto.mac(:hmac, :sha256, secret, "openagents-og-cards-v1")

  end

  defp template_revision, do: "1"

  defp base_url, do: String.trim_trailing(OpenAgentsWeb.Endpoint.url(), "/")

  defp default_description, do: "Code hosting, issues, and projects on the agent-native forge."

  defp meta_title(text) when is_binary(text), do: clamp(text, 120)

  defp present(nil), do: nil

  defp present(""), do: nil

  defp present(text) when is_binary(text), do: String.trim(text)

  defp namespace_slug(%{namespace: %{slug: slug}}) when is_binary(slug), do: slug

  defp namespace_slug(%{owner: owner}) when is_binary(owner), do: owner

  defp author_login(%{user: %{} = user}), do: user["login"] || user[:login]

  defp author_login(%{author: author}) when is_binary(author), do: author

  defp author_login(_), do: nil

  defp state_label(%{state: "closed", state_reason: "not_planned"}), do: "Closed as not planned"

  defp state_label(%{state: "closed", state_reason: "duplicate"}), do: "Closed as duplicate"

  defp state_label(%{state: "closed"}), do: "Closed"

  defp state_label(_), do: "Open"

  defp state_tone(%{state: "closed", state_reason: reason})

       when reason in ["not_planned", "duplicate"],

       do: :muted

  defp state_tone(%{state: "closed"}), do: :done

  defp state_tone(_), do: :open

  defp short_sha(sha) when is_binary(sha), do: String.slice(sha, 0, 7)

  defp plural(1, singular, _plural), do: "1 #{singular}"

  defp plural(n, _singular, plural_form) when is_integer(n), do: "#{n} #{plural_form}"

  defp format_size(bytes) when bytes < 1024, do: "#{bytes} B"

  defp format_size(bytes) when bytes < 1024 * 1024, do: "#{div(bytes, 1024)} KB"

  defp format_size(bytes),

    do: "#{Float.round(bytes / (1024 * 1024), 1)} MB"

  @doc """

  Language inferred from a path's extension or a well-known filename.

  Honest about ignorance: unknown shapes yield nil and the card shows no

  language chip.

  """

  def language_for_path(path) when is_binary(path) do

    filename = basename(path)

    well_known_language(filename) || extension_language(Path.extname(filename))

  end

  defp well_known_language("Dockerfile"), do: "Docker"

  defp well_known_language("Makefile"), do: "Makefile"

  defp well_known_language("mix.exs"), do: "Elixir"

  defp well_known_language(_), do: nil

  @extension_languages %{

    ".ex" => "Elixir",

    ".exs" => "Elixir",

    ".heex" => "HEEx",

    ".leex" => "HEEx",

    ".eex" => "EEx",

    ".erl" => "Erlang",

    ".hrl" => "Erlang",

    ".md" => "Markdown",

    ".markdown" => "Markdown",

    ".json" => "JSON",

    ".toml" => "TOML",

    ".yml" => "YAML",

    ".yaml" => "YAML",

    ".ts" => "TypeScript",

    ".tsx" => "TSX",

    ".js" => "JavaScript",

    ".jsx" => "JSX",

    ".mjs" => "JavaScript",

    ".cjs" => "JavaScript",

    ".rs" => "Rust",

    ".go" => "Go",

    ".py" => "Python",

    ".rb" => "Ruby",

    ".sh" => "Shell",

    ".bash" => "Shell",

    ".zsh" => "Shell",

    ".css" => "CSS",

    ".scss" => "SCSS",

    ".html" => "HTML",

    ".sql" => "SQL",

    ".swift" => "Swift",

    ".kt" => "Kotlin",

    ".java" => "Java",

    ".c" => "C",

    ".h" => "C",

    ".cpp" => "C++",

    ".hpp" => "C++",

    ".cs" => "C#",

    ".php" => "PHP",

    ".txt" => "Text",

    ".svg" => "SVG",

    ".xml" => "XML"

  }

  defp extension_language(ext) when is_binary(ext),

    do: Map.get(@extension_languages, String.downcase(ext))

  defp extension_language(_), do: nil

  defp basename(path) when is_binary(path),

    do: path |> String.split("/") |> Enum.reject(&(&1 == "")) |> List.last()

  # ── text safety and layout ──────────────────────────────────────────────────

  @control_pattern ~r/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/

  @doc "XML-escapes untrusted text; control characters are stripped entirely."

  def escape(text) when is_binary(text) do

    text

    |> String.replace(@control_pattern, "")

    |> String.replace("&", "&")

    |> String.replace("<", "&lt;")

    |> String.replace(">", ">")

    |> String.replace("\"", """)

    |> String.replace("'", "'")

  end

  def escape(nil), do: ""

  @doc "Hard cap on any dynamic string entering a template, grapheme-safe."

  def clamp(text, max_chars) when is_integer(max_chars) and max_chars >= 1 do

    cond do

      is_nil(text) ->

        nil

      String.length(text) <= max_chars ->

        String.trim(text)

      true ->

        text

        |> String.graphemes()

        |> Enum.take(max_chars - 1)

        |> Enum.concat(["…"])

        |> Enum.join()