archsight 0.4.3 → 0.5.0

data/lib/archsight/pdf/compiler.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+require_relative "../user_config"
+
+module Archsight
+  module Pdf
+    # Raised when a document cannot be turned into a PDF; the message is safe to show
+    class Error < StandardError; end
+
+    # Raised when typst is not installed
+    class Unavailable < Error; end
+
+    # Runs the `typst` command line tool on a prepared directory. The binary is `pdf.typst` of the user
+    # configuration (`ARCHSIGHT_PDF_TYPST`), else `typst` from the PATH.
+    class Compiler
+      DEFAULT_TIMEOUT = 60
+      ERROR_LINES = 12
+
+      def initialize(binary: nil, timeout: nil)
+        @binary = binary || UserConfig.setting("pdf", "typst") || "typst"
+        @timeout = (timeout || UserConfig.setting("pdf", "timeout") || DEFAULT_TIMEOUT).to_i
+      end
+
+      # @param dir [String] directory with main.typ; it is the Typst root, nothing outside of it can be read
+      # @param font_paths [Array<String>] directories with additional fonts
+      # @return [String] the PDF
+      # @raise [Unavailable] without typst
+      # @raise [Error] if typst fails or runs too long
+      def compile(dir, font_paths: [])
+        output = File.join(dir, "out.pdf")
+        args = [@binary, "compile", "--root", dir, *font_paths.flat_map { |p| ["--font-path", p] }, File.join(dir, "main.typ"), output]
+        _out, err, status = run(args, dir)
+        raise Error, "typst failed:\n#{err.lines.first(ERROR_LINES).join}" unless status.success? && File.file?(output)
+
+        File.binread(output)
+      end
+
+      # Whether PDF files can be placed as images (typst 0.14 and newer)
+      def pdf_images?
+        return @pdf_images if defined?(@pdf_images)
+
+        out, status = Open3.capture2(@binary, "--version")
+        version = out[/(\d+)\.(\d+)/]
+        @pdf_images = status.success? && !version.nil? && (Gem::Version.new(version) >= Gem::Version.new("0.14"))
+      rescue Errno::ENOENT
+        raise Unavailable, "typst is not installed (set ARCHSIGHT_PDF_TYPST to its path)"
+      end
+
+      private
+
+      def run(args, dir)
+        Open3.popen3(*args, chdir: dir) do |stdin, stdout, stderr, thread|
+          stdin.close
+          out = Thread.new { stdout.read }
+          err = Thread.new { stderr.read }
+          unless thread.join(@timeout)
+            Process.kill("KILL", thread.pid)
+            raise Error, "typst took longer than #{@timeout} seconds"
+          end
+          [out.value, err.value, thread.value]
+        end
+      rescue Errno::ENOENT
+        raise Unavailable, "typst is not installed (set ARCHSIGHT_PDF_TYPST to its path)"
+      end
+    end
+  end
+end

data/lib/archsight/pdf/dependency_graph.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "open3"
+require "digest"
+require_relative "../renderer"
+require_relative "../graph"
+require_relative "../user_config"
+require_relative "../resources"
+
+module Archsight
+  module Pdf
+    # The dependency graph of a resource as an SVG document, the picture the resource's page shows: the resources its
+    # relations lead to, as far as the page opens it (two steps, the layer of the resource and the one below it). The
+    # page draws it in the browser; here it is drawn by the `dot` command of Graphviz (`pdf.dot` /
+    # `ARCHSIGHT_PDF_DOT`, else `dot` from the PATH). A resource without relations has no graph, and without `dot`
+    # there is none either, which is not an error: the document is made without it.
+    class DependencyGraph
+      include Archsight::GraphvisRenderer
+
+      DEPTH = 2
+      BOX = [500.0, 480.0].freeze # points: the text width of a page and the height a graph may take (to choose the direction)
+      DIRECTIONS = %w[LR TB].freeze # left to right as on the page, or top to bottom
+      TIMEOUT = 30
+      CACHE_ENTRIES = 32
+
+      # The colours of the layers (the page colours its nodes with the same, by CSS)
+      LAYER_COLOURS = {
+        "strategy" => "#F4A261", "business" => "#F9DC5C", "application" => "#6CBEED", "technology" => "#8AC926",
+        "implementation" => "#F48FB1", "motivation" => "#CE93D8", "other" => "#cccccc"
+      }.freeze
+      # For the SVG, where the colours come as CSS: the page's style, without the borders of the label tables
+      STYLE = "<style>\n#{LAYER_COLOURS.map { |layer, hex| ".layer-#{layer} path[fill=\"lightgrey\"] { fill: #{hex}; stroke: #{hex}; }" }.join("\n")}\n" \
+              ".node polygon[fill=\"none\"] { stroke: none; }\n.node text { fill: #000000; }\n</style>\n".freeze
+      LAYER_CLASS = /("class" = "[^"]*\blayer-(\w+)[^"]*")/
+
+      @cache = {}
+      @lock = Mutex.new
+
+      class << self
+        # Colours the nodes by layer, as the page does (the DOT has no colours, they come from the page's CSS)
+        # @return [String] the SVG with a style element after its opening tag
+        def colour_layers(svg)
+          svg.sub(/(<svg\b[^>]*>)/) { "#{Regexp.last_match(1)}\n#{STYLE}" }
+        end
+
+        # The DOT of the page with what the page's CSS adds: the fill of a node by its layer, and label tables without borders
+        def paint(dot)
+          dot.gsub(LAYER_CLASS) do
+            hex = LAYER_COLOURS.fetch(Regexp.last_match(2), LAYER_COLOURS["other"])
+            "#{Regexp.last_match(1)} \"fillcolor\" = \"#{hex}\" \"color\" = \"#{hex}\""
+          end.gsub("<TABLE>", '<TABLE BORDER="0" CELLBORDER="0" CELLSPACING="0">')
+        end
+
+        def cached(key)
+          @lock.synchronize { @cache[key] } || yield.tap do |value|
+            @lock.synchronize do
+              @cache[key] = value
+              @cache.shift while @cache.size > CACHE_ENTRIES
+            end
+          end
+        end
+      end
+
+      # @param layers [Array<String>, nil] the layers to follow; the page's default for the resource's layer if nil
+      def initialize(database, resource, depth: DEPTH, layers: nil, binary: nil)
+        @database = database
+        @resource = resource
+        @depth = depth
+        @layers = layers || Archsight::GraphvisRenderer.default_graph_layers(resource.class.layer)
+        @binary = binary || UserConfig.setting("pdf", "dot") || "dot"
+      end
+
+      # @return [Boolean] whether the graph would show more than the resource itself
+      def relations?
+        !graph_targets(@resource, @layers).empty?
+      end
+
+      # @return [String, nil] the graph as a PDF page (drawn by `dot` itself, with the fonts it measured the text with), nil
+      #   if there is nothing to draw or `dot` is not installed or fails
+      def pdf = draw("pdf")
+
+      # @return [String, nil] the graph as SVG, coloured by CSS; nil as for #pdf
+      def svg
+        out = draw("svg")
+        out && self.class.colour_layers(out.dup.force_encoding(Encoding::UTF_8))
+      end
+
+      private
+
+      def draw(format)
+        return nil unless relations?
+
+        dot = self.class.paint(create_graph_one(@database, @resource.klass, @resource.name, max_depth: @depth, layers: @layers))
+        self.class.cached(Digest::SHA256.hexdigest("#{@binary}\0#{format}\0#{dot}")) { run(format, oriented(dot)) }
+      end
+
+      # The direction in which the graph is largest on the page: wide graphs read best left to right, tall ones top to
+      # bottom. Left to right (the page's) wins unless the other is clearly better.
+      def oriented(dot)
+        DIRECTIONS.each_with_index.map { |direction, index| [with_direction(dot, direction), index.zero? ? 1.05 : 1.0] }
+                                  .max_by { |candidate, bonus| fit(candidate) * bonus }.first
+      end
+
+      def with_direction(dot, direction)
+        dot.sub(/"rankdir" = "?\w+"?/, "\"rankdir\" = \"#{direction}\"")
+      end
+
+      # How much of its natural size the graph keeps when it is made to fit the box (1.0: nothing lost); 0 if `dot` fails
+      def fit(dot)
+        out, status = Open3.capture2(@binary, "-Tplain", stdin_data: dot)
+        return 0 unless status.success?
+
+        _graph, _scale, width, height = out.lines.first.split
+        [BOX[0] / (width.to_f * 72), BOX[1] / (height.to_f * 72), 1.0].min
+      rescue Errno::ENOENT
+        0
+      end
+
+      def run(format, dot)
+        out, status = Open3.capture2(@binary, "-T#{format}", stdin_data: dot, binmode: true)
+        status.success? && !out.empty? ? out : nil
+      rescue Errno::ENOENT
+        nil
+      end
+    end
+  end
+end

data/lib/archsight/pdf/document.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require "date"
+require "digest"
+require_relative "typst"
+require_relative "markdown"
+require_relative "theme"
+require_relative "images"
+require_relative "embeds"
+require_relative "resource_sheet"
+require_relative "dependency_graph"
+require_relative "../helpers/resource_resolver"
+require_relative "../helpers/diagram_includes"
+require_relative "../helpers/wiki_links"
+
+module Archsight
+  module Pdf
+    # One resource or page as the files typst needs: `main.typ` (the document), the layout library, the theme
+    # and the images. Pages are exported as written; any other resource becomes a generated document (description,
+    # properties, relations, diagram).
+    #
+    # Tags steer the export (page `page/tags`, resource `architecture/tags`):
+    #
+    #   pdf:cover               cover page instead of a title block
+    #   pdf:toc                 table of contents
+    #   pdf:landscape           landscape pages
+    #   pdf:draft               "draft" watermark
+    #   pdf:no-graph            leave the dependency graph out of a resource document
+    #   pdf:template:<name>     pdf Config to use instead of `default`
+    #   version:<x>             document version (else the page property Version, else 1)
+    class Document
+      GRAPH_HEIGHT = 0.8 # share of the page height the dependency graph may take
+      LIBRARY = File.join(__dir__, "typst", "archsight.typ")
+
+      # @return [String] title of the document
+      attr_reader :title
+
+      # @param template [String, nil] name of a pdf Config, overrides the tag
+      # @param draft [Boolean] force the watermark
+      def initialize(database, resource, template: nil, draft: false, resources_dir: Archsight.resources_dir, pdf_images: true)
+        @database = database
+        @resource = resource
+        @resources_dir = resources_dir
+        @pdf_images = pdf_images
+        @tags = tag_list
+        @theme = theme_for(template)
+        @draft = draft || @tags.include?("pdf:draft")
+        @title = title_for
+      end
+
+      # @return [Hash{String => String}] file name => content of everything typst needs, `main.typ` among them
+      def files
+        @files ||= build
+      end
+
+      # @return [Array<String>] directories with fonts to hand to typst
+      def font_paths
+        [@theme.font_dir].compact
+      end
+
+      # A name for the downloaded file
+      def filename
+        "#{@resource.name.to_s.gsub(/[^A-Za-z0-9._-]+/, "-").gsub(/\A[-.]+|-+\z/, "")}.pdf"
+      end
+
+      # Changes whenever the PDF would: the files and the fonts
+      def fingerprint
+        digest = Digest::SHA256.new
+        files.sort.each { |name, content| digest << name << "\0" << content.b << "\0" }
+        font_paths.each { |dir| Dir.children(dir).sort.each { |f| digest << f << File.size(File.join(dir, f)).to_s } }
+        digest.hexdigest[0, 16]
+      end
+
+      private
+
+      # The look, the title and the body are what a variant (see SampleDocument) replaces
+      def theme_for(template)
+        Theme.for(@database, template || tag_value("pdf:template"))
+      end
+
+      def title_for
+        page? ? @resource.title : @resource.name
+      end
+
+      def body(images)
+        page? ? page_body(images) : resource_body(images)
+      end
+
+      def page?
+        @resource.klass == "Page"
+      end
+
+      def build
+        images = Images.new(base_dir: base_dir, resources_dir: @resources_dir, resolver: resolver,
+                            includes: Helpers::DiagramIncludes.for(@database), pdf_images: @pdf_images)
+        body = body(images)
+        files = { "archsight.typ" => File.read(LIBRARY), "main.typ" => main(body) }.merge(images.files)
+        files.merge(logo_files).tap { |f| f["theme.typ"] = @theme.to_typst(**logo_names) }
+      end
+
+      def main(body)
+        meta = "title: #{Typst.lit(@title)}, doc-id: #{opt(doc_id)}, version: #{opt(version)}, date: #{opt(date)}, owner: #{opt(owner)}"
+        args = "theme: theme, #{meta}"
+        front = if @tags.include?("pdf:cover")
+                  "#cover-page(#{args}, kind: #{opt(kind)}, classification: #{opt(classification)})"
+                else
+                  "#title-block(theme: theme, title: #{Typst.lit(@title)}, kind: #{opt(kind)})"
+                end
+        front += "\n#toc-page(theme: theme)" if @tags.include?("pdf:toc")
+        <<~TYPST
+          #import "archsight.typ": *
+          #import "theme.typ": theme
+          #show: doc.with(#{args}, classification: #{opt(classification)}, draft: #{@draft}, landscape: #{@tags.include?("pdf:landscape")})
+          #{front}
+
+          #{body}
+        TYPST
+      end
+
+      # ---- body
+
+      def page_body(images)
+        markdown(images).render(strip_title(@resource.annotations["page/content"].to_s))
+      end
+
+      def resource_body(images)
+        ann = @resource.annotations
+        sheet = ResourceSheet.new(@resource, markdown: ->(text) { markdown(images, offset: 2).render(text) })
+        parts = []
+        # the pictures come first, right after the title, then the text and the facts
+        parts.concat(dependency_graph(images))
+        parts << images.diagram(ann["architecture/diagram"]).to_s if ann["architecture/diagram"].to_s.strip != ""
+        parts << markdown(images, offset: 1).render(ann["architecture/description"]) if ann["architecture/description"].to_s.strip != ""
+        parts.concat(sheet.properties)
+        parts.concat(sheet.relations)
+        parts.join("\n\n")
+      end
+
+      # The dependency graph the resource's page shows, unless the tag `pdf:no-graph` leaves it out
+      def dependency_graph(images)
+        return [] if @tags.include?("pdf:no-graph")
+
+        graph = DependencyGraph.new(@database, @resource)
+        picture = (images.pdf(graph.pdf, max_height: GRAPH_HEIGHT) if @pdf_images && graph.pdf) ||
+                  (images.vector(graph.svg, max_height: GRAPH_HEIGHT) if graph.svg)
+        picture ? [picture] : []
+      end
+
+      # @param embeds [Boolean] whether views, analyses and `![[..]]` embeds are part of the text; the content of an embed
+      #   is rendered without (one level, so embeds cannot include each other)
+      def markdown(images, offset: 0, embeds: true)
+        links = Helpers::WikiLinks.new(@database, resolver: resolver)
+        Markdown.new(heading_offset: offset, image: images.method(:image), diagram: images.method(:diagram), label: links.method(:label_for),
+                     embeds: embeds ? embeds_for(images) : nil)
+      end
+
+      def embeds_for(images)
+        @embeds_for ||= Embeds.new(@database, markdown: ->(inline, text) { markdown(images, offset: 1, embeds: false).render(text, inline: inline) })
+      end
+
+      # The header already shows the title, so a leading "# Title" that repeats it is dropped
+      def strip_title(body)
+        first, rest = body.lstrip.split("\n", 2)
+        heading = first.to_s[/\A#\s+(.+?)\s*#*\s*\z/, 1]
+        heading && [@title, @resource.name].any? { |t| t.to_s.casecmp?(heading) } ? rest.to_s.lstrip : body
+      end
+
+      # ---- metadata
+
+      def properties_hash
+        @properties_hash ||= page? ? @resource.properties.to_h : {}
+      end
+
+      def tag_list
+        raw = @resource.annotations["page/tags"] || @resource.annotations["architecture/tags"]
+        raw.to_s.split(",").map(&:strip).reject(&:empty?)
+      end
+
+      # `prefix:value` of a tag
+      def tag_value(prefix)
+        @tags.filter_map { |t| t.delete_prefix("#{prefix}:") if t.start_with?("#{prefix}:") }.first
+      end
+
+      def doc_id = properties_hash["Document ID"] || "#{@resource.klass}/#{@resource.name}"
+      def version = tag_value("version") || properties_hash["Version"] || "1"
+      def classification = properties_hash["Classification"] || @theme.classification
+      def kind = page? ? nil : @resource.klass
+
+      def date
+        (@resource.annotations["page/updated"] || Date.today.iso8601).to_s[0, 10]
+      end
+
+      def owner
+        value = @resource.annotations["page/owner"] || @resource.annotations["page/author"] ||
+                @resource.annotations["architecture/owner"]
+        Annotations::EmailRecipient.parse(value)&.fetch(:name)
+      end
+
+      def base_dir
+        Assets.base_dir_for(@resource, resources_dir: @resources_dir)
+      end
+
+      def resolver
+        @resolver ||= Helpers::ResourceResolver.new(@database)
+      end
+
+      def opt(value)
+        value.to_s.strip.empty? ? "none" : Typst.lit(value)
+      end
+
+      # Logos are staged under fixed names; the file type decides the extension
+      def logo_names
+        { logo: staged_name("logo", @theme.logo), logo_light: staged_name("logo-light", @theme.logo_light) }
+      end
+
+      def logo_files
+        { logo_names[:logo] => @theme.logo, logo_names[:logo_light] => @theme.logo_light }
+          .reject { |name, file| name.nil? || file.nil? }
+          .transform_values { |file| File.binread(file) }
+      end
+
+      def staged_name(base, file)
+        file && "#{base}#{File.extname(file).downcase}"
+      end
+    end
+  end
+end

data/lib/archsight/pdf/embeds.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "typst"
+require_relative "markdown"
+require_relative "tables"
+require_relative "../view_table"
+require_relative "../requirements"
+require_relative "../user_config"
+require_relative "../helpers/embeds"
+require_relative "../helpers/view_blocks"
+require_relative "../helpers/requirements_blocks"
+require_relative "../helpers/resource_resolver"
+require_relative "../query"
+
+module Archsight
+  module Pdf
+    # The live content of a page, as the data of the moment of the export (as the Confluence export does it): a View
+    # (`![[View/Name]]` or a ```view block) and the requirements of some resources as tables, an Analysis as its result,
+    # any other resource as its description. Nothing here raises: what cannot be shown is a note in the document, so
+    # that nothing disappears silently.
+    class Embeds
+      MAX_ANALYSES = 5 # per document, an analysis may run for as long as its own timeout
+      ANALYSIS_TTL = 60 # seconds a result is reused (the PDF endpoint builds the document for every request)
+      ANALYSIS_ENTRIES = 32
+      ANALYSIS_HEADING_OFFSET = 2
+
+      @results = {}
+      @lock = Mutex.new
+
+      class << self
+        # The result of an analysis, from a run of the last minute if there is one
+        def result(database, analysis, now: Time.now)
+          key = [analysis.name, Digest::SHA256.hexdigest(analysis.annotations.to_a.sort.inspect)]
+          entry = @lock.synchronize { @results[key] }
+          return entry[:result] if entry && now - entry[:at] < ANALYSIS_TTL
+
+          require_relative "../analysis"
+          result = Archsight::Analysis::Executor.new(database).execute(analysis)
+          @lock.synchronize do
+            @results[key] = { result: result, at: now }
+            @results.shift while @results.size > ANALYSIS_ENTRIES
+          end
+          result
+        end
+      end
+
+      # @param markdown [#call] `(Boolean inline, String) -> Typst`: renders markdown the way the document does
+      def initialize(database, markdown:, max_analyses: nil)
+        @database = database
+        @markdown = markdown
+        @max_analyses = (max_analyses || UserConfig.setting("pdf", "max_analyses") || MAX_ANALYSES).to_i
+        @analyses = 0
+        @resolver = Helpers::ResourceResolver.new(database)
+      end
+
+      def view_block(source)
+        table(ViewTable.from_block(@database, source))
+      rescue Helpers::ViewBlocks::Error, Archsight::Query::QueryError => e
+        problem("view block: #{e.message}")
+      end
+
+      def requirements_block(source)
+        table(Requirements.table(@database, Helpers::RequirementsBlocks.parse(source)), empty: "No requirements")
+      rescue Helpers::RequirementsBlocks::Error, Archsight::Query::QueryError => e
+        problem("requirements block: #{e.message}")
+      end
+
+      # @param reference [String] `Kind/Name` of `![[Kind/Name]]`
+      def embed(reference)
+        found = @resolver.find(reference)
+        return problem("#{reference}: not found") if found == :missing
+        return problem("#{reference}: ambiguous, write Kind/Name") if found == :ambiguous
+
+        kind, name = found
+        instance = @database.instance_by_kind(kind, name)
+        case kind
+        when "View" then view(instance)
+        when "Analysis" then analysis(instance)
+        else description(kind, instance, reference)
+        end
+      end
+
+      private
+
+      def table(table, empty: "No results")
+        Tables.typst(table, markdown: ->(text) { @markdown.call(true, text) }, empty: empty)
+      end
+
+      def problem(message)
+        Typst.note(message, fill: "#fde8e8")
+      end
+
+      def view(instance)
+        table(ViewTable.from_view(@database, instance))
+      rescue Helpers::ViewBlocks::Error, Archsight::Query::QueryError => e
+        problem("view #{instance.name}: #{e.message}")
+      end
+
+      # A page or menu is not content, a resource without description has nothing to show: its name stands there
+      def description(kind, instance, reference)
+        text = instance.annotations["architecture/description"].to_s.strip
+        return Typst.str(reference) unless Helpers::Embeds.embeddable_kind?(kind) && !text.empty?
+
+        @markdown.call(false, text)
+      end
+
+      def analysis(instance)
+        return problem("Analysis #{instance.name} not run: at most #{@max_analyses} analyses per document") if @analyses >= @max_analyses
+
+        @analyses += 1
+        result = self.class.result(@database, instance)
+        renderer = Archsight::Analysis::TypstRenderer.new([result], full: true)
+        parts = ["#strong[#{Typst.str(instance.name)}]"]
+        parts << renderer.error(result) if result.failed?
+        parts.concat(result.sections.filter_map { |section| analysis_section(renderer, section) })
+        parts.join("\n\n")
+      end
+
+      def analysis_section(renderer, section)
+        case section[:type]
+        when :table then table(analysis_table(section))
+        when :text then @markdown.call(false, section[:content].to_s)
+        else renderer.section(section, heading_offset: ANALYSIS_HEADING_OFFSET)
+        end
+      end
+
+      def analysis_table(section)
+        rows = section[:rows].map { |row| section[:headers].each_index.map { |i| ViewTable::Cell.new(text: row[i].to_s, as: :markdown) } }
+        ViewTable::Table.new(title: "", columns: section[:headers], rows: rows, total: rows.size)
+      end
+    end
+  end
+end

data/lib/archsight/pdf/images.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "typst"
+require_relative "remote_image"
+require_relative "../assets"
+require_relative "../diagram"
+require_relative "../helpers/diagram_blocks"
+
+module Archsight
+  module Pdf
+    # The pictures of a document: images next to the markdown and `asd` diagrams, copied (or converted) into the
+    # directory typst compiles in. Only what Archsight::Assets serves is ever read.
+    class Images
+      RASTER = %w[.png .jpg .jpeg .gif].freeze
+
+      # @return [Hash{String => String}] staged file name => content
+      attr_reader :files
+
+      # @param base_dir [String, nil] directory of the markdown file, relative to the resources directory
+      # @param pdf_images [Boolean] whether typst can place PDF files; else vector graphics stay SVG
+      def initialize(base_dir:, resources_dir:, resolver: nil, includes: nil, pdf_images: true, remote: RemoteImage.method(:fetch))
+        @base_dir = base_dir.to_s
+        @resources_dir = resources_dir
+        @resolver = resolver
+        @includes = includes
+        @pdf_images = pdf_images
+        @remote = remote && RemoteImage.enabled? ? remote : nil
+        @files = {}
+      end
+
+      # Hook for Markdown: Typst markup of the image a markdown reference names, nil if it cannot be shown
+      def image(src, _alt = nil)
+        return remote(src) if Assets.external?(src)
+
+        path = Assets.resolve_reference(src, @base_dir)
+        file = path && Assets.file_for(path, resources_dir: @resources_dir)
+        return nil unless file && File.size(file) <= Assets::MAX_BYTES
+
+        case File.extname(file).downcase
+        when *RASTER then place(File.binread(file), File.extname(file).downcase)
+        when ".svg" then vector(File.read(file, encoding: "UTF-8"))
+        when ".asd" then diagram(File.read(file, encoding: "UTF-8"))
+        when Assets::DRAWIO then Typst.note("draw.io diagram, shown in Archsight", fill: "#f2f2f2")
+        end
+      end
+
+      # Hook for Markdown: Typst markup of an `asd` diagram, or a note and the source if it does not render
+      def diagram(source)
+        vector(Helpers::DiagramBlocks.standalone_svg(source, resolver: @resolver, includes: @includes))
+      rescue Archsight::Diagram::Error => e
+        note = Typst.note("Diagram could not be rendered: #{e.message}", fill: "#fde8e8")
+        [note, Typst.raw(source, "asd")].join("\n\n")
+      end
+
+      # Vector graphics are placed as PDF (rsvg-convert paints text outlines correctly, typst's own SVG renderer
+      # does not honour `paint-order`), as SVG when that tool or PDF images are not available.
+      def vector(svg, max_height: nil)
+        pdf = @pdf_images ? Images.svg_to_pdf(svg) : nil
+        pdf ? place(pdf, ".pdf", max_height: max_height) : place(svg, ".svg", max_height: max_height)
+      end
+
+      # A PDF page that is already a picture (drawn by another tool), placed as it is
+      def pdf(bytes, max_height: nil)
+        place(bytes, ".pdf", max_height: max_height)
+      end
+
+      # @return [String, nil] PDF bytes of an SVG document, nil without rsvg-convert
+      def self.svg_to_pdf(svg)
+        out, status = Open3.capture2("rsvg-convert", "--format", "pdf", stdin_data: svg, binmode: true)
+        status.success? && !out.empty? ? out : nil
+      rescue Errno::ENOENT
+        nil
+      end
+
+      # An image by URL: fetched when allowed, else the caller shows the alt text
+      def remote(src)
+        return nil unless @remote && src.match?(%r{\Ahttps?://}i)
+
+        bytes, ext = @remote.call(src)
+        place(bytes, ext) if bytes
+      end
+
+      private
+
+      # @param max_height [Float, nil] share of the page height the picture may take (the layout's default if nil)
+      def place(bytes, ext, max_height: nil)
+        name = "img-#{@files.size + 1}#{ext}"
+        @files[name] = bytes
+        "#fit-image(#{Typst.lit(name)}#{", max-height: #{max_height}" if max_height})"
+      end
+    end
+  end
+end