jsmdcui 0.11.2 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 All notable user-visible changes to jsmdcui are documented here.
 
+## [0.12.0] - 2026-07-27
+
+This release makes Markdown images embedded by Bun's HTML bundler available to
+the compiled terminal UI, adds environment-controlled Kitty rendering, and
+consolidates the reusable single-executable asset helpers.
+
+### Added
+
+- Add `JSMDCUI_KITTY_MODE=off|compat|extended` as an environment-controlled
+  alternative to the Kitty command-line flags. Explicit `--kitty` and
+  `--kitty-compat` arguments continue to take precedence.
+- Preserve each generated WUI image source in `data-mdcui-src`. Bun can rewrite
+  the normal `src` to its content-hashed public asset path while the original
+  Markdown reference remains available for TUI lookup.
+- Add reusable HTML bundle helpers to `single-exe/assetsHelper.js`. They match
+  compiled public image paths to `homepage.files`, canonicalize HTML entities
+  and percent-encoded image references, and build a Markdown-reference-to-bunfs
+  image map from `homepage.index`.
+- Export the bundled `homepage` from generated Markdown server modules so a
+  compiled TUI can inspect the same HTML asset manifest without starting the
+  WUI server.
+
+### Changed
+
+- Reuse images already embedded by Bun's HTML bundler instead of copying a
+  second image archive into the executable. The compiled TUI builds the image
+  path map once on first Kitty use, caches it, and reads image bytes lazily from
+  Bun's compiled virtual filesystem (`/$bunfs/root/...` on POSIX systems or
+  `B:/~BUN/...` on Windows).
+- Load the bundled homepage only when running a compiled executable with
+  `global.MDCUI_MAIN` configured. Source-tree launches retain the existing
+  filesystem and authorized HTTP image fallbacks without importing a generated
+  server module.
+- Consolidate runtime asset access on `single-exe/assetsHelper.js` and remove
+  the duplicate `src/runtime/assets.js` implementation.
+
+### Fixed
+
+- Match compiled Markdown images independently of Bun's build-entry-relative
+  `homepage.files[].input` paths. This fixes images whose Markdown-relative
+  path and bundle-entry-relative path have different spellings.
+- Normalize bare `process.env.JSMDCUI_KITTY_MODE=compat` build definitions into
+  JavaScript string literals before forwarding them to `bun build`.
+- Use the global `process` binding for Kitty-mode build constants, allowing Bun
+  to replace `process.env.JSMDCUI_KITTY_MODE` at build time instead of missing
+  an imported and renamed `node:process` binding.
+
 ## [0.11.2] - 2026-07-26
 
 ### Added

package/README.md

@@ -153,6 +153,7 @@ bun src/index.js --wui testapp.md
 | `bun src/index.js app.md` | Render `app.md` as a read-only terminal UI and write five generated files beside it. |
 | `bun src/index.js --kitty app.md` | Display Markdown images with Kitty graphics and the jsgotty MIME extension. |
 | `bun src/index.js --kitty-compat app.md` | Convert Markdown images to PNG with `Bun.Image` and display them using the standard Kitty graphics protocol without the non-standard MIME `U` field. |
+| `JSMDCUI_KITTY_MODE=compat bun src/index.js app.md` | Enable `compat` or `extended` Kitty mode without passing a Kitty command-line flag; the default and invalid values are `off`. |
 | `bun src/index.js --kitty --allow-url URL.md` | Download trusted HTTP(S) Markdown and its HTTP(S) images, then display supported images with Kitty graphics. |
 | `JSMDCUI_KITTY_DEBUG=1 bun src/index.js --kitty app.md` | Enable Kitty image placement logging to `kitty-placement.log`. |
 | `bun src/index.js --check app.md` | Check heading and fenced-block IDs for collisions, print line-by-line details, and exit. |
@@ -576,6 +577,36 @@ supported HTTP(S) images with Kitty graphics, combine the options:
 bun src/index.js --kitty --allow-url https://example.com/app.md
 ```
 
+Images referenced by an app built with `--build-md-exe` are also available to
+the compiled TUI. Bun embeds them through the generated WUI HTML bundle;
+jsmdcui preserves the original Markdown reference, maps it to Bun's
+content-hashed compiled asset (`/$bunfs/root/...` on POSIX systems or
+`B:/~BUN/...` on Windows), and reads the image lazily when Kitty rendering
+needs it. The executable does not need a second copy in the tar asset archive;
+the runtime uses the path reported by Bun rather than assuming either platform
+prefix.
+
+To make a no-argument compiled app enable standard Kitty-compatible rendering
+immediately, inline the environment-mode value at build time:
+
+```sh
+npx jsmdcui --build-md-exe myapp.md \
+  --define process.env.JSMDCUI_KITTY_MODE=compat
+```
+
+For the jsgotty MIME extension, use `extended` instead:
+
+```sh
+npx jsmdcui --build-md-exe myapp.md \
+  --define process.env.JSMDCUI_KITTY_MODE=extended
+```
+
+The jsmdcui build wrapper quotes these bare string values before forwarding
+them to Bun. At the call site, `process` must be the Node/Bun global. Do not
+write `import process from "node:process"`: Bun renames that imported binding
+during bundling, so a define targeting `process.env.JSMDCUI_KITTY_MODE` cannot
+match and inline it.
+
 ### CDP control for TUI automation
 
 The terminal UI can expose a Chrome DevTools Protocol (CDP) server, so another
@@ -783,6 +814,10 @@ npx jsmdcui --build-md-exe myapp.md
 
 This is a convenience alias for
 `--build-exe --define global.MDCUI_MAIN=myapp.md`.
+The generated HTML images are embedded by Bun and can be displayed by the
+compiled TUI. Add
+`--define process.env.JSMDCUI_KITTY_MODE=compat` after the Markdown path when
+the executable should enable Kitty-compatible images on a no-argument launch.
 
 For cross-compilation, specify the Bun target before the Markdown file:
 
@@ -791,7 +826,7 @@ npx jsmdcui --build-md-for bun-linux-x64-v1.3.14 myapp.md
 ```
 
 This similarly expands to
-`--build-for bun-linux-x64 --define global.MDCUI_MAIN=myapp.md`. Both aliases
+`--build-for bun-linux-x64-v1.3.14 --define global.MDCUI_MAIN=myapp.md`. Both aliases
 are expanded before any generated application files are written.
 
 Place every build define after `--build-exe`, or after the target argument of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jsmdcui",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Markdown as a Common UI for Terminals and Web Browsers",
   "type": "module",
   "main": "./src/index.js",

package/runmd.mjs

@@ -2,7 +2,7 @@
 
 import path from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { readInternalAssetText } from './src/runtime/assets.js'
+import { readInternalAssetText } from './single-exe/assetsHelper.js'
 import { fenceEventMap } from './src/cui/fence-events.mjs'
 import { REPO_ROOT } from './single-exe/compiled.js'
 
@@ -470,7 +470,8 @@ ${moduleScript}
       md += `\n${moduleScript}\n`;
     }
   }
-  
+
+  md = annotateWuiImageSources(md)
   
   await Bun.write(mdpath+".html",md)
   logWroteFile("html", mdpath+".html")
@@ -478,6 +479,17 @@ ${moduleScript}
   return md;
 }
 
+function annotateWuiImageSources(html)
+{
+  return String(html).replace(/<img\b[^>]*>/gi, tag => {
+    if (/\bdata-mdcui-src\s*=/i.test(tag)) return tag
+    const src = tag.match(/\bsrc\s*=\s*(["'])(.*?)\1/i)
+    if (!src) return tag
+    const attribute = ` data-mdcui-src=${src[1]}${src[2]}${src[1]}`
+    return tag.replace(/\s*\/?>$/, ending => `${attribute}${ending}`)
+  })
+}
+
 export function charFromPoint(tui,row,col)
 {
   tui = tui.split('\n')[row-1] || ""

package/runtime/help/help.md

@@ -153,6 +153,7 @@ bun src/index.js --wui testapp.md
 | `bun src/index.js app.md` | Render `app.md` as a read-only terminal UI and write five generated files beside it. |
 | `bun src/index.js --kitty app.md` | Display Markdown images with Kitty graphics and the jsgotty MIME extension. |
 | `bun src/index.js --kitty-compat app.md` | Convert Markdown images to PNG with `Bun.Image` and display them using the standard Kitty graphics protocol without the non-standard MIME `U` field. |
+| `JSMDCUI_KITTY_MODE=compat bun src/index.js app.md` | Enable `compat` or `extended` Kitty mode without passing a Kitty command-line flag; the default and invalid values are `off`. |
 | `bun src/index.js --kitty --allow-url URL.md` | Download trusted HTTP(S) Markdown and its HTTP(S) images, then display supported images with Kitty graphics. |
 | `JSMDCUI_KITTY_DEBUG=1 bun src/index.js --kitty app.md` | Enable Kitty image placement logging to `kitty-placement.log`. |
 | `bun src/index.js --check app.md` | Check heading and fenced-block IDs for collisions, print line-by-line details, and exit. |
@@ -791,7 +792,7 @@ npx jsmdcui --build-md-for bun-linux-x64-v1.3.14 myapp.md
 ```
 
 This similarly expands to
-`--build-for bun-linux-x64 --define global.MDCUI_MAIN=myapp.md`. Both aliases
+`--build-for bun-linux-x64-v1.3.14 --define global.MDCUI_MAIN=myapp.md`. Both aliases
 are expanded before any generated application files are written.
 
 Place every build define after `--build-exe`, or after the target argument of

package/single-exe/README.md

@@ -44,8 +44,15 @@ need quotes. `stringifyNonPrimitiveDefineValues()` converts a bare value with
 `JSON.stringify()` before it reaches Bun. jsmdcui uses it for
 `global.MDCUI_MAIN`.
 
-The switch defines below are presence-based: `=0` and `=false` still enable
-them. Omit a switch define to disable it; examples consistently use `=1`.
+`global.MDCUI_MAIN` is a jsmdcui application convention, not a name reserved by
+the single-executable helpers. An adopting project can use
+`global.MY_EMBEDDED_APP`, or any other build expression, as long as it updates
+its own call sites and passes the same name to
+`stringifyNonPrimitiveDefineValues()`.
+
+The jsmdcui switch defines below are presence-based: `=0` and `=false` still
+enable them. Omit a switch define to disable it; examples consistently use
+`=1`.
 
 - `MDCUI_DEFAULT_EDIT=1`: editable-text default.
 - `MDCUI_DEFAULT_DEMO=1`: no-argument `testapp.md` TUI.
@@ -209,6 +216,111 @@ a resource should be returned as bytes instead of decoded text.
 Use `listInternalAssetPaths()` to list embedded asset paths and
 `listInternalAssetDirs()` to list embedded directories.
 
+#### Reuse images from a compiled HTML bundle
+
+Bun exposes an imported HTML entry as a `homepage` object in a compiled
+executable. Its `index` points to the compiled HTML and its `files` array lists
+the content-hashed assets under Bun's compiled virtual filesystem: paths
+normally begin with `/$bunfs/root/` on POSIX systems and `B:/~BUN/` on
+Windows. The helpers can turn image references preserved in that HTML into a
+lazy path map without copying the image bytes into `internalAssets`. Always use
+the path returned by `homepage.files`; do not hard-code either platform prefix.
+
+Before compiling, preserve each original image reference in a custom
+attribute. Its name belongs to the adopting project; it is not fixed by the
+helper. This example chooses `data-original-image`. Bun rewrites `src` but
+leaves the custom attribute intact:
+
+```html
+<!-- Input -->
+<img src="./images/photo.jpg" data-original-image="./images/photo.jpg">
+
+<!-- Compiled HTML -->
+<img src="/photo-abcd1234.jpg" data-original-image="./images/photo.jpg">
+```
+
+Export the imported HTML bundle from a module that both the web server and
+terminal runtime can load:
+
+```js
+import homepage from "./index.html";
+
+export { homepage };
+```
+
+Build and cache the map only in a compiled executable. Guard the import first:
+a source-tree launch does not necessarily have the generated server or HTML
+module.
+
+```js
+import {
+  buildHtmlBundleImageMap,
+  canonicalHtmlBundleImageHref,
+} from "../single-exe/assetsHelper.js";
+import { IS_COMPILED } from "../single-exe/compiled.js";
+
+let imageMapPromise = null;
+const imageSourceAttribute = "data-original-image";
+
+function getBundledImageMap() {
+  if (!IS_COMPILED || !global.MY_EMBEDDED_APP) return null;
+
+  imageMapPromise ??= import(global.MY_EMBEDDED_APP + "-server.js")
+    .then(module => buildHtmlBundleImageMap(
+      module.homepage,
+      imageSourceAttribute,
+    ));
+
+  return imageMapPromise;
+}
+
+const images = await getBundledImageMap();
+const key = canonicalHtmlBundleImageHref(originalImageHref);
+const bundledPath = images?.get(key);
+const bytes = bundledPath ? await Bun.file(bundledPath).bytes() : null;
+```
+
+`global.MY_EMBEDDED_APP` is only an example build-time module selector. Name it
+to match the adopting application, replace it with a direct static import, or
+use another compiled-only condition. The helper does not inspect or require
+`global.MDCUI_MAIN`; that is jsmdcui's own convention. When using a Bun
+`--define`, use the same expression at the call site, for example
+`--define global.MY_EMBEDDED_APP=...`.
+
+`buildHtmlBundleImageMap(homepage, sourceAttribute)` reads the compiled HTML
+once and returns a `Map<string, string>` from canonical original image
+references to Bun compiled virtual paths on either platform. The second
+argument is the custom attribute name. It defaults to `"data-mdcui-src"` only
+for jsmdcui's convenience:
+
+```js
+const images = await buildHtmlBundleImageMap(homepage);
+```
+
+Adopting projects can choose any valid HTML attribute name and pass it
+explicitly:
+
+```html
+<img src="./photo.jpg" data-original-image="./photo.jpg">
+```
+
+```js
+const images = await buildHtmlBundleImageMap(
+  homepage,
+  "data-original-image",
+);
+```
+
+The helper decodes HTML attribute entities and percent encoding so the HTML
+reference can match the equivalent original caller reference. Image bytes
+remain lazy and are read only when the caller uses the returned path.
+
+For lower-level lookup, `findHtmlBundleAsset(homepage, publicPath, options)`
+matches a rewritten public path such as `/photo-abcd1234.jpg` to its
+`homepage.files` entry. `findHtmlBundleImageAsset()` restricts the lookup to
+`image/*`, and `htmlBundleImageAssetPath()` returns only the corresponding
+Bun compiled virtual path.
+
 ### 5. Add the optional build commands to the regular CLI
 
 Before normal argument parsing, call `buildEarlyExit` from the regular main

package/single-exe/assetsHelper.js

@@ -1,3 +1,5 @@
+import { posix } from "node:path";
+
 const textDecoder = new TextDecoder();
 const textEncoder = new TextEncoder();
 
@@ -12,6 +14,87 @@ export function assetPath(...parts) {
     .join("/");
 }
 
+export function decodeHtmlAttribute(value) {
+  return String(value ?? "").replace(
+    /&(?:amp|quot|apos|lt|gt|#39|#x27|#\d+|#x[\da-f]+);/gi,
+    (entity) => {
+      const named = {
+        "&": "&",
+        """: "\"",
+        "'": "'",
+        "&lt;": "<",
+        "&gt;": ">",
+        "&#39;": "'",
+        "&#x27;": "'",
+      }[entity.toLowerCase()];
+      if (named != null) return named;
+      const hex = /^&#x([\da-f]+);$/i.exec(entity);
+      const decimal = /^&#(\d+);$/.exec(entity);
+      const codePoint = Number.parseInt(hex?.[1] ?? decimal?.[1] ?? "", hex ? 16 : 10);
+      try {
+        return Number.isInteger(codePoint) ? String.fromCodePoint(codePoint) : entity;
+      } catch {
+        return entity;
+      }
+    },
+  );
+}
+
+export function canonicalHtmlBundleImageHref(input, { htmlAttribute = false } = {}) {
+  let value = String(input ?? "");
+  if (htmlAttribute) value = decodeHtmlAttribute(value);
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+export function findHtmlBundleAsset(homepage, publicPath, {
+  contentTypePrefix = "",
+} = {}) {
+  if (!Array.isArray(homepage?.files)) return null;
+  const name = posix.basename(String(publicPath ?? "").replace(/[?#].*$/, ""));
+  for (const file of homepage.files) {
+    if (file?.loader !== "file") continue;
+    const contentType = String(file.headers?.["content-type"] ?? "");
+    if (contentTypePrefix && !contentType.startsWith(contentTypePrefix)) continue;
+    if (posix.basename(String(file.path ?? "")) === name) return file;
+  }
+  return null;
+}
+
+export function findHtmlBundleImageAsset(homepage, publicPath) {
+  return findHtmlBundleAsset(homepage, publicPath, {
+    contentTypePrefix: "image/",
+  });
+}
+
+export function htmlBundleImageAssetPath(homepage, publicPath) {
+  return findHtmlBundleImageAsset(homepage, publicPath)?.path ?? null;
+}
+
+export async function buildHtmlBundleImageMap(
+  homepage,
+  sourceAttribute = "data-mdcui-src",
+) {
+  const images = new Map();
+  if (!homepage?.index || !Array.isArray(homepage.files)) return images;
+  const html = await Bun.file(homepage.index).text();
+  for (const tag of html.match(/<img\b[^>]*>/gi) ?? []) {
+    const rawHref = htmlTagAttribute(tag, sourceAttribute);
+    const publicPath = htmlTagAttribute(tag, "src");
+    if (rawHref == null || publicPath == null) continue;
+    const bundledPath = htmlBundleImageAssetPath(homepage, decodeHtmlAttribute(publicPath));
+    if (!bundledPath) continue;
+    images.set(
+      canonicalHtmlBundleImageHref(rawHref, { htmlAttribute: true }),
+      bundledPath,
+    );
+  }
+  return images;
+}
+
 export function listInternalAssetPaths(prefix = "") {
   const store = getAssetStore();
   if (!store) return [];
@@ -88,3 +171,9 @@ function iterateAssetKeys(store) {
   if (store instanceof Map) return [...store.keys()].map(String);
   return Object.keys(store);
 }
+
+function htmlTagAttribute(tag, name) {
+  const escapedName = String(name).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = String(tag).match(new RegExp(`\\b${escapedName}\\s*=\\s*([\"'])(.*?)\\1`, "i"));
+  return match?.[2] ?? null;
+}

package/src/cui/kitty-images.mjs

@@ -2,6 +2,7 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { logKittyPlacement } from "./kitty-debug.mjs";
 import { fetchHttpBytes as defaultFetchHttpBytes } from "../platform/commands.js";
+import { canonicalHtmlBundleImageHref } from "../../single-exe/assetsHelper.js";
 
 const PNG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 
@@ -63,8 +64,8 @@ function imageSize(buffer) {
   }
   const svg = buffer.subarray(0, Math.min(buffer.length, 8192)).toString("utf8");
   if (svg.includes("<svg")) {
-    const width = svg.match(/\bwidth=["']([0-9.]+)(?:px)?["']/i);
-    const height = svg.match(/\bheight=["']([0-9.]+)(?:px)?["']/i);
+    const width = svg.match(/\bwidth=["']([0-9.]+)(?:px)?["']/i); //'
+    const height = svg.match(/\bheight=["']([0-9.]+)(?:px)?["']/i); //'
     if (width && height) {
       return { mime: "image/svg+xml", width: Math.round(Number(width[1])), height: Math.round(Number(height[1])) };
     }
@@ -136,11 +137,17 @@ export async function prepareKittyImages(ansiText, markdownPath, terminalCols =
   const images = [];
   const maxCols = Math.max(1, Math.trunc(Number(terminalCols) || 80));
   const oscImage = /\x1b\]8;;([^\x1b]*)\x1b\\(?=[^\n]*📷)/;
+  const bundledImages = await options.getBundledImageMap?.() ?? null;
 
   for (let sourceLine = 0; sourceLine < inputLines.length; sourceLine++) {
     const line = inputLines[sourceLine];
     const match = line.match(oscImage);
-    const source = match ? imageSource(match[1], markdownPath, options.allowUrl === true) : null;
+    const bundledPath = match
+      ? bundledImages?.get(canonicalHtmlBundleImageHref(match[1]))
+      : null;
+    const source = bundledPath
+      ? { kind: "bundled", value: bundledPath }
+      : match ? imageSource(match[1], markdownPath, options.allowUrl === true) : null;
     if (!source) {
       outputLines.push(line);
       continue;

package/src/cui/kitty-mode.mjs

@@ -0,0 +1,6 @@
+const KITTY_MODES = new Set(["off", "compat", "extended"]);
+
+export function kittyModeFromEnvironment(input) {
+  const value = String(input ?? "").trim().toLowerCase();
+  return KITTY_MODES.has(value) ? value : "off";
+}

package/src/cui/server.mjs

@@ -9,6 +9,7 @@ const mda = Bun.markdown.ansi
 import homepage from "./testapp.md.html"
 import * as backmod from "./testapp.md.back.js";
 
+export { homepage };
 
 /*
 // Wait until Bun fixes dynamic html import bundle

package/src/index.js

@@ -94,17 +94,17 @@ import { accessSync, closeSync, constants, existsSync, openSync, readSync, readd
 import { mkdir } from "node:fs/promises";
 import { dirname, basename, join, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import process from "node:process";
 import { toggleTaskCheckboxBeforeColumn, updateAnsiTaskCheckbox } from "./cui/task-checkbox.mjs";
 import { fenceEventMap, inlineFenceEventCode } from "./cui/fence-events.mjs";
 import { checkMarkdownIdCollisions, formatMarkdownIdCheckAnsi } from "./cui/id-collision.mjs";
 import { fitKittyImageToWidth, prepareKittyImages } from "./cui/kitty-images.mjs";
+import { kittyModeFromEnvironment } from "./cui/kitty-mode.mjs";
 import { logKittyPlacement } from "./cui/kitty-debug.mjs";
 import { Config } from "./config/config.js";
 import { defaultAllSettings, OPTION_CHOICES, LOCAL_SETTINGS } from "./config/defaults.js";
 import { cleanConfig } from "./config/clean.js";
 import { RuntimeRegistry, RTColorscheme, RTHelp } from "./runtime/registry.js";
-import { assetPath, hasInternalAssets, listInternalAssetDirs, listInternalAssetPaths, readInternalAssetText } from "./runtime/assets.js";
+import { assetPath, buildHtmlBundleImageMap, hasInternalAssets, listInternalAssetDirs, listInternalAssetPaths, readInternalAssetText } from "../single-exe/assetsHelper.js";
 //import { PluginManager } from "./plugins/manager.js";
 import { JsPluginManager, buildMicroGlobal, buildTuiBlockIndex, findTuiBlockInIndex, insertTuiTextareaNewline, mergeTuiTextareaBackward, mergeTuiTextareaForward, runAction, listActions } from "./plugins/js-bridge.js";
 import { Colorscheme } from "./config/colorscheme.js";
@@ -124,6 +124,7 @@ import { writeBackup, removeBackup, applyBackup } from "./buffer/backup.js";
 let kittyImageMode = "off";
 let allowRemoteKittyImages = false;
 const remoteMarkdownSources = new Map();
+let bundledImageMapPromise = null;
 import { isHex3Encoding, isMdcuiEncoding } from "./runtime/encodings.js";
 import { createInterface } from "node:readline/promises";
 
@@ -135,6 +136,13 @@ import { expandBuildMdAliases } from "./build-args.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+function getBundledImageMap() {
+  if (!IS_COMPILED || !global.MDCUI_MAIN) return null;
+  bundledImageMapPromise ??= import(global.MDCUI_MAIN + "-server.js")
+    .then((module) => buildHtmlBundleImageMap(module.homepage));
+  return bundledImageMapPromise;
+}
+
 
 if(!globalThis.Bun)
 {
@@ -380,6 +388,7 @@ async function renderMdcui(markdown, width = process.stdout.columns || 80, mdpat
     : await prepareKittyImages(tui, resolvedImageBasePath, width, {
       allowUrl: allowRemoteKittyImages,
       kittyMode: kittyImageMode,
+      getBundledImageMap,
     });
   return {
     rendered: prepared.rendered,
@@ -1119,7 +1128,7 @@ function parseArgs(argv) {
     cdpMaze: false,
     cdpPort: 0,
     cdpAddress: "",
-    kittyMode: "off",
+    kittyMode: kittyModeFromEnvironment(process.env.JSMDCUI_KITTY_MODE),
     settings: new Map(),
   };
   const files = [];
@@ -1269,6 +1278,9 @@ Modes:
     Display Markdown images with Kitty graphics and the jsgotty MIME extension
   --kitty-compat
     Display Markdown images with Kitty graphics without the non-standard MIME U field
+
+  JSMDCUI_KITTY_MODE=off|compat|extended
+    Set the Kitty image mode without command-line flags; explicit Kitty flags override it
       
   --edit
     Open files as editable UTF-8 text
@@ -8265,6 +8277,7 @@ async function main() {
   addCheckpoint("Argument Parsing");
 
   expandBuildMdAliases(process.argv);
+  stringifyNonPrimitiveDefineValues(process.argv, "process.env.JSMDCUI_KITTY_MODE");
   stringifyNonPrimitiveDefineValues(process.argv, "global.MDCUI_MAIN");
   const argvMdcuiMain = stringDefineFromArgv(
     process.argv,

package/src/lua/engine.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { readInternalAssetBytes } from "../runtime/assets.js";
+import { readInternalAssetBytes } from "../../single-exe/assetsHelper.js";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { REPO_ROOT } from "../../single-exe/compiled.js";

package/src/plugins/js-bridge.js

@@ -3,7 +3,7 @@ import { readdir } from "node:fs/promises";
 import { dirname, join, basename, extname } from "node:path";
 import { pathToFileURL } from "node:url";
 import { tmpdir } from "node:os";
-import { assetPath, hasInternalAssets, listInternalAssetDirs, listInternalAssetPaths, readInternalAssetBytes } from "../runtime/assets.js";
+import { assetPath, hasInternalAssets, listInternalAssetDirs, listInternalAssetPaths, readInternalAssetBytes } from "../../single-exe/assetsHelper.js";
 import { isMdcuiEncoding } from "../runtime/encodings.js";
 import { newMessage, newMessageAtLine, MTError, MTWarning, MTInfo } from "../buffer/message.js";
 import { Loc } from "../buffer/loc.js";

package/src/plugins/manager.js

@@ -4,7 +4,7 @@ import { basename, dirname, extname, join, sep } from "node:path";
 import { fetchHttp, downloadFile } from "../platform/commands.js";
 import { extractAndStrip } from "../platform/archive.js";
 import { createLuaEngine } from "../lua/engine.js";
-import { assetPath, hasInternalAssets, internalAssetSource, listInternalAssetDirs, listInternalAssetPaths, readInternalAssetText } from "../runtime/assets.js";
+import { assetPath, hasInternalAssets, internalAssetSource, listInternalAssetDirs, listInternalAssetPaths, readInternalAssetText } from "../../single-exe/assetsHelper.js";
 import { execCommand, runBackgroundShell, runCommand } from "../shell/shell.js";
 import { Loc } from "../buffer/loc.js";
 import { BTDefault, BTHelp, BTInfo, BTLog, BTRaw, BTScratch, byteOffset, BufferCore } from "../buffer/buffer.js";

package/src/runtime/registry.js

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
-import { assetPath, hasInternalAssets, listInternalAssetPaths, readInternalAssetBytes } from "./assets.js";
+import { assetPath, hasInternalAssets, listInternalAssetPaths, readInternalAssetBytes } from "../../single-exe/assetsHelper.js";
 
 export const RTColorscheme = 0;
 export const RTSyntax = 1;