asciidoctor-ldl 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d37e7971f951167055c3491ecfeb5490b04b57871428bedb4cdd9e1184ddda18
+  data.tar.gz: 66950750f09e748e71f498678f0d305beb92ce31b04e8aa5cb2a47bc0f344069
+SHA512:
+  metadata.gz: 5bb1d501146cece951dbc5268ec36d73b058af6aceaaf3124bef4c870594fbc7cac86041f5b6fa342b18b3ba4037e3cc07ccb21f3d7ec52f9c23bc34eb623dd3
+  data.tar.gz: a07923b23d094eabfff664acf3d95b4451802e5c3263616eba076cbd11b86b71d32baedbec57fdf5f552f7a897f677431431e7145eefe0e515953fd555cbd674

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project are documented here. 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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-23
+
+### Added
+
+- Initial release.
+- `[ldl]` delimited block and `ldl::file.ldl[]` block macro that render
+  [Logic Diagram Language](https://github.com/OpenPowerShift/logic-diagram-language)
+  source to an image at conversion time.
+- SVG output (vector, isomorphic, no extra dependency) and PNG output (via
+  `@resvg/resvg-js`).
+- `format`, `scale`, `theme`, `show-ids` and `show-labels` attributes, settable
+  per block or document-wide with the `ldl-` prefix.
+- Every generated image carries `ldl`, `ldl-<format>` and `ldl-<theme>` roles for
+  CSS / asciidoctor-pdf theme targeting.
+- Content-addressed caching with a digest sidecar so unchanged diagrams are not
+  re-rendered.
+
+[Unreleased]: https://github.com/OpenPowerShift/asciidoctor-ldl/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/OpenPowerShift/asciidoctor-ldl/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Mulholland
+
+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.adoc

@@ -0,0 +1,365 @@
+= asciidoctor-ldl
+:idprefix:
+:idseparator: -
+:source-language: asciidoc
+:ldl-url: https://github.com/OpenPowerShift/logic-diagram-language
+:npm-url: https://www.npmjs.com/package/@openpowershift/logic-diagram-language
+:toc: macro
+:toclevels: 3
+
+An https://asciidoctor.org[Asciidoctor] extension that renders *logic and
+protection-relay diagrams* written in the {ldl-url}[Logic Diagram Language (LDL)]
+into *SVG* or *PNG* at conversion time, driven by AsciiDoc attributes.
+
+You write boolean equations in an AsciiDoc block; the extension renders a clean,
+laid-out diagram and embeds it as an image — no manual placement, no separate
+build step.
+
+[source]
+----
+[ldl]
+....
+TRIP.Name = "Trip"
+TRIP = OVERCURRENT AND NOT BLOCK
+       OR (EARTH AND MANUAL)
+....
+----
+
+toc::[]
+
+== How it works
+
+Rendering is delegated to the official {npm-url}[`@openpowershift/logic-diagram-language`]
+npm package (the same renderer used by the
+{ldl-url}[LDL playground]). The gem ships a tiny Node helper that imports the
+package and returns the rendered artifact; the Ruby side handles attributes,
+output paths and caching.
+
+* *SVG* output is produced by the LDL renderer directly (isomorphic — pure
+  Node). It needs only Node and the npm package. Being vector, it embeds
+  cleanly in `asciidoctor-pdf`, scales without loss, and stays small.
+* *PNG* output additionally rasterises the SVG with
+  https://github.com/thx/resvg-js[`@resvg/resvg-js`] — a single prebuilt,
+  dependency-free native module (no system libraries such as ImageMagick,
+  Cairo or a headless browser required).
+
+The dependency footprint is deliberately small: *Ruby*, *Node*, and the *LDL npm
+package* (plus `@resvg/resvg-js` only if you want PNG).
+
+== Prerequisites
+
+* Ruby (works on older versions — 2.5+) with Asciidoctor 2.0+.
+* https://nodejs.org[Node.js] 20 or newer, on `PATH`.
+* The LDL npm package, installed where you build your documents:
++
+[source,console]
+----
+$ npm install @openpowershift/logic-diagram-language
+$ npm install @resvg/resvg-js          # only needed for PNG output
+----
+
+The extension resolves the npm package from your project's `node_modules`
+(your build directory), or from a location you point it at with the
+`ldl-package-dir` attribute or the `LDL_PACKAGE_DIR` environment variable.
+
+== Installation
+
+Add the gem to your `Gemfile`:
+
+[source,ruby]
+----
+gem 'asciidoctor-ldl'
+----
+
+or install it directly:
+
+[source,console]
+----
+$ gem install asciidoctor-ldl
+----
+
+== Registering the extension
+
+On the command line, require it when converting:
+
+[source,console]
+----
+$ asciidoctor -r asciidoctor-ldl document.adoc
+$ asciidoctor-pdf -r asciidoctor-ldl document.adoc
+----
+
+From Ruby, requiring the gem auto-registers it with the global registry:
+
+[source,ruby]
+----
+require 'asciidoctor'
+require 'asciidoctor-ldl'
+
+Asciidoctor.convert_file 'document.adoc', safe: :safe
+----
+
+To register against a specific registry instead of globally:
+
+[source,ruby]
+----
+registry = Asciidoctor::Extensions.create
+Asciidoctor::Ldl.register(registry)
+----
+
+== Usage
+
+=== Inline block
+
+Put LDL source in a block named `ldl`. Use a literal (`....`) delimiter so LDL's
+own punctuation is never interpreted as AsciiDoc:
+
+[source]
+----
+[ldl]
+....
+O1.Name = "Trip"
+I1.Name = "Overcurrent"
+O1 = I1 AND NOT I2
+....
+----
+
+Optional positional attributes are `target` (a stable output file name) and
+`format`:
+
+[source]
+----
+[ldl,trip-logic,svg]
+....
+O1 = I1 AND NOT I2
+....
+----
+
+=== From a file
+
+Use the `ldl::` block macro to render an external `.ldl` file (path relative to
+the document):
+
+[source]
+----
+ldl::diagrams/trip-matrix.ldl[format=png,scale=2]
+----
+
+== Attributes
+
+Every option can be set on the individual block/macro, or document-wide using
+the `ldl-` prefixed form (block/macro wins). Set document attributes in the
+header or on the command line (`-a ldl-format=png`).
+
+[cols="1m,1m,1,3",options="header"]
+|===
+| Block attribute | Document attribute | Default | Description
+
+| format
+| ldl-format
+| `svg`
+| Output format: `svg` or `png`.
+
+| scale
+| ldl-scale
+| `1`
+| Scale multiplier. For `svg`, sets explicit `width`/`height` from the diagram's
+  intrinsic size (the `viewBox` is preserved, so it still scales crisply). For
+  `png`, multiplies the rasterised device pixels.
+
+| theme
+| ldl-theme
+| `light`
+| Colour theme: `light` or `dark`.
+
+| show-ids
+| ldl-show-ids
+| `false`
+| Draw bare identifiers (e.g. `I1`, `AND#G1`) instead of / in addition to labels.
+
+| show-labels
+| ldl-show-labels
+| `true`
+| Draw `.Name`/`.Description` labels.
+
+| target
+| —
+| _(hash)_
+| Output file basename (without extension). When omitted, a content-addressed
+  name (`ldl-<hash>.<ext>`) is used so identical diagrams share a file.
+
+| _(n/a)_
+| ldl-node
+| `node`
+| Path to the Node executable.
+
+| _(n/a)_
+| ldl-package-dir
+| _(auto)_
+| Directory from which to resolve the LDL npm package (and `@resvg/resvg-js`).
+  Overrides auto-detection; the `LDL_PACKAGE_DIR` env var does the same.
+
+| _(n/a)_
+| ldl-cache
+| `true`
+| Set to `false` to always re-render, ignoring the cache.
+|===
+
+Standard image attributes — `alt`, `title`, `width`, `height`, `align`,
+`float`, `id`, `link`, `role` — pass straight through to the generated image.
+
+TIP: Most *diagram* styling (inversion bubbles vs NOT gates, input bars,
+compactness, stroke width, margins, …) is authored in the LDL source itself with
+`OPTION` lines — see the {ldl-url}[LDL documentation]. This extension only
+surfaces the render-time view options above.
+
+=== Language `OPTION` lines vs. attributes
+
+The LDL source can carry its own `OPTION` lines; the extension honours them and
+then applies the attribute-driven overrides (`theme`, `show-ids`,
+`show-labels`) on top. For example:
+
+[source]
+----
+[ldl,theme=dark]
+....
+OPTION INVERSION = BUBBLES
+OPTION MARGIN = 16
+O1 = I1 AND NOT I2
+....
+----
+
+== Output formats
+
+Choosing a format:
+
+[cols="1m,4",options="header"]
+|===
+| Format | When to use
+
+| svg
+| *Default and recommended for `asciidoctor-pdf`.* Vector, so it is sharp at any
+  zoom or print resolution, embeds via `prawn-svg` with no rasterisation, and
+  compresses to a fraction of an equivalent PNG. Also ideal for HTML.
+
+| png
+| When a raster image is required (e.g. a target that cannot embed SVG). Use
+  `scale` to control resolution — `scale=2` renders at 2× device pixels.
+  Requires `@resvg/resvg-js`.
+|===
+
+For `asciidoctor-pdf`, prefer `svg`: it keeps PDFs small and crisp. If you must
+raster for PDF, `png` with `scale=2` or higher gives good print quality at the
+cost of size.
+
+== Styling with roles
+
+Every generated image is tagged with roles so it can be targeted from CSS or an
+`asciidoctor-pdf` theme without touching each block:
+
+* `ldl` — on every LDL diagram.
+* `ldl-svg` / `ldl-png` — the output format.
+* `ldl-light` / `ldl-dark` — the theme.
+
+Any `role` you set on the block is preserved and appended.
+
+In HTML the roles appear as classes on the image block, so you can style them
+with CSS:
+
+[source,css]
+----
+.imageblock.ldl { margin-block: 1.5rem; }
+.imageblock.ldl img { max-width: 100%; }
+.imageblock.ldl-dark { background: #1b1b1f; padding: 0.5rem; border-radius: 6px; }
+----
+
+In `asciidoctor-pdf`, target the same roles from your theme (roles map to
+`role_<name>` keys). For example, to centre and pad LDL diagrams:
+
+[source,yaml]
+----
+role:
+  ldl:
+    align: center
+  ldl-dark:
+    background-color: '1B1B1F'
+----
+
+Because the roles are stable, a document-wide look needs no per-block markup.
+
+== Caching
+
+Rendered files are content-addressed and cached: the source plus the resolved
+options (format, scale, theme, label toggles, and the gem version) are hashed
+into a small sidecar (`<image>.ldlcache`). On the next build, an unchanged
+diagram is reused and Node is not invoked. Editing the diagram or changing an
+option transparently regenerates it. Disable with `-a ldl-cache=false`.
+
+Generated images are written to the usual Asciidoctor image output location —
+`imagesoutdir` if set, otherwise `imagesdir` under the output directory — so
+they interoperate with the rest of your image pipeline.
+
+== Error handling
+
+If a diagram fails to parse or render, the extension emits a visible error block
+(role `ldl-error`) with the message and logs a warning, rather than aborting the
+whole conversion. This keeps a single broken diagram from failing a large book.
+
+== Example document
+
+[source]
+----
+= Protection Scheme
+:ldl-format: svg
+:ldl-theme: light
+:imagesdir: images
+
+== Transformer trip
+
+[ldl,xfmr-trip]
+....
+TRIP.Name = "Transformer trip"
+DIFF.Name = "Differential (87T)"
+OC.Name   = "Overcurrent (50/51)"
+BUCH.Name = "Buchholz (63)"
+TRIP = DIFF OR OC OR BUCH
+....
+
+== SEL-style seal-in (from a file)
+
+ldl::diagrams/seal-in.ldl[]
+----
+
+Convert to HTML and PDF:
+
+[source,console]
+----
+$ asciidoctor      -r asciidoctor-ldl protection-scheme.adoc
+$ asciidoctor-pdf  -r asciidoctor-ldl protection-scheme.adoc
+----
+
+== Development
+
+[source,console]
+----
+$ bundle install
+$ (cd test/js && npm install)     # LDL package + resvg for the test suite
+$ bundle exec rake test           # Ruby unit + end-to-end tests
+$ bundle exec rake jstest         # Node helper tests
+----
+
+The Ruby end-to-end tests convert real AsciiDoc through Asciidoctor and assert on
+the generated files, roles and markup. They resolve the npm package from
+`test/js` (or `LDL_PACKAGE_DIR`) and skip cleanly if Node or the package is
+unavailable.
+
+== Releasing
+
+Releases publish to RubyGems via https://guides.rubygems.org/trusted-publishing/[Trusted
+Publishing] (OIDC) — no API key is stored in the repository. Push a version tag
+(`git tag v0.1.0 && git push origin v0.1.0`) and the `Release` workflow builds,
+tests and publishes the gem. Configure the trusted publisher once on RubyGems to
+match `.github/workflows/release.yml`.
+
+== License
+
+MIT © Daniel Mulholland. See link:LICENSE[].

data/lib/asciidoctor/ldl/extension.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'asciidoctor'
+require 'asciidoctor/extensions'
+require_relative 'version'
+require_relative 'renderer'
+
+module Asciidoctor
+  module Ldl
+    # Shared behaviour for the block and block-macro processors: read options
+    # from attributes, drive the Renderer, and emit an image (or, on failure,
+    # a visible error block).
+    module Processor
+      # Turn LDL +source+ into an image block placed in +parent+.
+      def render_ldl(parent, source, attrs, target_hint)
+        doc = parent.document
+        renderer = build_renderer(doc, attrs)
+        out_dir = renderer.out_dir
+
+        begin
+          filename = renderer.render(source, resolve_basename(attrs, target_hint))
+        rescue Renderer::Error => e
+          return error_block(parent, attrs, e.message)
+        end
+
+        create_ldl_image(parent, attrs, filename, renderer, doc)
+      end
+
+      private
+
+      def build_renderer(doc, attrs)
+        Renderer.new(
+          format: attr(attrs, doc, 'format', 'ldl-format', 'svg'),
+          scale: attr(attrs, doc, 'scale', 'ldl-scale', nil),
+          theme: attr(attrs, doc, 'theme', 'ldl-theme', 'light'),
+          show_ids: attr(attrs, doc, 'show-ids', 'ldl-show-ids', nil),
+          show_labels: attr(attrs, doc, 'show-labels', 'ldl-show-labels', nil),
+          node: doc.attr('ldl-node', 'node'),
+          package_dir: doc.attr('ldl-package-dir') || doc.attr('ldl-node-modules'),
+          out_dir: image_output_dir(doc),
+          cache: cache_enabled?(doc)
+        )
+      end
+
+      # Block/macro attribute wins; otherwise the document attribute; otherwise
+      # the default. Empty strings are treated as "unset".
+      def attr(attrs, doc, block_key, doc_key, default)
+        value = attrs[block_key]
+        value = doc.attr(doc_key) if value.nil? || value.to_s.empty?
+        value.nil? || value.to_s.empty? ? default : value
+      end
+
+      def cache_enabled?(doc)
+        raw = doc.attr('ldl-cache')
+        return true if raw.nil?
+
+        !%w[false 0 no off].include?(raw.to_s.strip.downcase)
+      end
+
+      def resolve_basename(attrs, target_hint)
+        candidate = attrs['target'] || target_hint
+        return nil if candidate.nil? || candidate.to_s.strip.empty?
+
+        candidate
+      end
+
+      # Physical directory the image is written to, following the same
+      # conventions as asciidoctor-diagram (imagesoutdir overrides; otherwise
+      # imagesdir under the output/base directory).
+      def image_output_dir(doc)
+        images_outdir = doc.attr('imagesoutdir')
+        return images_outdir if images_outdir && !images_outdir.to_s.empty?
+
+        base = doc.attr('outdir')
+        base = doc.options[:to_dir] if (base.nil? || base.empty?) && doc.options[:to_dir]
+        base ||= doc.base_dir
+        images_dir = doc.attr('imagesdir')
+        (images_dir && !images_dir.to_s.empty?) ? File.join(base, images_dir) : base
+      end
+
+      def create_ldl_image(parent, attrs, filename, renderer, _doc)
+        image_attrs = { 'target' => filename }
+        %w[alt title width height align float id link].each do |key|
+          image_attrs[key] = attrs[key] if attrs.key?(key)
+        end
+        image_attrs['alt'] ||= (attrs['target'] || 'LDL logic diagram')
+        image_attrs['role'] = image_roles(attrs, renderer)
+        create_image_block(parent, image_attrs)
+      end
+
+      # Always tag the image with the +ldl+ role plus format/theme modifier
+      # roles, so it can be targeted from CSS or an asciidoctor-pdf theme.
+      # Any author-supplied role is preserved (and wins for ordering).
+      def image_roles(attrs, renderer)
+        roles = %w[ldl]
+        roles << "ldl-#{renderer.format}"
+        roles << "ldl-#{renderer.theme}"
+        author = attrs['role']
+        roles.concat(author.to_s.split) if author && !author.to_s.empty?
+        roles.uniq.join(' ')
+      end
+
+      def error_block(parent, attrs, message)
+        warn "asciidoctor-ldl: #{message}"
+        text = "LDL diagram error:\n#{message}"
+        Asciidoctor::Block.new(parent, :listing, source: text,
+                                                 attributes: { 'role' => 'ldl-error' })
+      end
+    end
+
+    # Delimited block:
+    #
+    #   [ldl]
+    #   ----
+    #   O1 = I1 AND NOT I2
+    #   ----
+    #
+    # Optional positional attributes: [ldl, target-basename, format].
+    class BlockProcessor < Asciidoctor::Extensions::BlockProcessor
+      include Processor
+
+      use_dsl
+      named :ldl
+      on_contexts :listing, :literal, :paragraph, :open
+      name_positional_attributes 'target', 'format'
+      parse_content_as :raw
+
+      def process(parent, reader, attrs)
+        render_ldl(parent, reader.source, attrs, attrs['target'])
+      end
+    end
+
+    # Block macro reading from a file:
+    #
+    #   ldl::path/to/diagram.ldl[format=png, scale=2]
+    class BlockMacroProcessor < Asciidoctor::Extensions::BlockMacroProcessor
+      include Processor
+
+      use_dsl
+      named :ldl
+      name_positional_attributes 'format'
+
+      def process(parent, target, attrs)
+        doc = parent.document
+        path = doc.normalize_system_path(target, doc.attr('docdir'))
+        unless File.readable?(path)
+          return error_block(parent, attrs, "cannot read LDL file: #{target}")
+        end
+
+        source = File.read(path)
+        hint = attrs['target'] || File.basename(target, File.extname(target))
+        render_ldl(parent, source, attrs, hint)
+      end
+    end
+  end
+end

data/lib/asciidoctor/ldl/js/ldl_render.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+// ldl_render.mjs — render LDL source to SVG or PNG for the asciidoctor-ldl gem.
+//
+// Contract (kept deliberately small so the Ruby side is easy to drive):
+//   * LDL source is read from stdin.
+//   * Options come from CLI flags (see parseArgs below).
+//   * The rendered artifact is written to the path given by --out.
+//   * On success nothing is written to stdout; a one-line JSON summary
+//     ({"format","width","height","out"}) is written to stderr for logging.
+//   * On failure a human-readable message is written to stderr and the
+//     process exits non-zero.
+//
+// SVG rendering is isomorphic (only needs @openpowershift/logic-diagram-language).
+// PNG rendering additionally needs @resvg/resvg-js, resolved lazily so an
+// SVG-only install never has to have it present.
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join, resolve, isAbsolute } from 'node:path';
+
+const PACKAGE = '@openpowershift/logic-diagram-language';
+
+// Resolve an installed package's ESM entry point from a base directory,
+// without relying on a `require` export condition (the LDL package is
+// ESM-only, so `require.resolve(pkg)` throws ERR_PACKAGE_PATH_NOT_EXPORTED).
+// The `./package.json` subpath *is* exported, so resolve that and read the
+// declared entry ourselves. Returns a file:// URL string, or null.
+function resolveEntryFrom(base, pkg) {
+  let pkgJsonPath;
+  try {
+    const req = createRequire(pathToFileURL(join(base, 'package.json')).href);
+    pkgJsonPath = req.resolve(`${pkg}/package.json`);
+  } catch (_) {
+    return null;
+  }
+  const meta = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+  const dot = meta.exports && meta.exports['.'];
+  const entry =
+    (dot && typeof dot === 'object' && (dot.import || dot.default)) ||
+    (typeof dot === 'string' ? dot : null) ||
+    meta.module ||
+    meta.main ||
+    'index.js';
+  return pathToFileURL(resolve(dirname(pkgJsonPath), entry)).href;
+}
+
+// Candidate base directories to search, in priority order.
+function candidateBases(packageDir) {
+  const bases = [];
+  if (packageDir) bases.push(packageDir);
+  if (process.env.LDL_PACKAGE_DIR) bases.push(process.env.LDL_PACKAGE_DIR);
+  bases.push(process.cwd());
+  bases.push(dirname(fileURLToPath(import.meta.url)));
+  return bases;
+}
+
+function parseArgs(argv) {
+  const opts = {
+    format: 'svg',
+    scale: 1,
+    theme: 'light',
+    showIds: false,
+    showLabels: true,
+    out: null,
+    packageDir: null,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = () => argv[++i];
+    switch (arg) {
+      case '--format': opts.format = String(next()).toLowerCase(); break;
+      case '--scale': opts.scale = Number(next()); break;
+      case '--theme': opts.theme = String(next()).toLowerCase(); break;
+      case '--show-ids': opts.showIds = true; break;
+      case '--no-show-ids': opts.showIds = false; break;
+      case '--show-labels': opts.showLabels = true; break;
+      case '--no-show-labels': opts.showLabels = false; break;
+      case '--out': opts.out = next(); break;
+      case '--package-dir': opts.packageDir = next(); break;
+      default:
+        throw new Error(`unknown argument: ${arg}`);
+    }
+  }
+  if (!opts.out) throw new Error('missing required --out <path>');
+  if (!Number.isFinite(opts.scale) || opts.scale <= 0) {
+    throw new Error(`invalid --scale: ${opts.scale}`);
+  }
+  if (opts.format !== 'svg' && opts.format !== 'png') {
+    throw new Error(`unsupported --format: ${opts.format} (expected svg or png)`);
+  }
+  return opts;
+}
+
+// Resolve the LDL package from a set of candidate base directories, so it can
+// live in the user's project, a globally installed location, or a checkout
+// pointed at by --package-dir / LDL_PACKAGE_DIR.
+async function loadLibrary(packageDir) {
+  const tried = [];
+  for (const base of candidateBases(packageDir)) {
+    // Allow a base that points straight at a package checkout (…/lib/index.js).
+    for (const direct of [join(base, 'lib', 'index.js'), join(base, 'index.js')]) {
+      try {
+        return await import(pathToFileURL(direct).href);
+      } catch (e) { tried.push(`${direct} (${e.code || 'error'})`); }
+    }
+    // Otherwise resolve it as an installed dependency from that base.
+    const entry = resolveEntryFrom(base, PACKAGE);
+    if (entry) {
+      try {
+        return await import(entry);
+      } catch (e) { tried.push(`${entry} (${e.code || 'error'})`); }
+    } else {
+      tried.push(`${base}:${PACKAGE} (not found)`);
+    }
+  }
+  throw new Error(
+    `could not resolve ${PACKAGE}.\n` +
+    `Install it where your document is built, e.g.\n` +
+    `  npm install ${PACKAGE}\n` +
+    `or point the ldl-package-dir attribute / LDL_PACKAGE_DIR env var at it.\n` +
+    `Searched:\n  ${tried.join('\n  ')}`);
+}
+
+async function loadResvg(packageDir) {
+  for (const base of candidateBases(packageDir)) {
+    try {
+      const req = createRequire(pathToFileURL(join(base, 'package.json')).href);
+      return await import(pathToFileURL(req.resolve('@resvg/resvg-js')).href);
+    } catch (_) { /* try next */ }
+    const entry = resolveEntryFrom(base, '@resvg/resvg-js');
+    if (entry) {
+      try { return await import(entry); } catch (_) { /* try next */ }
+    }
+  }
+  throw new Error(
+    'PNG output needs @resvg/resvg-js, which was not found.\n' +
+    'Install it alongside the LDL package:\n' +
+    '  npm install @resvg/resvg-js\n' +
+    'or use format=svg (the default), which needs no extra dependency and is\n' +
+    'ideal for asciidoctor-pdf (vector, scalable, compact).');
+}
+
+// The renderer emits <svg viewBox="0 0 W H" …> with no intrinsic width/height.
+// Add them (scaled) so downstream consumers — prawn-svg in asciidoctor-pdf,
+// browsers, resvg — get a concrete size and the scale attribute is honoured.
+function sizeFromViewBox(svg) {
+  const m = svg.match(/viewBox="0 0 ([\d.]+) ([\d.]+)"/);
+  if (!m) return null;
+  return { width: parseFloat(m[1]), height: parseFloat(m[2]) };
+}
+
+function applySvgScale(svg, scale) {
+  const size = sizeFromViewBox(svg);
+  if (!size) return { svg, size };
+  const w = size.width * scale;
+  const h = size.height * scale;
+  // Insert width/height right after "<svg"; drop the max-width/height clamp so
+  // an explicit size actually takes effect when embedded as an image.
+  const scaled = svg
+    .replace(/<svg/, `<svg width="${w}" height="${h}"`)
+    .replace(/\s*max-width:100%;max-height:100%;/, '');
+  return { svg: scaled, size: { width: w, height: h } };
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const source = readFileSync(0, 'utf8'); // fd 0 = stdin
+
+  const lib = await loadLibrary(opts.packageDir);
+  const { parse, renderDiagram, resolveOptions, LIGHT_DIAGRAM, DARK_DIAGRAM } = lib;
+
+  const { diagram, errors } = parse(source);
+  if (errors && errors.length) {
+    const lines = errors.map((e) => {
+      const pos = e.position ? ` (line ${e.position.line}, col ${e.position.column})` : '';
+      return `  ${e.message}${pos}`;
+    });
+    throw new Error(`LDL parse error:\n${lines.join('\n')}`);
+  }
+
+  const renderOptions = resolveOptions(diagram.options);
+  renderOptions.showIds = opts.showIds;
+  renderOptions.showLabels = opts.showLabels;
+  const theme = opts.theme === 'dark' ? DARK_DIAGRAM : LIGHT_DIAGRAM;
+
+  let svg = renderDiagram(diagram, renderOptions, theme);
+  const scaled = applySvgScale(svg, opts.scale);
+  svg = scaled.svg;
+  const size = scaled.size || { width: 0, height: 0 };
+
+  const outPath = isAbsolute(opts.out) ? opts.out : join(process.cwd(), opts.out);
+
+  if (opts.format === 'svg') {
+    writeFileSync(outPath, svg, 'utf8');
+    process.stderr.write(JSON.stringify({ format: 'svg', width: size.width, height: size.height, out: outPath }) + '\n');
+    return;
+  }
+
+  // PNG
+  const { Resvg } = await loadResvg(opts.packageDir);
+  // Rasterise from the *unscaled* viewBox using resvg's own zoom, so the scale
+  // multiplies device pixels crisply rather than baking a size into the SVG.
+  const base = renderDiagram(diagram, renderOptions, theme);
+  const resvg = new Resvg(base, {
+    fitTo: { mode: 'zoom', value: opts.scale },
+    background: 'white',
+  });
+  const rendered = resvg.render();
+  const png = rendered.asPng();
+  writeFileSync(outPath, png);
+  process.stderr.write(JSON.stringify({ format: 'png', width: rendered.width, height: rendered.height, out: outPath }) + '\n');
+}
+
+main().catch((err) => {
+  process.stderr.write(`[asciidoctor-ldl] ${err && err.message ? err.message : err}\n`);
+  process.exit(1);
+});

data/lib/asciidoctor/ldl/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Asciidoctor
+  module Ldl
+    VERSION = '0.1.0'
+  end
+end

data/lib/asciidoctor/ldl.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'ldl/version'
+require_relative 'ldl/renderer'
+require_relative 'ldl/extension'
+
+module Asciidoctor
+  module Ldl
+    # Register the block and block-macro processors with an Asciidoctor
+    # extension registry (defaults to the global one).
+    def self.register(registry = Asciidoctor::Extensions)
+      registry.block Asciidoctor::Ldl::BlockProcessor, :ldl
+      registry.block_macro Asciidoctor::Ldl::BlockMacroProcessor, :ldl
+    end
+  end
+end
+
+Asciidoctor::Extensions.register do
+  block Asciidoctor::Ldl::BlockProcessor, :ldl
+  block_macro Asciidoctor::Ldl::BlockMacroProcessor, :ldl
+end

data/lib/asciidoctor-ldl.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Conventional require name (matches the gem name) so that:
+#   asciidoctor -r asciidoctor-ldl document.adoc
+# works. Delegates to the namespaced implementation.
+require_relative 'asciidoctor/ldl'

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: asciidoctor-ldl
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniel Mulholland
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: asciidoctor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |
+  An Asciidoctor extension that renders protection-relay / logic diagrams
+  written in the Logic Diagram Language (LDL) — the
+  @openpowershift/logic-diagram-language npm package — into SVG or PNG at
+  conversion time. SVG output is vector and embeds cleanly in asciidoctor-pdf;
+  PNG is available via @resvg/resvg-js. Format, scale, theme and label
+  visibility are controlled with AsciiDoc attributes.
+email:
+- dan.mulholland@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.adoc
+- lib/asciidoctor-ldl.rb
+- lib/asciidoctor/ldl.rb
+- lib/asciidoctor/ldl/extension.rb
+- lib/asciidoctor/ldl/js/ldl_render.mjs
+- lib/asciidoctor/ldl/renderer.rb
+- lib/asciidoctor/ldl/version.rb
+homepage: https://github.com/OpenPowerShift/asciidoctor-ldl
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/OpenPowerShift/asciidoctor-ldl
+  source_code_uri: https://github.com/OpenPowerShift/asciidoctor-ldl
+  bug_tracker_uri: https://github.com/OpenPowerShift/asciidoctor-ldl/issues
+  changelog_uri: https://github.com/OpenPowerShift/asciidoctor-ldl/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Asciidoctor extension for OpenPowerShift LDL logic diagrams
+test_files: []