DEV Community: river

Convert a PNG Sequence to Transparent WebM with FFmpeg

river — Sat, 31 Oct 2026 17:31:41 +0000

The PNG frames are transparent. The exported video has a black rectangle. Running background removal again seems like the obvious fix, but it can be the wrong step: the alpha channel may have disappeared during encoding, or the player may simply be ignoring it.

To convert an existing transparent PNG sequence to WebM, use FFmpeg with libvpx-vp9 and an alpha-capable pixel format. Then decode the output and check it. Renaming a file to .webm does not create transparency, and a successful encode does not prove that transparency survived.

This walkthrough uses real footage, an opaque control, and a frame-by-frame comparison. There is also a small result worth keeping in mind: in this particular run, the largest alpha difference was one level out of 255, even with the encoder's lossless option enabled.

The source cutout is the public podcast demo from BG Remover Online. Original footage: Mixkit, “Bearded announcer, close up”. The person shown is not affiliated. The processed cutout also removes the microphone; it is not a perfect subject-selection example. The backgrounds in the figure are display layers, not baked into the PNG.

Start with frames that already contain transparency

A PNG can contain alpha, but it can also be completely opaque. Open a frame above two different solid backgrounds. The empty area around the subject should reveal each background. A checkerboard that stays fixed inside the image may be ordinary image pixels.

Keep the frames in a dedicated directory with matching dimensions and continuous numbering:

frames/
  frame_0001.png
  frame_0002.png
  frame_0003.png
  ...

The command below expects four digits and a first frame numbered 0001. Use %03d for three digits, or change -start_number if your sequence begins elsewhere. A missing number can make a sequence end early. Check how many frames you actually encoded.

For the same conversion in a browser, the PNG sequence to transparent WebM converter accepts a ZIP of PNG frames and outputs VP9-alpha WebM. Google sign-in is required; check the current file limits before uploading. This is an alternative workflow, not the workflow benchmarked below.

This step packages existing cutouts into video. If your starting point is an ordinary MP4 with a room behind the presenter, you still need a separate matting, masking, or keying step. A pixel-format flag cannot identify which parts of that room to remove.

Encode the sequence

Use an FFmpeg build with the libvpx-vp9 encoder. In a terminal, check its availability:

ffmpeg -h encoder=libvpx-vp9

Then run this from the directory containing frames:

ffmpeg -framerate 12 -start_number 1 -i "frames/frame_%04d.png" -c:v libvpx-vp9 -pix_fmt yuva420p -lossless 1 -auto-alt-ref 0 cutout.webm

This is the encoding command used in the experiment. If cutout.webm already exists, FFmpeg asks before overwriting it. Use a new output name when comparing settings.

Setting	What it controls
`-framerate 12`	Reads the sequence at 12 frames per second. Set it to the rate your frames were created for.
`-start_number 1`	Starts at `frame_0001.png`.
`-c:v libvpx-vp9`	Selects the VP9 encoder used here.
`-pix_fmt yuva420p`	Requests an alpha-capable pixel format. The `a` matters.
`-lossless 1`	Enables the encoder's lossless mode. It does not promise that every conversion around the encoder is numerically lossless.
`-auto-alt-ref 0`	Disables alternate reference frames; this is the setting used for the tested alpha workflow.

Input frame rate belongs before -i. In this example, 24 frames at 12 fps produce two seconds of video. Reading the same files at 24 fps produces one second. Neither command reconstructs the original timing of an irregularly timed sequence.

FFmpeg documents the numbering and frame-rate behavior in its image2 input documentation.

The result has no audio because the input contains only images. If you need sound, preserve it separately and align it against the final duration. Do not assume changing the frame rate will keep an existing voice track in sync.

What the real-footage test showed

The test ran on Windows with FFmpeg 8.0.1. Its input was an already processed BG Remover Online demo cutout, not a newly submitted background-removal job.

The setup extracted the first two seconds at 12 fps, resized to 640 × 360, and wrote 24 RGBA PNGs. That extraction explicitly used the libvpx VP9 decoder so the existing WebM alpha could be retained:

ffmpeg -c:v libvpx-vp9 -i podcast-after-alpha.webm -t 2 -vf "fps=12,scale=640:360" -pix_fmt rgba -start_number 1 "frames/frame_%04d.png"

Create the frames directory first. You can skip this extraction entirely when you already have your own PNG sequence. For a browser-based reverse workflow, the video to PNG sequence converter returns RGBA PNG frames in a ZIP.

After encoding, every output frame was decoded to RGBA and its alpha bytes were compared with the corresponding PNG. The result:

Observation	Result
PNG frames read / WebM frames decoded	24 / 24
Output dimensions	640 × 360
Output frame rate / duration	12 fps / 2.000 seconds
Output file size	1,056,049 bytes
Alpha range in every decoded frame	0–255
Largest absolute alpha difference across all 24 frames	1
Bit-identical alpha across every frame	No

That last row is easy to miss. On the first frame, 89,034 alpha values differed, but no value differed by more than one. The count of completely transparent pixels remained 137,838. Many near-opaque values became fully opaque.

This does not establish which internal step caused the difference, or predict another FFmpeg build's behavior. It establishes what this complete workflow produced. If your acceptance criterion is “a visible cutout with transparent surroundings,” these observations are relevant. If it is “preserve every alpha byte exactly,” this run fails that stricter requirement.

RGB equality was not tested or claimed. The requested output uses YUV 4:2:0, so preserving alpha is a separate question from retaining all source color detail.

Decode the output before trusting the metadata

First, extract a PNG with the libvpx decoder selected before the input:

ffmpeg -c:v libvpx-vp9 -i cutout.webm -frames:v 1 check.png

Open check.png in an image editor over light and dark backgrounds. For a clearer look at opacity itself, extract the alpha plane:

ffmpeg -c:v libvpx-vp9 -i cutout.webm -vf alphaextract -frames:v 1 alpha.png

In alpha.png, black means transparent, white means opaque, and gray means partially opaque. It is a grayscale diagnostic image, not a second cutout. See FFmpeg's alphaextract documentation.

In this run, ffprobe reported pix_fmt=yuv420p alongside alpha_mode=1 for a file whose decoded frames contained transparency. Therefore, that pixel-format field alone was not a reliable rejection rule. Conversely, alpha metadata alone does not establish that any pixel is actually transparent.

The control made that distinction visible. The same sequence was encoded with yuv420p, without the a. Its first decoded frame had alpha 255 everywhere: an opaque rectangle. That is the sort of output a conversion pipeline can create while still returning a playable video.

Checking the first frame is a quick diagnostic, not a whole-clip guarantee. The 24-frame comparison above inspected this entire short fixture; a longer production export needs its own inspection scope.

Put it over the actual page background

A file-level check does not answer whether the destination browser composites it correctly. Save this next to cutout.webm as preview.html:

<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Transparent WebM check</title>
<style>
  .stage { max-width: 640px; background: #17263d; }
  .stage.light { background: #f5ead6; }
  video { display: block; width: 100%; }
</style>
<button type="button" id="background">Switch background</button>
<div class="stage" id="stage">
  <video controls muted loop playsinline preload="metadata"
    src="cutout.webm"></video>
</div>
<script>
  document.querySelector('#background').addEventListener('click', () => {
    document.querySelector('#stage').classList.toggle('light');
  });
</script>
</html>

Play it, switch backgrounds, and look at hair, fingers, and motion-blurred edges. A flat rectangle suggests opaque pixels or an unsupported playback path. A changing background with halos suggests a different problem: the matte or color edges need work.

Do not use CSS mix-blend-mode: screen as proof that transparency works. It can hide dark pixels while also changing the subject. A real alpha channel should composite without that workaround.

Browser support needs its own check. Chrome documents WebM alpha playback. MDN's codec guide notes that Safari does not support VP9 alpha. This experiment did not test Safari. Keep a tested fallback for browsers outside your validated path; a static transparent PNG may be enough for a decorative animation.

For an editing handoff rather than a web page, the transparent WebM to ProRes 4444 converter provides an alpha-capable MOV workflow for editing software. ProRes is an editing format, not a substitute for a tested browser delivery format. These online converters require sign-in and have usage limits; they were not part of the local FFmpeg benchmark above.

When the result still looks wrong

Symptom	Check next
“Unknown encoder libvpx-vp9”	Use a build that includes the encoder; the filename extension cannot substitute for it.
Video stops earlier than expected	Check continuous numbering, the first-frame index, the encoded frame count, and input frame rate.
Solid background in the extracted PNG	Confirm the source PNG has alpha, the encoding requested `yuva420p`, and the decoding used libvpx.
PNG is transparent, player shows black	Test another known alpha-aware playback path before repeating background removal.
Dark or bright fringes around hair	Inspect the source matte and color treatment on both backgrounds. Conversion does not repair an inaccurate cutout.
File is too large	Evaluate a separate constant-quality encode against the lossless baseline, comparing edges and alpha as well as file size.

For a delivery-sized experiment, a common starting point is -crf 30 -b:v 0 in place of -lossless 1. That variation was not benchmarked in the recorded run. Recheck its output rather than applying the lossless run's measurements to it.

The useful handoff is the encoded file plus a check in its destination. Keep the PNG sequence until both have passed. It is the easiest way to change the encoding later without paying for another matting pass or discarding the best source you have.

Context and reproducibility: This walkthrough accompanies the BG Remover Online project and uses its existing public demo asset. It is a conversion experiment, not an independent product comparison or a claim about all background-removal results. The recorded run was executed on November 1, 2026; its script and raw observations are retained with the draft.

AI disclosure: This article was drafted by an AI agent. The stated FFmpeg experiment was executed; browser compatibility beyond the documented references is not presented as a firsthand test.

Test Video Transparency in CI with FFmpeg and Node.js

river — Mon, 26 Oct 2026 08:42:17 +0000

A video looks cut out in a preview. Then you place it over a dark page, and a rectangle appears around the presenter. Before an export reaches production, the useful question is whether decoded pixels actually let the new background show through.

Start with a real example. The images below come from an original podcast clip and its processed transparent WebM, decoded locally. The same output frame is shown on a checkerboard, a dark background, and a light background.

Public BG Remover Online demo, using stock footage from Mixkit: “Bearded announcer, close up”. The person shown is not affiliated. The images are actual frames requested at 0.4 seconds; comparison backgrounds are added here. The processing also removed the foreground microphone.

An independent run of the inspector reported transparency-detected for this 1920 × 1080, 3.753-second VP9 file. At all four requested sample times—0, 0.93825, 1.8765, and 2.81475 seconds—the decoded alpha range included both 0 and 255. Each sample also contained partially transparent pixels. These observations establish sampled alpha presence, not a whole-clip matting-quality score.

With the source checkout and FFmpeg below installed, reproduce that check on the public file:

curl -fL https://bgremover.online/demo/podcast-after-alpha.webm -o podcast-alpha.webm
node dist/cli.js podcast-alpha.webm --json --require-transparency

Real footage shows why the check matters. For a regression test, we also need inputs with known intent: a useful cutout, an opaque video, an invisible video, and a brief alpha change between sample times. The rest of this tutorial creates those controls and turns the sampled condition into a CI gate.

Decide what a passing export means

For a reusable cutout, there are at least two requirements:

Some sampled pixels let the background show through.
Some sampled pixels remain visible.

That policy rejects an entirely invisible clip. It also differs from “the format supports alpha” and “this player shows the correct result.”

The experiment uses video-alpha-inspector, a standalone Node.js wrapper around local FFmpeg decoding. It reports metadata separately from pixel observations.

Its default 8-bit alpha rules are:

Rule	Default
Transparent pixel	Alpha below 245
Visible pixel	Alpha above 10
Significant amount	At least 1% of sampled pixels, rounded up
Requested times	0%, 25%, 50%, and 75% of reported duration

The two pixel categories intentionally overlap: a partly transparent pixel can still be visible. The aggregate passing status can also combine transparency in one sampled frame with visibility in another. If a pipeline requires both in the same frame, it needs a stricter per-sample policy.

Reproduce the run

Use Node.js 22 or newer, plus FFmpeg and ffprobe on PATH. The FFmpeg build needs the libvpx-vp9 encoder and decoder for this experiment.

npm publication is pending, so use the source checkout:

git clone https://github.com/j-river/video-alpha-inspector.git
cd video-alpha-inspector
git checkout a20d1844535111b139ca7ec2524c5c944f897906
npm ci --ignore-scripts
npm run build

The results below were produced on Windows with Node.js 24.13.1 and FFmpeg/ffprobe 8.0.1. Different FFmpeg builds should be checked rather than assumed equivalent.

Generate controls with known intent

Save this as make-fixtures.mjs in the repository root:

Open the fixture generator: four synthetic videos

import { mkdirSync } from 'node:fs';
import { join } from 'node:path';
import { spawnSync } from 'node:child_process';

const directory = process.argv[2] ?? 'alpha-fixtures';
mkdirSync(directory, { recursive: true });

function generate(name, duration, filter) {
  const result = spawnSync('ffmpeg', [
    '-nostdin', '-hide_banner', '-loglevel', 'error',
    '-f', 'lavfi', '-i',
    `color=c=blue:s=64x64:r=10:d=${duration},format=rgba`,
    '-vf', filter + ',format=yuva420p',
    '-c:v', 'libvpx-vp9', '-lossless', '1',
    '-auto-alt-ref', '0', '-g', '9999', '-threads', '1',
    '-deadline', 'realtime', '-y', join(directory, name),
  ], { encoding: 'utf8', windowsHide: true, timeout: 60_000 });
  if (result.error) throw result.error;
  if (result.status !== 0) throw new Error(result.stderr);
}

generate('cutout.webm', 1,
  'colorchannelmixer=aa=0,drawbox=x=16:y=16:w=32:h=32:color=blue@1:t=fill:replace=1');
generate('tagged-opaque.webm', 1, 'colorchannelmixer=aa=1');
generate('empty.webm', 1, 'colorchannelmixer=aa=0');
generate('brief-alpha.webm', 4,
  "colorchannelmixer=aa=0.5:enable='between(t,1.2,1.7)'");

console.log('Generated four synthetic VP9-alpha fixtures.');

Run:

node make-fixtures.mjs

The files contain synthetic colors and a square, with no downloaded footage:

cutout.webm: an opaque square on a transparent canvas.
tagged-opaque.webm: a fully opaque alpha plane.
empty.webm: alpha zero everywhere.
brief-alpha.webm: a four-second clip with partial alpha only around 1.2–1.7 seconds.

The generator enables the alpha encoding path for every control. The inspection below checks what actually survived encoding.

These commands overwrite the named files inside alpha-fixtures. Keep that folder separate from source media.

The blue squares are deliberately simple regression controls, separate from the real footage above. The fourth column uses a focused request near 1.4 seconds.

Inspect pixels, then compare the outcomes

Save this as inspect-fixtures.mjs in the same repository root:

Open the inspection script and assertions

import assert from 'node:assert/strict';
import { join } from 'node:path';
import { inspectVideoAlpha } from './dist/index.js';

const directory = process.argv[2] ?? 'alpha-fixtures';
const expected = {
  'cutout.webm': 'transparency-detected',
  'tagged-opaque.webm': 'no-transparency-observed',
  'empty.webm': 'fully-transparent-samples',
  'brief-alpha.webm': 'no-transparency-observed',
};
const rows = [];
for (const [file, status] of Object.entries(expected)) {
  const report = await inspectVideoAlpha(join(directory, file));
  assert.equal(report.status, status);
  if (file === 'cutout.webm') {
    assert.ok(report.samples.every(sample => sample.alpha.min === 0 && sample.alpha.max === 255));
  } else if (file === 'empty.webm') {
    assert.ok(report.samples.every(sample => sample.alpha.min === 0 && sample.alpha.max === 0));
  } else {
    assert.ok(report.samples.every(sample => sample.alpha.min === 255 && sample.alpha.max === 255));
  }
  rows.push({
    file,
    alphaMetadata: report.video.alphaMetadata,
    pixelFormat: report.video.pixelFormat,
    status: report.status,
    alphaMin: report.samples[0].alpha.min,
    alphaMax: report.samples[0].alpha.max,
    samples: report.samples.length,
  });
}

const focused = await inspectVideoAlpha(
  join(directory, 'brief-alpha.webm'),
  { sampleFractions: [0.35] },
);
assert.equal(focused.status, 'transparency-detected');

console.log(JSON.stringify({
  rows,
  focused: {
    fraction: 0.35,
    requestedTimeSeconds: focused.samples[0].requestedTimeSeconds,
    status: focused.status,
    alphaMin: focused.samples[0].alpha.min,
    alphaMax: focused.samples[0].alpha.max,
  },
}, null, 2));

Run node inspect-fixtures.mjs. The assertions passed, with these observations:

File	Alpha metadata	ffprobe pixel format	Default sampled alpha	Status
cutout.webm	true	yuv420p	Values include 0 and 255	transparency-detected
tagged-opaque.webm	true	yuv420p	All 255	no-transparency-observed
empty.webm	true	yuv420p	All 0	fully-transparent-samples
brief-alpha.webm	true	yuv420p	All 255 at requested samples	no-transparency-observed

Here, all four files have the same metadata hint and reported pixel format. Their decoded content leads to three different statuses.

That is why a metadata-only gate cannot make the decision. This library explicitly selects the libvpx decoder for VP8/VP9 to preserve the WebM alpha data, then measures the decoded alpha plane. FFmpeg's alphaextract filter documentation describes the underlying extraction operation.

This experiment establishes the behavior of these fixtures and this decode path. It does not establish transparency support in every browser or video player.

The red requests miss the green interval. A focused 35% request reveals the partial alpha; requested times are not exact decoded timestamps.

The control that the default sampling misses

The fourth fixture is four seconds long. Default sampling requests frames around 0, 1, 2, and 3 seconds. Its partial transparency occurs between two of those requests.

The additional sampleFractions: [0.35] call asks for a frame around 1.4 seconds. In this run, it returned:

{
  "requestedTimeSeconds": 1.4,
  "status": "transparency-detected",
  "alphaMin": 129,
  "alphaMax": 129
}

The measured alpha is near half opacity. Its exact 8-bit value should not be generalized to every encoding path.

More importantly, the default negative result did not mean “this clip contains no transparent frames.” It meant no qualifying transparency was observed in the requested samples.

The requested seek time is not a measured frame timestamp. FFmpeg may return the next available frame. Downscaling can also remove small features from the observations.

If a release requires whole-clip validation, design a bounded full-frame scan with an explicit alpha policy, or inspect all relevant frames in a trusted processing stage. Increasing a sparse sample count still does not turn sampling into a whole-clip guarantee.

A slowed sequence of actual FFmpeg seek observations, not a real-time player recording. Frame requests and decoded alpha ranges are displayed.

Turn the observation into a CI gate

After building, the CLI can require the library's visible-cutout condition:

node dist/cli.js alpha-fixtures/cutout.webm --json --require-transparency

The tested exit-code contract is:

Input	Exit code	Interpretation
cutout.webm	0	The sampled condition passed
tagged-opaque.webm	1	Inspection completed; condition was unmet
empty.webm	1	Inspection completed; no visible cutout was established
missing.webm	2	Inspection failed

In a CI step that already has the repository and required tools, use the command directly so its nonzero exit can fail the step. Preserve the JSON report as an artifact using the CI system's artifact mechanism.

Do not append || true, swallow the exit status, or convert decoder errors into “opaque video.” A missing tool, missing sample, or damaged file is an inspection failure. The JSON report should support diagnosis, not replace the gate's exit status.

This gate is appropriate only if its sampling policy is enough for the pipeline. It does not judge hair quality, temporal shimmer, color fringes, or whether a target application interprets alpha correctly.

Keeping these outcomes separate prevents a missing file or decoder failure from masquerading as a successful inspection.

Keep a player test in the delivery workflow

The browser playground is a separate way to inspect synthetic samples and local WebM files. It uses the browser's decoder and Canvas, so it may observe different behavior from FFmpeg. Local file contents are processed in browser memory.

For a web overlay, retain a check in the destination browser. For an editing handoff, composite the actual output in the destination editor. Passing a decoded-pixel gate answers one part of delivery; those checks answer the remaining parts.

The four fixtures provide a useful starting regression set: useful cutout, opaque false positive, invisible output, and an event between samples.

If you already validate media exports in CI, does the gate promise a sampled observation or a whole-clip property? That distinction determines which files it can safely accept.

Project context: this inspector is maintained alongside BG Remover Online. It neither removes backgrounds nor uploads files, and its production integration into that site is pending.

AI disclosure: this article was drafted with AI. The synthetic fixtures, pixel inspections, assertions, and four CLI exit-code cases were executed against the recorded commit on October 23, 2026.

How to Encode and Decode Mermaid Share Links in JavaScript

river — Sun, 25 Oct 2026 03:32:47 +0000

A teammate sends you an architecture diagram. You can read it, but the next request is to rename a service and change a route. A screenshot has already discarded the useful part: the source.

Here is the result worth preserving: a rendered API gateway diagram with services, databases, and relationships. A share link can carry the Mermaid source so the receiving editor can render—and edit—it again.

Actual Mermaid Online rendering of the separate visual example below. The codec preserved its 715 UTF-8 source bytes exactly; rendering is the editor’s job. The small Unicode test later in this article is a different, 57-byte input.

Open the visual example in the editor. Its source is included here, so the picture does not have to be taken on trust.

Open the Mermaid source used for the rendered architecture

flowchart LR
  Client["Web / Mobile"] -->|HTTPS| Gateway["API Gateway"]
  Gateway --> Auth["Auth Check"]
  Gateway --> Limit["Rate Limit"]
  Auth --> User["User Service"]
  Auth --> Order["Order Service"]
  Auth --> Billing["Billing Service"]
  User --> UserDB[("User DB")]
  Order --> OrderDB[("Order DB")]
  Billing --> Provider["Payment Provider"]
  Limit --> Logs["Observability"]
  classDef entry fill:#dbeafe,stroke:#2563eb,color:#172554
  classDef core fill:#ede9fe,stroke:#7c3aed,color:#2e1065
  classDef data fill:#dcfce7,stroke:#16a34a,color:#14532d
  classDef failure fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
  class Client,Gateway entry
  class Auth,User,Order,Billing core
  class UserDB,OrderDB data

The smaller executable test below then concentrates on the failure-prone details: Chinese text, an emoji, CRLF line endings, configuration, malformed input, and a decoded-size limit.

What the fragment contains

For the pako: format covered here, the pipeline is:

state object
  → JSON
  → UTF-8 bytes
  → zlib-wrapped DEFLATE
  → Base64URL
  → #pako:...

The compressed data is a document, not an image. A minimal state might look like this:

{
  "code": "flowchart LR\n  A-->B",
  "mermaid": "{\"theme\":\"dark\"}"
}

Notice that mermaid is a JSON string, rather than a nested configuration object. That detail follows the recorded Mermaid Live Editor serializer used as a compatibility reference.

The pako: prefix names the format. An implementation can use a different compatible compression library.

There is also an uncompressed base64: variant. A cloud document ID, a site-specific #code= parameter, and an arbitrary Base64 string are different inputs; a decoder should not silently guess that they follow this format.

Each boundary has a different job. The diagram travels as serialized data, without loading a Mermaid renderer.

Run the example from a source checkout

The example uses mermaid-share-codec, an independent MIT project. npm publication is pending, so these instructions use a recorded Git commit rather than a registry install.

Use Node.js 22 or newer. The run reported below used Node.js 24.13.1 on Windows.

git clone https://github.com/j-river/mermaid-share-codec.git
cd mermaid-share-codec
git checkout d3d7c90eab4e5e7cb0fa22dca184e937b3f71d28
npm ci --ignore-scripts
npm run build

Save the following as roundtrip.mjs in that repository's root, then run node roundtrip.mjs.

Open the complete runnable round-trip and failure checks

import assert from 'node:assert/strict';
import { deflateSync } from 'node:zlib';
import {
  createShareUrl, extractCode, decodeState, encodeState,
} from './dist/index.js';

const code = 'flowchart LR\r\n  A["开始 🚀"] --> B["Review & ship"]\r\n';
const mermaid = JSON.stringify({ theme: 'dark' });
const baseUrl = 'https://mermaid.live/edit';
const url = createShareUrl({ code, mermaid }, { baseUrl });

const recovered = extractCode(url);
assert.equal(recovered.ok, true);
assert.equal(recovered.value, code); // Includes CRLF and the trailing newline.

const state = decodeState(url);
assert.equal(state.ok, true);
assert.equal(state.value.mermaid, mermaid);
assert.equal(new URL(url).origin, new URL(baseUrl).origin);
assert.equal(new URL(url).pathname, '/edit');

// A second decoder path: use Node's compressor to produce an input token.
const independent = 'pako:' + deflateSync(
  Buffer.from(JSON.stringify({ code, mermaid }), 'utf8'),
).toString('base64url');
assert.equal(extractCode(independent).value, code);

const malformed = decodeState('pako:!!!!');
assert.equal(malformed.ok, false);
assert.equal(malformed.error.code, 'INVALID_BASE64');

// A small compressed input can expand beyond the application's limit.
const oversized = 'pako:' + deflateSync(Buffer.from(JSON.stringify({
  code: 'A'.repeat(20_000),
}))).toString('base64url');
const bounded = decodeState(oversized, { maxDecodedBytes: 1_024 });
assert.equal(bounded.ok, false);
assert.equal(bounded.error.code, 'OUTPUT_TOO_LARGE');

assert.throws(
  () => encodeState({ code, mermaid: { theme: 'dark' } }),
  error => error.code === 'INVALID_STATE',
);

console.log(JSON.stringify({
  roundTrip: recovered.value === code,
  configRoundTrip: state.value.mermaid === mermaid,
  independentlyCompressedInput: true,
  malformedError: malformed.error.code,
  boundedError: bounded.error.code,
  urlCharacters: url.length,
  sourceUtf8Bytes: Buffer.byteLength(code, 'utf8'),
}, null, 2));

The first assertions compare the recovered source string, including its CRLF line endings and final newline. A screenshot comparison would not catch those differences.

The configuration is checked separately. The URL's origin and path are also asserted, so the test verifies the selected destination as well as the payload.

The independently compressed token uses Node's zlib, rather than the codec's encoder. This checks one external input path instead of relying exclusively on an encoder and decoder agreeing with each other.

What actually passed

The example was executed on October 23, 2026. Its output was:

{
  "roundTrip": true,
  "configRoundTrip": true,
  "independentlyCompressedInput": true,
  "malformedError": "INVALID_BASE64",
  "boundedError": "OUTPUT_TOO_LARGE",
  "urlCharacters": 225,
  "sourceUtf8Bytes": 57
}

Those size values describe this particular source and encoded state. A tiny diagram can produce a URL longer than its source because JSON fields, compression headers, the prefix, and the destination add overhead. Compression is not a promise that every input becomes smaller.

Do not snapshot the entire compressed URL as the primary compatibility test. Two compressors can emit different streams that recover the same state. Compare the decoded fields, and keep a separately sourced editor fixture or serializer test as an interoperability check.

This experiment verifies source and configuration recovery. It does not test whether the Mermaid syntax renders, or whether every target editor accepts every configuration field.

These are the error outcomes from the runnable example, not estimated robustness scores.

Make decoder limits part of the feature

The malformed input returns INVALID_BASE64. The second failure is more interesting: the token represents 20,000 repeated characters, but decoding is restricted to 1,024 uncompressed bytes.

Checking only the pasted URL length would miss the expansion. The decoder returns OUTPUT_TOO_LARGE while enforcing its output bound.

A sensible boundary has several parts:

Boundary	What it controls
Encoded input length	How much data a caller can submit
Uncompressed byte limit	How much decoded JSON can be produced
JSON depth	How deeply the resulting data can nest
Application policy	Which fields the editor actually accepts

For this codec, callers can lower the built-in ceilings. They cannot raise them arbitrarily. The defaults and error codes are documented in the repository.

These limits reduce resource use. Synchronous decompression still consumes CPU; it is not a general-purpose isolation boundary. Keep that distinction when adapting the example to an application that handles untrusted links.

Recovering data does not authorize applying it

A decoded configuration can contain settings your application should not accept.

For a source-recovery feature, extracting only code is often enough. If the application also supports configuration import, define an allowlist of supported options rather than merging arbitrary decoded fields into the renderer.

Likewise, display recovered code with a textarea or textContent. A successful JSON decode says nothing about whether text is safe to insert as HTML.

In an interactive editor, source edits should also invalidate any previously generated link. Otherwise, a user can change a label and copy a link that still contains the old diagram.

A fragment keeps the payload out of one request, not out of reach

The browser does not include the fragment in the HTTP request for the document. It processes that part of the URL on the client. MDN's fragment reference describes this behavior.

The destination page's scripts can still read the fragment. So can anyone who receives the complete link. Compression does not encrypt the source, and a self-contained link has no central record to revoke.

For confidential diagrams, choose a sharing mechanism with the access and revocation behavior the project requires. Also test the real delivery path: a browser, chat application, or receiving editor can impose practical URL-length limits below the codec's own limit.

Actual browser editor capture. The visual example was edited in the source panel and rendered successfully. The independent share-codec playground linked below exposes recovered JSON; it does not render diagrams.

Try a changed input

The browser playground exposes the source, generated link, and recovered JSON without a local setup. It performs encoding and decoding in browser memory; it does not render the diagram.

A useful next experiment is to alter only the final newline, or replace an English label with Chinese and an emoji. Check source equality after decoding. Then lower the decoded-byte limit and check that failure remains an explicit error rather than an empty diagram.

For editors that already import shared state: which settings do you deliberately refuse to import, and how do you explain that choice in the UI?

Project context: this standalone codec is maintained alongside Mermaid Online. It is independent of the official Mermaid project, and the extracted package's production integration is pending.

AI disclosure: this article was drafted with AI. The included executable example was run against the recorded source commit; the measured output above is from that run.

I Edited Text in an AI Poster—Then Checked What Else Changed

river — Wed, 14 Oct 2026 09:32:00 +0000

The moon was right. The colors were right. Even the tiny event details were right. The headline was the one thing that needed to change: NIGHT BLOOM had to become AFTER DARK.

This is a controlled poster example from our EditableImage text-editing workflow, not a client campaign. Regenerating the entire frame would throw away the parts we wanted to keep. So the useful question wasn't “Can AI write the new words?” It was: Can we change those words without quietly changing everything around them?

Before: NIGHT BLOOM	After: AFTER DARK

Only the headline was meant to change. The moon, vines, gradient, and small event details were meant to stay put.

The test I care about is outside the edit

A side-by-side comparison can miss subtle drift. A model might make the moon slightly smaller, move a leaf, or rewrite the event time while fixing the headline. Those are failures when the surrounding design is the part you wanted to preserve.

For this test, we marked the headline, generated replacement lettering, and composited only the marked result onto the original image. We then compared the two versions pixel by pixel. The image below is an annotated change map, not the finished poster:

Orange marks the old “NIGHT BLOOM” lettering; blue marks the new “AFTER DARK” lettering. The two phrases overlap because they occupy the same part of the poster, so this map is not meant to be read as a headline. The dimmed background is shown only for reference.

On the web-compressed examples above, the meaningful differences occupy under 4% of the frame, all in the headline area. The comparison ignores faint compression noise (up to 22/255 here). The downloadable editor result is a lossless PNG; outside the selected lines, it retains the original pixels. The 4% figure describes this poster, not a promise for every image.

That distinction matters. “Looks similar” is subjective. “Nothing outside the marked area changed” is a property you can check.

A practical check for your own image

You don't need a special tool to apply the same reasoning:

Keep the original file. Compare against that file, not a screenshot of it.
Align dimensions. If the output was resized or cropped, a pixel diff will light up everywhere and tell you little.
Mark the allowed region. Decide before editing which pixels may change. For this poster, it's the headline; for a product screenshot, it might be one button label.
Look outside that region. Any substantial change there deserves an explanation. If you're comparing JPEG or WebP copies, first allow for compression noise; use lossless exports when you can.
Zoom in at 100%. The diff can tell you where pixels changed, but not whether the new lettering has a clean edge or a believable font.

The same test is especially useful for an approved UI screenshot with an outdated button label or a campaign image with last month's date. The design around the words is not disposable just because the words are wrong.

Where the result can still disappoint

Keeping the original outside the marked lines creates a trade-off at the boundary. On a smooth gradient like this poster, the seam is hard to notice. On a photograph, grain, or a busy pattern, the newly inferred background behind old letters may not join perfectly with the original. A full-image redraw can hide that seam, but it can also shift details elsewhere. Neither mode is universally better; compare both at full resolution.

This also doesn't recover an original font file. The new lettering is drawn to resemble the surrounding type; an exact font match isn't guaranteed. If the lettering is the artwork—a hand-painted logo, for example—I would rebuild it manually rather than expect a text edit to preserve its character.

My takeaway from this poster isn't that AI can “fix any image.” It's a narrower, more useful rule: when one part of an image is wrong, define the permitted change and inspect everything outside it. That turns a plausible-looking edit into one you can actually evaluate.

The full poster case and its limitations are on our site. If you want to try the same bounded edit on your own asset, here's the text-editing workflow.

The Mermaid Flowchart Rendered—but the Failure Path Was Missing

river — Wed, 14 Oct 2026 03:38:31 +0000

A deployment flowchart went from a red parser error to a clean, exportable diagram—but the most important fix was not syntax. Mermaid Online identified two concrete code errors; the preview then exposed a missing failure path. Below is the exact before-and-after, with screenshots and the code you can adapt.

This is a small, reproducible walkthrough, not a production incident. The point is to show where the tool saves time and where a human still has to decide what the arrows mean.

The starting draft

The intended flow was simple: push to main, build an image, run smoke tests, then deploy only if they pass. Here is the deliberately flawed first version:

flowchart LR
  A[Push to main] --> B[Build image (v2.4)]
  B --> C{Smoke tests pass?} C -->|yes| D[Deploy to prod (us-west)]

Pasting this into the Mermaid syntax checker produced a parse error on line 2. The opening parenthesis in “Build image (v2.4)” was being read as Mermaid syntax rather than label text. The smallest repair was to quote the label:

A["Push to main"] --> B["Build image (v2.4)"]

That did not finish the job. The next check reached line 3 and stopped at the second C: two statements had been squeezed onto one line. Its unexpected-token clue was NODE_STRING. Splitting the edge and the yes branch onto separate lines fixed that error.

Example of the checker's line-level feedback. The full code for this walkthrough is shown above and below.

The useful lesson is that the first parser error is not necessarily the only one. Fix the reported line, run the parser again, and keep the rest of the diagram intact. A wholesale rewrite can accidentally change the process you meant to document.

A green check was not the finish line

Once the code parsed, the live preview made the larger problem obvious. The decision diamond had a yes route to production and no route for a failed smoke test. That is not a Mermaid error. A parser cannot infer your release policy.

An earlier preview of the yes-only version: syntactically valid, but the failure path is absent.

For this example, a failed test should send the team to investigate and push a fix before the build runs again. The diagram also needs to show what happens after deployment. Here is the complete tested version:

flowchart LR
  A["Push to main"] --> B["Build image (v2.4)"]
  B --> C{"Smoke tests pass?"}
  C -->|yes| D["Deploy to prod (us-west)"]
  C -->|no| E["Investigate and push fix"]
  E --> A
  D --> F["Monitor"]

The final diagram exported from the exact code above. The no route returns through a fix and a new push; the yes route continues to deployment and monitoring.

It passes the checker and renders with both branches visible. The return arrow goes to Push to main, not straight back to Build image: this example assumes a new code change is needed before retrying. If your team reruns a flaky test without a new commit, that arrow should be different. The diagram is useful only if the arrows describe the real procedure.

Getting it into the document

A valid preview is still not the same thing as a deliverable. For this case, the Mermaid Online editor’s export panel produced a 2× PNG in the Clean Docs standard style. The page reported a 2452 × 672 px file with no watermark. The same panel offers SVG, PDF, and other image formats; the core checker and standard-style exports do not require an account.

The destination decides what to keep:

In a GitHub README that supports Mermaid, keep the source code. Reviewers can diff a changed edge and future editors can fix a label without recreating an image.
In a slide deck or document that will not render Mermaid, use SVG when it is supported or a high-resolution PNG when compatibility matters. Keep the source beside the exported asset so the image does not become the only copy of the diagram.

The layout choice matters too. A long pipeline can become an awkward vertical strip with top-down direction. Left-to-right worked better for this example, but it made the exported image wide. A slide may need fewer nodes or two smaller diagrams rather than a tiny unreadable one.

The same steps can read very differently depending on direction and where the diagram will live.

That is the workflow Mermaid Online makes less fiddly: paste code, get a concrete parser error, inspect the rendered flow, and export a clean asset. It shortened the mechanical part of this example. It did not decide that the no branch was missing, or whether a failed test should lead to a retry, rollback, or manual review. Those remain the author's decisions.

The next time a generated diagram gives you a red banner, fix the first reported token. When it turns green, ask the harder question: what would a teammate misunderstand if they used this diagram to do the job? For more on prompt constraints and other Mermaid failure modes, there is a longer guide here.

A Checkerboard Is Not Transparency: A Practical Alpha Test for Video

river — Fri, 09 Oct 2026 07:24:06 +0000

You export a “background-free” video, put it on a web page, and see a black rectangle. Is the file broken? Perhaps. But the player might be ignoring a real alpha channel.

Before running background removal again, separate three things: the preview background, the file's alpha channel, and the software playing the file. They can produce similar-looking screenshots for very different reasons.

Start with a no-code test

Place the exported file above a bright, solid-color layer in a video editor that supports transparency. Change that layer to a very different color. Watch the space around the subject, then pause on frames with hair, hands, or motion blur.

If both colors show through around the subject, the file is being composited with transparency in that editor.
If you see a fixed checkerboard, black, or white rectangle, either those pixels are baked into the file or the current playback path is not displaying alpha. Try a second known-compatible destination before blaming the removal step.
If the background changes but the edges look poor, alpha is present; your problem is cutout quality, not format support.

This visual test tells you what the destination can display. It does not prove every application will handle the same file in the same way.

What the checkerboard actually means

The grey-and-white checkerboard is a visual convention used by editors to represent empty space. It is not transparency itself. If those squares are written into the exported video, you have an opaque video of a checkerboard.

An alpha channel stores opacity alongside color. At one pixel, alpha 0 means the background can show through; alpha 1 means the foreground is fully opaque. Values in between let hair, glass, or motion-blurred edges blend with whatever is underneath. Apple’s ProRes white paper describes alpha as the data used to composite a foreground image over a background.

That is why the test uses two contrasting backgrounds and the actual exported file, rather than accepting one preview screenshot as proof.

A tiny browser test for VP9-alpha WebM

Save this as alpha-test.html next to your exported cutout.webm, then open it in a browser that supports VP9 alpha. Replace the filename if yours is different.

<div class="stage" id="stage">
  <video autoplay muted loop playsinline>
    <source src="cutout.webm" type="video/webm">
  </video>
</div>
<button id="switch-bg">Switch background</button>

<style>
  .stage { background: #14223b; width: min(100%, 720px); }
  .stage.light { background: #f2e8d5; }
  .stage video { display: block; width: 100%; }
</style>
<script>
  const stage = document.querySelector('#stage');
  document.querySelector('#switch-bg').addEventListener('click', () => {
    stage.classList.toggle('light');
  });
</script>

If the area around the subject switches from navy to cream, this browser is compositing the video over the page. Inspect the edges as well as the empty areas. If a solid rectangle remains, the file may be opaque—or the browser may not support this alpha path. Test in another alpha-aware destination before re-exporting. MDN's video codec guide notes that Safari does not support alpha transparency in VP9.

If the video does not play at all, check that the filename, path, and codec are correct before interpreting the result as an alpha failure.

Why a real transparent background matters

A cutout with a working alpha channel is reusable footage, not just a video that looks clean against one chosen color. You can place the same person or object over different website sections, slide backgrounds, or editing timelines without removing the background again for each design. That is especially useful when a campaign's colors change after the footage has already been prepared.

The practical advantage is flexibility: export once in a format your destination supports, then composite the subject over the background that fits the project. A baked-in checkerboard or solid-color rectangle takes that flexibility away.

A preview of the workflow—and what to verify

The BG Remover Online example shows a processed 3.75-second, 1920×1080 clip. The page identifies its 90-frame output as VP9-alpha WebM, and lets you switch the preview among checkerboard, blue, and dark backgrounds. You can try those controls without uploading anything. Seeing the same cutout on contrasting backgrounds helps you judge whether its edges will work in more than one design—not just whether it looks good on a checkerboard.

A separate outdoor result makes the comparison easier to see. This Product Hunt gallery image uses the same processed frame against three preview backgrounds:

Source footage: Pexels. These are preview composites, not three different exports or proof about the downloaded file.

Both demonstrations are still site previews. The cover image shows its original frame next to the cutout on a checkerboard; the cover alone cannot verify the alpha channel in a downloaded file. For your own project, export your clip and run the two-background test above in the destination that matters to you. The source footage is from Mixkit; the person shown is not affiliated with the product.

When a “transparent” file looks black

I diagnose the problem in this order:

Check the actual output format. An ordinary H.264 MP4 is not an alpha-delivery file for this workflow. Renaming .mp4 to .webm does not add opacity data.
Test a known alpha-aware editor or browser. If the background layer shows through there, your original player is the likely limitation.
Switch between light and dark backgrounds. One color may conceal halos, missing hair, or a leftover matte.
Inspect multiple frames. A clean still can shimmer when the subject moves.
Only then re-export. If the file fails in more than one compatible destination, choose an alpha-capable export and verify the new file before delivery.

Pick the format for the destination

There is no single transparent-video format that is ideal everywhere.

Destination	Practical choice	Caveat
Supported web playback and overlays	WebM with VP9 alpha	Test the target browser; Safari does not display VP9 alpha.
Editing and compositing	ProRes 4444	Large files; an alpha channel is supported but must actually be present in the export.
Compatible Apple playback	HEVC with alpha	A distinct alpha-capable HEVC workflow, not an ordinary MP4 export.

Apple documents ProRes 4444 alpha support and HEVC with alpha. Choose based on where the file will be used, then verify the actual output, not only the codec name.

If you use BG Remover Online for that test, its current limits are worth knowing first: video uploads are capped at 60 seconds; it exports VP9-alpha WebM, and offers ProRes 4444 for processed clips up to 15 seconds. It does not currently export HEVC alpha or retain the original audio. Google sign-in gives new accounts 5 free credits—enough for five images or up to five started seconds of video, with no card. Uploads are private: an upload you never process is deleted after 24 hours, and finished results are kept for 7 days and can be deleted sooner. Check the current terms before uploading sensitive footage.

If you need a subject you can reuse over different backgrounds, try BG Remover Online with a short, non-sensitive clip. Switch the preview background to inspect the edges, download the transparent video, then test that file in your actual editor or browser. The result is valuable when it saves a reshoot or a second cutout—not merely when the preview looks convincing.

The general rule is tool-independent: a checkerboard preview is a prompt to test, not evidence that the file will composite where you need it.

Disclosure: I built BG Remover Online. AI assistance was used to draft and edit this article; product-specific details were checked against its public pages. The public preview is described as a preview, not as an independent inspection of the downloaded file.

A PPTX Is Not Necessarily an Editable Slide: Five Tests That Matter

river — Fri, 09 Oct 2026 07:22:43 +0000

A screenshot pasted onto a PowerPoint slide is technically a .pptx. It is also still just a screenshot. You can resize it, but you cannot rewrite the title, move a KPI card, or correct a number without rebuilding part of the slide.

That distinction matters when the original deck has disappeared and the only surviving copy is a PNG in a wiki, a PDF export, or a screenshot in a chat thread. The useful question is not “Can I get a PPTX?” It is “Which edits will the downloaded PPTX actually let me make?”

Here is a five-part test you can run on any image-to-slide workflow. The point is to test the exported file, not just trust a polished preview.

1. Can you change the words as words?

Click the main title and replace one word. Then try a small label, such as a KPI value or footnote.

If the text is a native text box, you should be able to select characters and change the copy. If the output merely puts a new text box over old text baked into the background, the old letters may reappear when the replacement is shorter. Move the text box temporarily and inspect what is underneath.

Typography is a second test. A converter may recognize the correct words but substitute a font, weight, or line break. That is recoverable, but it is still review work.

2. Do the pieces move independently?

Try moving the title, one card, and the chart region. If the whole slide moves together, the file is mostly an image inside a PPTX wrapper.

There is an important distinction inside this test: a chart that moves as one graphic is not necessarily a native PowerPoint chart with an editable data table. Likewise, a recovered icon might be an independent image rather than a vector shape. Decide what level of editing you need before judging the export:

What you need to do	Minimum useful result
Rewrite a heading	Native text box
Reposition a visual	Separate slide object
Recolor individual parts	Editable shapes or layers
Change chart values	Native chart data or a deliberate redraw

“Editable” is a spectrum, not a single checkbox.

3. What appears when you move an object away?

This is the test that polished before/after pictures often skip.

Move the title to an empty corner. Is there a clean background underneath, or is the old title still visible? Move a card. Does it leave a rectangular hole or a blurry patch?

Reconstructing the background behind a foreground element requires an educated guess: the original pixels were covered. On a plain gradient that may be easy. On a photograph or intricate texture, expect to inspect and possibly repair the fill. Keep the original image beside the reconstructed slide so you can spot changes.

4. Did the small details keep their meaning?

A slide can look convincing at a glance while getting a tiny but important detail wrong: a percentage, axis label, date, unit, legend entry, or footnote. Compare each one against the source image. Pay extra attention to low-resolution text and labels placed over busy imagery.

For data-heavy slides, I treat the converted file as a draft until the numbers have been checked by a human. Visual similarity is not the same as factual accuracy.

5. Does it survive a round trip?

Download the PPTX, close the web editor, and open the file in the PowerPoint application your team actually uses. Make one text edit and one layout edit there. Check for substituted fonts, shifted objects, or a slide that became flat during export.

This matters because an interactive browser preview can demonstrate the intended structure without proving that the downloaded file preserves it.

Why convert an image to editable PowerPoint?

Imagine you inherit this “Genetic Discovery” slide as a single image and need to update its explanation for a new audience. Rebuilding the two-column layout, charts, and labels by hand would take time before you could even start editing the message. In the original image, none of those elements can be selected independently.

Before: a flattened slide image.

The next screenshot shows the slide in EditableImage’s Image to PPT editor. A text region in the right-hand panel is selected as a separate object. The visual layout is still recognizable, but there is now a starting point for changing copy and rearranging parts of the slide instead of recreating everything from a blank canvas.

After: a text object selected in the browser editor. This is not a screenshot of the exported PPTX opened in PowerPoint.

That is the practical value of an image-to-editable-PowerPoint workflow: it can turn a screenshot-only slide into a reconstruction draft you can work from. For an old presentation that needs a revised heading, a corrected paragraph, or a new arrangement, the time saved comes from not having to redraw the whole slide first. The original remains beside the result, making it easier to spot what needs fixing.

The trade-off is visible too: some dense text in this result is garbled or overlaps nearby content. Check every scientific label and number against the source before reuse. These screenshots show object separation in the browser editor; they do not prove that chart values are native PowerPoint data, that every background is clean, or that the exported PPTX passes the round-trip test.

If you have a slide you actually need to revise, try converting one image with EditableImage. Correct the obvious text errors, export the PPTX, and run the five tests above. Judge it by the manual work it saves on your slide—not by a perfect-looking preview.

A short test with your own slide

If you have a screenshot-only slide, use a full-resolution PNG, JPG, or WebP rather than a compressed chat thumbnail. Then:

Write down two edits you actually need to make—for example, change a KPI and move a card.
Convert that one slide and compare the result with the original. Fix obvious recognition errors before export.
Download the PPTX and run tests 1–5 in PowerPoint. Keep the source image next to it while you inspect small details.
Judge the result by manual work avoided, not by the number of objects reported. If your requirement is editable chart data or an exact licensed typeface, expect to rebuild or supply those parts yourself.

For context, the current EditableImage workflow requires sign-in, uses 4 credits per slide conversion, and gives new accounts 10 free credits without a card. The page estimates 45–90 seconds for processing. Images are sent to third-party AI services, are not published, and are deleted after 24 hours. Check the current terms before uploading anything confidential.

If all you need is a slide that looks right, simply placing the screenshot on a slide may be enough. If you need to reuse its words and layout, the exported file—not its extension or its preview—is the evidence.

Disclosure: I built EditableImage. AI assistance was used to draft and edit this article; the product details above were checked against its public pages. I have not presented the browser preview as an independent test of every exported PPTX.

I Recovered an Architecture Diagram from a PNG—Every Box Came Back, but the Labels Lied

river — Sun, 27 Sep 2026 15:15:52 +0000

When the only copy of an architecture diagram is an image, you can recover it as an
editable Draw.io file instead of redrawing it: the boxes and their labels come back as
real shapes you can move, and the arrows come back as connectors. On the real example
below, every box and every arrow came back — but the small words written along the arrows
did not, and a few of them came back wrong. It is a draft to check, and this post is about
what exactly to check.

How does a diagram end up as only a picture?

The usual ways. A design session ends and someone photographs the whiteboard. A system is
explained once in a slide deck, and the deck survives while the source file does not. A
PNG gets pasted into the wiki by the person who then leaves. Six months later the diagram
is needed for a review, it gets redrawn from memory, and the redraw gets a detail wrong
that nobody can check.

A picture cannot be searched, diffed against next quarter's design, or edited when the
system changes. A diagram file can.

What does "recovered" mean?

Not a trace. Image to Draw.io measures the boxes from the pixels, reads
the labels, follows the arrow strokes, and attaches each connector to the shapes it joins.
The result behaves like a diagram: drag a node and its edges go with it, retype a service
name in place, export Draw.io XML that opens anywhere
mxGraph files are read.

The diagram at the top of this post went in as a flat image. This is what came back:

The recovered diagram in the editor. The panel on the right counts what came back: 13 nodes, 12 connectors, 13 labels.

What did it get right, and what did it miss?

Most of it. Taken from the recovered file itself — which boxes each connector is actually
attached to, not how it happens to be drawn:

Every box came back, in its place, with its label and its fill colour: the eleven services and stores, plus the version tag and the sticky note. The three data stores came back as cylinders.
All twelve connectors are joined to the right two boxes. The nine arrows point the right way, and the three plain lines down to the data stores stayed plain lines.
The dashed "production vpc" boundary is gone, and its label with it. The boxes it grouped are all there, just no longer inside anything.
The words on the lines are the weak part. The original has six. One came back right (grpc), three came back missing (https, rest, sql), and two came back as words the original does not have: get / set became redis, and events became kafka.

Those last two are the ones worth dwelling on. They are plausible — a cache next to the
word redis, a message queue next to kafka — which is exactly why they are easy to miss. A
missing label is obvious; a wrong one that sounds right is not. The smaller slips are of
the same kind: the tag's "·" came back as ":", and some rounded corners came back square.

So the check that matters is not "does it look like the original", which it largely does.
It is: read every word on a line against the original, then drag each box and watch which
lines come with it. The original stays one click away in the editor for exactly this
comparison, and each fix is a retype or a drag rather than a redraw.

Is a whiteboard photo harder?

Yes. The example above is a clean export, which is the easy input — and it still needed its
line labels checked, which is worth saying plainly, because a clean export is the one every
tool in this category shows. A photographed board adds a
perspective the lens was not square to, a light reflection across some of the writing, and
hand-drawn boxes without the consistent borders box detection leans on.

Clear structure — boxes with borders, arrows with arrowheads, one label per edge — gives
the best start. Dense freehand sketching comes back as a rougher draft with more arrows to
fix. Either way the boxes and labels are the part you do not have to retype, and ten
minutes of dragging connectors beats redrawing the whole thing from memory.
Whiteboard photo to diagram covers how to photograph a
board so it can be read.

The steps

Open Image to Draw.io and upload the picture.
Read every label on a line against the original, then drag each box and watch which lines come with it: is every arrow there, joined to the right two boxes, pointing the right way?
Fix what is wrong by reconnecting, dragging and retyping.
Export the XML and put it where the next person will find it — versioned, searchable, and checkable against the next redesign.

Questions

What does it produce?

Standard Draw.io XML — nodes, connectors and labels that open in diagrams.net and any tool that reads mxGraph files.

Will the connectors follow the nodes?

They come back as edges attached to shapes, so dragging a node carries its arrows with it — which is also the quickest way to find an arrow attached to the wrong shape. Check every edge is there, joins the right two boxes, and points the right way.

Does it work on photographed whiteboards?

When boxes and arrows are clear, yes. A photo is a harder input than a clean export, so expect more to correct — the whiteboard page covers how to photograph a board so it can be read.

Archify Online: Interactive Diagrams in Your Browser, No Agent Needed

river — Mon, 21 Sep 2026 10:10:00 +0000

You see the screenshots everywhere: architecture maps that light up a request path on click, fade everything else back, and let you walk a system layer by layer. They come from Archify — the open-source diagram project on GitHub (tt-a1i/archify), MIT-licensed — which has collected more than 65,000 stars since April 2026 (as of September 2026). Then you open the repository and hit the catch: Archify is not a website. It is an agent skill and a CLI, meant to live inside Claude Code, Codex, or a similar tool.

Most people searching for "Archify online" want the maps, not the tooling around them. This post covers what Archify actually is, whether an official online version exists (short answer: no — by explicit design), and the browser port of the same engine that we run at mermaidonline.org — including what carries over, what had to change, and an honest comparison so you can pick the right form for your workflow.

TL;DR

Archify is a 65,000+-star open-source engine that turns a system description into a verifiable, interactive map — but it ships as an agent skill/CLI, not a website.

There is no official hosted version; the README names hosted sharing as intentionally out of scope.

We ported the same MIT-licensed rendering engine to the browser: paste a description, a Mermaid flowchart, docker-compose, Terraform, Kubernetes, or SQL, and explore the result at the interactive map generator.

Export is a self-contained HTML file — search, route tracing, and lenses keep working offline, in one file you can attach to a PR.

What Is Archify and Why Is It Everywhere?

Archify is best understood as a compile step for system diagrams. Instead of asking a model to "draw" boxes and hoping the output is legible, an agent produces a typed JSON intermediate representation of your system, and Archify deterministically compiles that specification into self-contained HTML/SVG. The project's own README puts it simply: agents produce the typed specification; Archify deterministically renders it (project README on GitHub, accessed September 2026). That split is why the output looks designed rather than generated — layout, routing, and label spacing are rules, not guesses.

It landed at the right moment. AI coding agents became the default place where engineers already describe systems, so "turn a codebase or system description into a polished, interactive system map — directly in chat" (project README) matched how people actually work. Growth has been steep: the repository was created in April 2026, crossed roughly 22,800 stars by late August, and sits above 65,000 as of September 2026 (GitHub repository and public star trackers).

Item	Details
Project	tt-a1i/archify on GitHub
License	MIT
Form	Agent skill + CLI (runs inside coding agents)
Diagram types	Architecture, workflow, sequence, data flow, lifecycle
Created	April 2026 — 65,000+ stars as of September 2026

The mental model to keep: Archify is a skill you install into your agent, not a site you visit. Which raises the obvious question.

Is There an Official Archify Online Version?

No — and this is a deliberate scope decision, not an oversight. The README states it verbatim:

"Automatic Mermaid parsing, general-purpose auto-layout, hosted sharing, and WYSIWYG editing are intentionally outside the current scope." (project README on GitHub, accessed September 2026)

The official site is a documentation landing page plus a gallery of pre-built example artifacts you can download and open locally. Nothing on it accepts your input and returns a map. So today there are exactly two ways to run this engine:

	How it works
Original (official)	Install the skill into an agent (Claude Code, Codex, Cursor, …), describe your system in chat, receive the rendered map locally
Browser port (ours)	Open a web page, paste code or describe the system, explore the map immediately

Everything below is about the second row — what a browser port of the engine gives you, and where it deliberately differs.

A Browser Port of the Same Engine: No Install, No Agent

We run the ported engine at the interactive map generator. One disclosure first: Mermaid Online is not affiliated with or endorsed by the Archify authors — we ported its MIT-licensed engine and credit it by name in the product.

What carries over from the original

The part of Archify that makes the output good is the deterministic layer, and that is exactly what the port preserves. Same typed JSON specification contract, same rule-driven layout and label-fitting, same interaction model: click a node to focus it, press R to trace an exact route between two nodes, L to compare semantic roles through lenses, P to play a guided story, search with /. Deep links carry state — a URL fragment like #route=a~b reopens the map with that path already traced. Because the compilation is deterministic, the same specification renders identically in the CLI and in the browser; route traces over the same nodes return the same hops. The exported artifact is the same self-contained HTML file: one file, no CDN, no server, and the interactions keep working offline.

What we rebuilt for the browser

The upstream flow assumes an agent sits in front of the engine: you describe the system in chat, the agent authors the JSON specification. In a browser there is no agent, so our service takes over that step — an AI layer converts your input into the typed specification, and the renderer takes it from there. That substitution drives most of the practical differences below, including the inputs we accept (the original explicitly excludes automatic Mermaid parsing, while accepting a pasted Mermaid diagram is one of our primary paths). It also changes the economics: running the conversion costs us model calls, so the port is free for your first 10 maps and uses credits after that, while the CLI remains fully free under its MIT license.

From Mermaid, docker-compose, Terraform, K8s, or SQL to an Interactive Map

The input story is where the port diverges most from upstream. The original expects your agent to read a repository or a chat description; Mermaid parsing is explicitly out of its scope. Our conversion layer was built for exactly the artifacts engineers already have lying around:

Input	Original Archify	Browser port
Plain-English description	✅ (in agent chat)	✅
Mermaid flowchart	❌ (out of scope by design)	✅ paste it
docker-compose / Terraform / K8s manifests	❌	✅ paste it
SQL schema	❌	✅ paste it

Paste a Mermaid flowchart

This is the path most mermaidonline readers will care about. Take a flowchart you already maintain:

flowchart TD
    A[Client] --> B[API Gateway]
    B --> C[Webhook Service]
    C --> D{Delivery ok?}
    D -- yes --> E[(Event Store)]
    D -- no --> F[Retry Queue]
    F --> C

Paste it into the interactive map generator, and the conversion layer maps nodes to typed components, classifies them (external, backend, message bus, data store), and hands the specification to the same deterministic renderer:

The static diagram did not change — the same six nodes and edges are all there. What changed is that every box became an addressable object you can search, trace, and filter. If your Mermaid does not render cleanly to begin with, fix that first with our guide to getting AI-generated Mermaid to render correctly, or generate fresh code with the AI Mermaid generator. Photos of whiteboards work too — turn a whiteboard photo into Mermaid first, then paste the result. And if a static Mermaid architecture diagram is all you need, the Mermaid architecture diagram guide covers that path.

Paste infrastructure as code

The same conversion layer reads infrastructure definitions. A docker-compose.yml becomes services and their dependencies; a Terraform file becomes managed resources and their references; Kubernetes manifests become workloads, config, and the clusters they expose. The value over reading the YAML is the same as with Mermaid: the map exposes structure — what calls what, what happens if this node dies — which is tedious to reconstruct by eye from a few hundred lines of manifests.

Point it at a SQL schema

Foreign keys are edges; tables are nodes. A schema paste produces a map where you can trace exactly which tables a given feature touches — useful during migrations and reviews, when the question "what reads this table?" needs a precise answer. As with every input mode, the result is an explorable map, not a picture.

What the Map Can Do: Node Search, Route Tracing, Lenses, Guided Stories

The interactions are the reason to bother with an engine like this at all. Four of them carry most of the value:

Node search (/) jumps the viewport to any named node — the fast path in a map with dozens of components.
Route tracing (R) asks the only question that matters in an incident review: how does a request actually get from A to B? The map highlights the exact directed hops and fades everything else.

Semantic lenses (L) re-color the map by component role — backends, data stores, external services — so you can read one layer at a time.

Guided stories (P) play an authored walkthrough of the system, one step at a time — the closest thing to a presenter mode a generated map has.

Two of these survive export in a shareable form. Deep links like #route= and #lens= reopen the exported HTML with the view already applied, which makes them surprisingly useful in PR descriptions and design docs — paste a link and reviewers see the path you are talking about, not a red rectangle drawn on a screenshot. For destinations that cannot run HTML at all, export a static PNG when the destination can't run HTML instead; and if you are weighing interactive HTML against plain Mermaid blocks, how Mermaid renders in GitHub README files covers the trade-offs.

60-Second Walkthrough: Mermaid Flowchart to Interactive Map

Open the interactive map generator — no install, no signup to try.
Paste a Mermaid flowchart, docker-compose, Terraform, Kubernetes, or SQL — or just describe the system in plain English. The input type is detected automatically.
Generate. The map renders in the page; search (/) for a node name to test that everything landed.
Press R and pick two nodes to trace a route; press L to view the map through a role lens.
Download the self-contained HTML — it opens offline with every interaction intact.

That is the whole loop. There is nothing to configure before step 2; the type chips (Architecture, Dataflow, Sequence) exist if you want to force a diagram style instead of relying on detection.

Honest Comparison: Browser Port vs the Original Archify CLI

If you are evaluating this family of tools, the comparison that matters is not "port versus original" as a quality ranking — the port uses the original's engine. It is which form fits your workflow:

	Original Archify (agent skill/CLI)	Browser port (mermaidonline.org)
Price	Free (MIT)	10 free maps, then paid credits
Install	Agent + skill/CLI	None — a browser tab
Diagram types	5 (incl. workflow, lifecycle)	3 (architecture, dataflow, sequence)
Inputs	Whatever your agent can read (repos, chats)	Description or pasted Mermaid / compose / Terraform / K8s / SQL
Output	Self-contained interactive HTML	Same engine, same self-contained HTML
Reproducibility	Spec + deterministic compile	Spec + deterministic compile

When the original CLI is the better choice

If you already live in Claude Code or Codex, the skill is the more natural home: it can read your repository directly, it is free without limits, and it tracks upstream immediately. You also get the two diagram types the port does not serve yet — workflow and lifecycle — plus whatever the fast-moving upstream adds next (the project has shipped continuously since April).

Limitations of our port

The port covers three of the five diagram types; upstream updates reach it only when we re-port them; the input conversion runs through our AI layer rather than your local agent; and after the first 10 free maps it is paid credits. None of that is hidden in the fine print — it is the trade you make for zero install. If those constraints bite, use the original; that is what it is for. And if the interactive layer is more than you need, a well-structured static diagram still goes a long way — keeping large diagrams readable applies regardless of the render.

Frequently Asked Questions

Is Archify free to use?

The upstream project is MIT-licensed open source, so the CLI and agent skill cost nothing. Our browser port is free to try with no account — you get 10 interactive renders, and paid credits cover heavier use.

Does Archify have an official online version?

No. As of September 2026, the project README states that hosted sharing is "intentionally outside the current scope", and the official site hosts documentation plus a gallery of prebuilt examples. The only way to run the engine in a browser today is a third-party port like ours.

Can I use Archify without an AI agent or CLI?

The original Archify is an agent skill and CLI designed to run inside tools like Claude Code. Our port moves the rendering engine into the browser, so you can paste Mermaid, docker-compose, Terraform, Kubernetes manifests, or a SQL schema and get an interactive map with nothing to install.

What export formats does Archify support?

The core output is a self-contained interactive HTML file that works offline — node search, route tracing, and lenses keep functioning in the exported file. If you need a static image for slides or docs, you can export one with our Mermaid-to-PNG tool instead.

Try It While You Are Here

Everything above runs at mermaidonline.org — the interactive map generator needs no account for your first 10 maps, and the same site covers the static side of the workflow: generating Mermaid from a description or an image, checking syntax, and exporting PNG/SVG. If you end up preferring the original CLI, the repository README has the install instructions — the engine is the same either way; pick the form that matches where you work.

“Looks done” is not the same as launch-ready

river — Wed, 17 Jun 2026 09:35:43 +0000

I used to check small sites in a pretty shallow way before launch.

Open the homepage.

Click the main CTA.

Resize the browser.

Make sure nothing looks obviously broken.

If the page looked fine, I shipped it.

But the issues I kept missing were rarely visual.

A staging noindex tag was still there.

The canonical URL pointed to a preview domain.

A privacy or contact link returned 404.

The sitemap included old test pages.

The shared link preview looked broken.

The homepage copy was clear to me, but not clear enough for someone seeing it cold.

None of these are dramatic bugs.

But they matter because launch traffic usually comes in a short window. You post once on Product Hunt, Reddit, HN, a newsletter, or send the link to users. That first impression is shaped by more than the hero section.

So my pre-launch check changed.

Now I try to answer a few boring but useful questions:

Can search engines index the right pages?
Are canonical, sitemap, and robots signals consistent?
Do trust links like privacy, terms, and contact actually work?
Does the page explain what the product is and who it’s for?
Does the link preview look reasonable when shared?
Are there any leftover staging or test signals?
For AI/devtool sites: is there enough public context for an assistant to summarize it correctly?

That last one is becoming more important for me.

I don’t think anyone can honestly promise “AI visibility.” But many sites accidentally make themselves harder to understand: thin copy, missing docs, blocked crawlers, placeholder llms.txt, unclear positioning.

Before sharing a site now, I try to ask:

If someone — or some crawler — sees this page without context, will they understand it correctly?

I turned this checklist into a small free tool here:

WebsiteReady launch checker

But the habit is the useful part:

Don’t only check whether the site looks finished.

Check whether it is ready to be discovered, shared, indexed, and trusted.

I wanted cleaner beautiful Mermaid diagrams for docs, so I made a small exporter

river — Thu, 04 Jun 2026 07:56:46 +0000

I use Mermaid diagrams a lot when I am trying to explain something that is easier to see than to read.

A release flow. A service talking to another service. A small state machine. The kind of diagram that belongs in a README, an architecture note, or a planning doc.

Mermaid itself is great for that. Plain text, versionable, reviewable. The part that kept annoying me was what happened after the diagram looked right.

I often wanted a clean image for a README, a slide, or a blog post. Not a rough screenshot. Not something with awkward padding. Not a diagram that looked fine in one place and slightly blurry everywhere else.

So I made a small tool for that:

Mermaid Online

It is a browser-based Mermaid editor and exporter. Paste Mermaid code, preview it, adjust the export style, then download PNG, SVG, JPG, WebP, or PDF.

No signup. No watermark. The core render/export workflow happens in the browser.

The problem I wanted to smooth out

Here is a tiny example:

flowchart LR
  A[Write the doc] --> B[Sketch the flow]
  B --> C[Preview the diagram]
  C --> D[Export for README]
  C --> E[Export for slides]

That is easy enough to write.

But when I need to put it somewhere, I usually start making small judgement calls:

Should this be SVG or PNG?
Does it need a transparent background?
Is 1x too soft for a slide?
How much padding should the diagram have?
Will it still be readable in a GitHub README?

None of these are hard problems. That is partly why they are annoying. They are small enough that I do not want to open a design tool, but visible enough that a sloppy export makes the whole doc feel less cared for.

What Mermaid Online does

The tool is intentionally simple.

You paste or edit Mermaid code on the left, check the live preview, then choose the export format and style.

The formats I cared about most:

PNG for README files, docs, and slides
SVG when I want a vector asset
PDF for handoff or document workflows
WebP for lightweight blog images
JPG when I need the boring compatible option

There are also presets for common destinations: clean docs, GitHub README, transparent backgrounds, dark docs, slides, and blog-style cards.

That last bit matters more than I expected. A diagram for a README and a diagram for a presentation usually should not have exactly the same padding, background, and scale.

A workflow that feels right to me

For documentation, I usually do this:

Write the Mermaid diagram directly while working on the doc.
Paste it into Mermaid Online.
Use a docs or README preset.
Export PNG at 2x, or SVG if the destination handles it well.
Put both the Mermaid source and exported asset near the doc.

For slides, I usually switch to a transparent preset and export at a larger scale. That keeps labels and arrows sharper on big screens, especially when the diagram gets resized by the slide tool.

For blog posts, WebP is nice when I want something lighter, and the editorial-style preset gives the diagram enough breathing room that it does not look like a raw screenshot dropped into the middle of the page.

Why local-first mattered

Some Mermaid diagrams are harmless. Others describe internal systems, database relationships, release flows, or security-review details.

I did not want the default workflow to require uploading diagram text just to turn it into an image.

The core editor and exporter run in the browser, so the diagram content stays local during the normal export path. That makes the tool feel more appropriate for architecture notes and internal docs.

It is still a small project, so I am being careful with the wording here: this is an independent tool, not affiliated with Mermaid.js, Mermaid Chart, or their maintainers.

What I would like to improve next

The current version is mostly about single-diagram export quality.

The things I keep thinking about next are:

Batch export from Markdown files
ZIP downloads for multiple diagrams
Saved custom themes
Better workflows for docs teams
More examples for common architecture and product diagrams

I am deliberately not rushing all of that in at once. The first version should do one job well: turn Mermaid code into a clean asset you can actually use.

Try it

If you use Mermaid in README files, technical docs, slides, or blog posts, you can try it here:

https://mermaidonline.org/

I would especially like feedback from people who write docs often:

Which export format do you use most?
Do you prefer keeping Mermaid source in the doc, or committing generated images?
What diagram style actually looks good inside your documentation system?

Small tools get better when they are shaped by real workflows, so practical feedback is more useful to me than general praise.