ink-sdl 0.3.2 → 0.5.0

package/README.md

@@ -168,6 +168,7 @@ Creates stdin/stdout streams and a window for use with Ink.
 | `borderless`      | `boolean`                            | `false`     | Remove window decorations (title bar, borders)             |
 | `minWidth`        | `number`                             | `undefined` | Minimum window width in pixels                             |
 | `minHeight`       | `number`                             | `undefined` | Minimum window height in pixels                            |
+| `existing`        | `ExistingSdlResources`               | `undefined` | Use existing SDL window/renderer (see Advanced Usage)      |
 
 #### Returns
 
@@ -213,6 +214,49 @@ if (isSdlAvailable()) {
 
 ## Advanced Usage
 
+### Using Existing SDL Window/Renderer
+
+For applications that need to share a single SDL window between ink-sdl and custom rendering (e.g., an emulator with a menu UI), you can pass existing SDL resources:
+
+```typescript
+import { render, Text, Box } from "ink";
+import { createSdlStreams, getSdl2, type ExistingSdlResources } from "ink-sdl";
+
+// Create your own SDL window and renderer
+const sdl = getSdl2();
+sdl.init(0x20 | 0x4000); // SDL_INIT_VIDEO | SDL_INIT_EVENTS
+
+const myWindow = sdl.createWindow("My App", 100, 100, 800, 600, 0x4);
+const myRenderer = sdl.createRenderer(myWindow, -1, 0x2);
+
+// Use them with ink-sdl
+const streams = createSdlStreams({
+  existing: { window: myWindow, renderer: myRenderer },
+  fontSize: 16,
+});
+
+render(<MenuApp />, { stdin: streams.stdin, stdout: streams.stdout });
+
+// When done with ink-sdl UI, close() cleans up ink-sdl resources
+// but does NOT destroy your window/renderer
+streams.window.close();
+
+// You can now render directly to the same window, or create new streams later
+// When completely done, destroy the window/renderer yourself
+sdl.destroyRenderer(myRenderer);
+sdl.destroyWindow(myWindow);
+```
+
+**Ownership rules:**
+
+- When `existing` is provided, ink-sdl does NOT own the window/renderer
+- `close()` will NOT destroy the provided window/renderer
+- The caller retains ownership and must destroy them when fully done
+- Window options (`width`, `height`, `title`, `fullscreen`, `borderless`) are ignored
+- Rendering options (`fontSize`, `scaleFactor`, `fontPath`, etc.) still apply
+
+### Low-Level Components
+
 For more control, you can use the lower-level components directly:
 
 ```typescript
@@ -223,6 +267,8 @@ import {
   InputBridge,
   getSdl2,
   getSdlTtf,
+  type ExistingSdlResources,
+  type SDLPointer,
 } from "ink-sdl";
 ```
 

package/dist/{chunk-BOQYTA3S.js → chunk-LP5C65TH.js}

@@ -4,9 +4,18 @@ import { pickBy, isDefined } from "remeda";
 
 // src/Sdl2/index.ts
 import koffi from "koffi";
-import { platform } from "os";
+
+// src/utils/findLibrary/index.ts
 import { existsSync } from "fs";
+import { platform } from "os";
 import { find, last } from "remeda";
+var isSystemPath = (p) => !p.includes("/") && !p.includes("\\");
+var findLibrary = (pathMap) => {
+  const plat = platform();
+  const paths = pathMap[plat] ?? [];
+  const foundPath = find(paths, (p) => isSystemPath(p) || existsSync(p));
+  return foundPath ?? last(paths) ?? null;
+};
 
 // src/Sdl2/consts.ts
 var SDL_INIT_VIDEO = 32;
@@ -94,13 +103,6 @@ var SDL_LIB_PATHS = {
   ],
   win32: ["SDL2.dll", "C:\\Windows\\System32\\SDL2.dll"]
 };
-var isSystemPath = (p) => !p.includes("/") && !p.includes("\\");
-var findLibrary = (pathMap) => {
-  const plat = platform();
-  const paths = pathMap[plat] ?? [];
-  const foundPath = find(paths, (p) => isSystemPath(p) || existsSync(p));
-  return foundPath ?? last(paths) ?? null;
-};
 var findSDLLibrary = () => {
   return findLibrary(SDL_LIB_PATHS);
 };
@@ -962,15 +964,12 @@ var AnsiParser = class {
 // src/TextRenderer/index.ts
 import { resolve, dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { existsSync as existsSync3 } from "fs";
-import { platform as platform3, homedir } from "os";
-import { sortBy, take } from "remeda";
+import { existsSync as existsSync2 } from "fs";
+import { platform as platform2, homedir } from "os";
+import { flatMap, sortBy, take } from "remeda";
 
 // src/SdlTtf/index.ts
 import koffi2 from "koffi";
-import { platform as platform2 } from "os";
-import { existsSync as existsSync2 } from "fs";
-import { find as find2, last as last2 } from "remeda";
 var SDL_TTF_LIB_PATHS = {
   darwin: [
     "/opt/homebrew/lib/libSDL2_ttf.dylib",
@@ -996,15 +995,8 @@ var SDL_TTF_LIB_PATHS = {
   ],
   win32: ["SDL2_ttf.dll", "C:\\Windows\\System32\\SDL2_ttf.dll"]
 };
-var isSystemPath2 = (p) => !p.includes("/") && !p.includes("\\");
-var findLibrary2 = (pathMap) => {
-  const plat = platform2();
-  const paths = pathMap[plat] ?? [];
-  const foundPath = find2(paths, (p) => isSystemPath2(p) || existsSync2(p));
-  return foundPath ?? last2(paths) ?? null;
-};
 var findSDLTtfLibrary = () => {
-  return findLibrary2(SDL_TTF_LIB_PATHS);
+  return findLibrary(SDL_TTF_LIB_PATHS);
 };
 var SdlTtf = class {
   lib;
@@ -1214,6 +1206,21 @@ var EMOJI_FONTS = {
 var EMOJI_FONT_SCALE = 0.75;
 
 // src/TextRenderer/index.ts
+var findFirstExisting = (paths) => {
+  for (const p of paths) {
+    try {
+      if (existsSync2(p)) {
+        return p;
+      }
+    } catch {
+    }
+  }
+  return null;
+};
+var getPlatformPaths = (pathMap) => {
+  const plat = platform2();
+  return [...pathMap[plat] ?? []];
+};
 var TextRenderer = class {
   sdl = getSdl2();
   ttf = getSdlTtf();
@@ -1252,7 +1259,7 @@ var TextRenderer = class {
    */
   getSystemFontDirectories() {
     const home = homedir();
-    const plat = platform3();
+    const plat = platform2();
     if (plat === "darwin") {
       return [
         join(home, "Library/Fonts"),
@@ -1291,16 +1298,13 @@ var TextRenderer = class {
   findFontByName(fontName) {
     const extensions = [".ttf", ".ttc", ".otf", ".TTC", ".TTF", ".OTF"];
     const directories = this.getSystemFontDirectories();
-    for (const dir of directories) {
-      for (const ext of extensions) {
-        const fontPath = join(dir, `${fontName}${ext}`);
-        try {
-          if (existsSync3(fontPath)) {
-            return fontPath;
-          }
-        } catch {
-        }
-      }
+    const paths = flatMap(
+      directories,
+      (dir) => extensions.map((ext) => join(dir, `${fontName}${ext}`))
+    );
+    const fontPath = findFirstExisting(paths);
+    if (fontPath) {
+      return fontPath;
     }
     throw new Error(
       `Font "${fontName}" not found in system font directories.
@@ -1313,13 +1317,9 @@ Tried extensions: ${extensions.join(", ")}`
    * Get the path to the Cozette font (system or bundled)
    */
   getDefaultFontPath() {
-    for (const p of this.getSystemFontPaths()) {
-      try {
-        if (existsSync3(p)) {
-          return p;
-        }
-      } catch {
-      }
+    const systemPath = findFirstExisting(this.getSystemFontPaths());
+    if (systemPath) {
+      return systemPath;
     }
     const currentFilename = fileURLToPath(import.meta.url);
     const currentDirname = dirname(currentFilename);
@@ -1331,96 +1331,38 @@ Tried extensions: ${extensions.join(", ")}`
       resolve(currentDirname, "../fonts", DEFAULT_FONT_FILENAME)
       // Alternate
     ];
-    for (const p of bundledPaths) {
-      try {
-        if (existsSync3(p)) {
-          return p;
-        }
-      } catch {
-      }
-    }
-    return bundledPaths[0];
+    return findFirstExisting(bundledPaths) ?? bundledPaths[0];
   }
   /**
    * Get fallback fonts for the current platform
    */
   getFallbackFontPaths() {
-    const plat = platform3();
-    if (plat === "darwin") {
-      return [...FALLBACK_FONTS.darwin];
-    }
-    if (plat === "linux") {
-      return [...FALLBACK_FONTS.linux];
-    }
-    if (plat === "win32") {
-      return [...FALLBACK_FONTS.win32];
-    }
-    return [];
+    return getPlatformPaths(FALLBACK_FONTS);
   }
   /**
    * Find an available font, trying default first then fallbacks
    */
   findAvailableFont() {
     const defaultPath = this.getDefaultFontPath();
-    try {
-      if (existsSync3(defaultPath)) {
-        return defaultPath;
-      }
-    } catch {
-    }
-    for (const fallbackPath of this.getFallbackFontPaths()) {
-      try {
-        if (existsSync3(fallbackPath)) {
-          return fallbackPath;
-        }
-      } catch {
-      }
-    }
-    return defaultPath;
+    return findFirstExisting([defaultPath, ...this.getFallbackFontPaths()]) ?? defaultPath;
   }
   /**
    * Find a system font, skipping the default bundled font
    */
   findSystemFont() {
-    for (const fallbackPath of this.getFallbackFontPaths()) {
-      try {
-        if (existsSync3(fallbackPath)) {
-          return fallbackPath;
-        }
-      } catch {
-      }
-    }
-    return this.getDefaultFontPath();
+    return findFirstExisting(this.getFallbackFontPaths()) ?? this.getDefaultFontPath();
   }
   /**
    * Get emoji font paths for the current platform
    */
   getEmojiFontPaths() {
-    const plat = platform3();
-    if (plat === "darwin") {
-      return [...EMOJI_FONTS.darwin];
-    }
-    if (plat === "linux") {
-      return [...EMOJI_FONTS.linux];
-    }
-    if (plat === "win32") {
-      return [...EMOJI_FONTS.win32];
-    }
-    return [];
+    return getPlatformPaths(EMOJI_FONTS);
   }
   /**
    * Find an available emoji font
    */
   findEmojiFont() {
-    for (const fontPath of this.getEmojiFontPaths()) {
-      try {
-        if (existsSync3(fontPath)) {
-          return fontPath;
-        }
-      } catch {
-      }
-    }
-    return null;
+    return findFirstExisting(this.getEmojiFontPaths());
   }
   /**
    * Load the fallback emoji font if available
@@ -1912,6 +1854,11 @@ var TEXT_DECORATION_THICKNESS = 0.08;
 var DEFAULT_BG2 = { r: 0, g: 0, b: 0 };
 var DEFAULT_FG2 = { r: 255, g: 255, b: 255 };
 var MIN_BRIGHTNESS = 100;
+var adjustBrightness = (color, multiplier, clamp = true) => ({
+  r: clamp ? Math.min(COLOR_CHANNEL_MAX, Math.floor(color.r * multiplier)) : Math.floor(color.r * multiplier),
+  g: clamp ? Math.min(COLOR_CHANNEL_MAX, Math.floor(color.g * multiplier)) : Math.floor(color.g * multiplier),
+  b: clamp ? Math.min(COLOR_CHANNEL_MAX, Math.floor(color.b * multiplier)) : Math.floor(color.b * multiplier)
+});
 var HEX_COLOR_LENGTH = 6;
 var HEX_R_END = 2;
 var HEX_G_END = 4;
@@ -1939,6 +1886,10 @@ var SdlUiRenderer = class {
   renderer = null;
   textRenderer = null;
   renderTarget = null;
+  /** Whether we own the window (should destroy it on cleanup) */
+  ownsWindow = true;
+  /** Whether we own the renderer (should destroy it on cleanup) */
+  ownsRenderer = true;
   ansiParser;
   inputBridge;
   windowWidth;
@@ -1973,11 +1924,69 @@ var SdlUiRenderer = class {
    * Initialize SDL window and renderer
    */
   initSDL(options) {
+    this.defaultBgColor = parseBackgroundColor(options.backgroundColor);
+    this.bgColor = { ...this.defaultBgColor };
+    if (options.existing) {
+      this.initWithExistingResources(options);
+    } else {
+      this.initNewResources(options);
+    }
+    this.userScaleFactor = options.scaleFactor === void 0 ? null : options.scaleFactor;
+    if (this.userScaleFactor !== null) {
+      this.scaleFactor = this.userScaleFactor;
+    } else {
+      this.scaleFactor = this.sdl.getScaleFactorFromRenderer(
+        this.window,
+        this.renderer
+      );
+    }
+    this.textRenderer = new TextRenderer(this.renderer, {
+      fontSize: options.fontSize ?? DEFAULT_FONT_SIZE,
+      scaleFactor: this.scaleFactor,
+      ...options.systemFont && { systemFont: true },
+      ...options.fontPath && { fontPath: options.fontPath },
+      ...options.fontName && { fontName: options.fontName }
+    });
+    const charDims = this.textRenderer.getCharDimensions();
+    this.charWidth = charDims.width;
+    this.charHeight = charDims.height;
+    this.updateTerminalDimensions();
+    this.createRenderTarget();
+    this.setDrawColor(this.defaultBgColor);
+    this.sdl.setRenderTarget(this.renderer, this.renderTarget);
+    this.sdl.renderClear(this.renderer);
+    this.sdl.setRenderTarget(this.renderer, null);
+    this.sdl.renderClear(this.renderer);
+    this.sdl.renderPresent(this.renderer);
+    if (this.ownsWindow) {
+      this.sdl.raiseWindow(this.window);
+    }
+  }
+  /**
+   * Initialize with existing SDL window and renderer
+   */
+  initWithExistingResources(options) {
+    const existing = options.existing;
+    this.window = existing.window;
+    this.renderer = existing.renderer;
+    this.ownsWindow = false;
+    this.ownsRenderer = false;
+    if (!this.sdl.init(SDL_INIT_EVENTS)) {
+      throw new Error("Failed to initialize SDL2 events");
+    }
+    const size = this.sdl.getWindowSize(this.window);
+    this.windowWidth = size.width;
+    this.windowHeight = size.height;
+  }
+  /**
+   * Initialize by creating new SDL window and renderer
+   */
+  initNewResources(options) {
     if (!this.sdl.init(SDL_INIT_VIDEO | SDL_INIT_EVENTS)) {
       throw new Error("Failed to initialize SDL2 for UI rendering");
     }
-    this.defaultBgColor = parseBackgroundColor(options.backgroundColor);
-    this.bgColor = { ...this.defaultBgColor };
+    this.ownsWindow = true;
+    this.ownsRenderer = true;
     let windowFlags = SDL_WINDOW_SHOWN | SDL_WINDOW_ALLOW_HIGHDPI;
     if (!options.fullscreen) {
       windowFlags |= SDL_WINDOW_RESIZABLE;
@@ -2005,40 +2014,6 @@ var SdlUiRenderer = class {
     }
     const rendererFlags = options.vsync !== false ? SDL_RENDERER_ACCELERATED | SDL_RENDERER_PRESENTVSYNC : SDL_RENDERER_ACCELERATED;
     this.renderer = this.sdl.createRenderer(this.window, -1, rendererFlags);
-    this.userScaleFactor = options.scaleFactor === void 0 ? null : options.scaleFactor;
-    if (this.userScaleFactor !== null) {
-      this.scaleFactor = this.userScaleFactor;
-    } else {
-      this.scaleFactor = this.sdl.getScaleFactorFromRenderer(
-        this.window,
-        this.renderer
-      );
-    }
-    this.textRenderer = new TextRenderer(this.renderer, {
-      fontSize: options.fontSize ?? DEFAULT_FONT_SIZE,
-      scaleFactor: this.scaleFactor,
-      ...options.systemFont && { systemFont: true },
-      ...options.fontPath && { fontPath: options.fontPath },
-      ...options.fontName && { fontName: options.fontName }
-    });
-    const charDims = this.textRenderer.getCharDimensions();
-    this.charWidth = charDims.width;
-    this.charHeight = charDims.height;
-    this.updateTerminalDimensions();
-    this.createRenderTarget();
-    this.sdl.setRenderDrawColor(
-      this.renderer,
-      this.defaultBgColor.r,
-      this.defaultBgColor.g,
-      this.defaultBgColor.b,
-      COLOR_CHANNEL_MAX
-    );
-    this.sdl.setRenderTarget(this.renderer, this.renderTarget);
-    this.sdl.renderClear(this.renderer);
-    this.sdl.setRenderTarget(this.renderer, null);
-    this.sdl.renderClear(this.renderer);
-    this.sdl.renderPresent(this.renderer);
-    this.sdl.raiseWindow(this.window);
   }
   /**
    * Update terminal dimensions based on window size
@@ -2130,13 +2105,7 @@ var SdlUiRenderer = class {
         this.renderText(cmd);
         break;
       case "clear_screen":
-        this.sdl.setRenderDrawColor(
-          this.renderer,
-          this.defaultBgColor.r,
-          this.defaultBgColor.g,
-          this.defaultBgColor.b,
-          COLOR_CHANNEL_MAX
-        );
+        this.setDrawColor(this.defaultBgColor);
         this.sdl.renderClear(this.renderer);
         this.ansiParser.reset();
         break;
@@ -2200,50 +2169,22 @@ var SdlUiRenderer = class {
     let fg = this.reverse ? this.bgColor : this.fgColor;
     const bg = this.reverse ? this.fgColor : this.bgColor;
     if (this.bold) {
-      fg = {
-        r: Math.min(
-          COLOR_CHANNEL_MAX,
-          Math.floor(fg.r * BOLD_BRIGHTNESS_MULTIPLIER)
-        ),
-        g: Math.min(
-          COLOR_CHANNEL_MAX,
-          Math.floor(fg.g * BOLD_BRIGHTNESS_MULTIPLIER)
-        ),
-        b: Math.min(
-          COLOR_CHANNEL_MAX,
-          Math.floor(fg.b * BOLD_BRIGHTNESS_MULTIPLIER)
-        )
-      };
+      fg = adjustBrightness(fg, BOLD_BRIGHTNESS_MULTIPLIER);
     }
     if (this.dim) {
-      fg = {
-        r: Math.floor(fg.r * DIM_BRIGHTNESS_MULTIPLIER),
-        g: Math.floor(fg.g * DIM_BRIGHTNESS_MULTIPLIER),
-        b: Math.floor(fg.b * DIM_BRIGHTNESS_MULTIPLIER)
-      };
+      fg = adjustBrightness(fg, DIM_BRIGHTNESS_MULTIPLIER, false);
     }
     const brightness = Math.max(fg.r, fg.g, fg.b);
     if (brightness < MIN_BRIGHTNESS) {
       if (brightness === 0) {
         fg = { r: MIN_BRIGHTNESS, g: MIN_BRIGHTNESS, b: MIN_BRIGHTNESS };
       } else {
-        const scale = MIN_BRIGHTNESS / brightness;
-        fg = {
-          r: Math.min(COLOR_CHANNEL_MAX, Math.floor(fg.r * scale)),
-          g: Math.min(COLOR_CHANNEL_MAX, Math.floor(fg.g * scale)),
-          b: Math.min(COLOR_CHANNEL_MAX, Math.floor(fg.b * scale))
-        };
+        fg = adjustBrightness(fg, MIN_BRIGHTNESS / brightness);
       }
     }
     const textWidth = text.length * this.charWidth;
     const bgRect = createSDLRect(x, y, textWidth, this.charHeight);
-    this.sdl.setRenderDrawColor(
-      this.renderer,
-      bg.r,
-      bg.g,
-      bg.b,
-      COLOR_CHANNEL_MAX
-    );
+    this.setDrawColor(bg);
     this.sdl.renderFillRect(this.renderer, bgRect);
     this.textRenderer.renderText(text, x, y, fg, this.italic);
     if (this.underline || this.strikethrough) {
@@ -2251,13 +2192,7 @@ var SdlUiRenderer = class {
         1,
         Math.round(this.charHeight * TEXT_DECORATION_THICKNESS)
       );
-      this.sdl.setRenderDrawColor(
-        this.renderer,
-        fg.r,
-        fg.g,
-        fg.b,
-        COLOR_CHANNEL_MAX
-      );
+      this.setDrawColor(fg);
       if (this.underline) {
         const underlineY = y + Math.round(this.charHeight * UNDERLINE_POSITION);
         const underlineRect = createSDLRect(
@@ -2283,16 +2218,22 @@ var SdlUiRenderer = class {
       return;
     }
     this.sdl.setRenderTarget(this.renderer, this.renderTarget);
+    this.setDrawColor(this.defaultBgColor);
+    this.sdl.renderClear(this.renderer);
+    this.sdl.setRenderTarget(this.renderer, null);
+    this.ansiParser.reset();
+  }
+  /**
+   * Set the SDL render draw color
+   */
+  setDrawColor(color) {
     this.sdl.setRenderDrawColor(
       this.renderer,
-      this.defaultBgColor.r,
-      this.defaultBgColor.g,
-      this.defaultBgColor.b,
+      color.r,
+      color.g,
+      color.b,
       COLOR_CHANNEL_MAX
     );
-    this.sdl.renderClear(this.renderer);
-    this.sdl.setRenderTarget(this.renderer, null);
-    this.ansiParser.reset();
   }
   /**
    * Clear a line from a specific position
@@ -2306,13 +2247,7 @@ var SdlUiRenderer = class {
     const drawable = this.sdl.getDrawableSize(this.window);
     const clearWidth = drawable.width - x;
     const rect = createSDLRect(x, y, clearWidth, this.charHeight);
-    this.sdl.setRenderDrawColor(
-      this.renderer,
-      this.bgColor.r,
-      this.bgColor.g,
-      this.bgColor.b,
-      COLOR_CHANNEL_MAX
-    );
+    this.setDrawColor(this.bgColor);
     this.sdl.renderFillRect(this.renderer, rect);
   }
   /**
@@ -2443,6 +2378,11 @@ var SdlUiRenderer = class {
   }
   /**
    * Clean up resources
+   *
+   * When using existing window/renderer (via `existing` option), this method
+   * will NOT destroy the window or renderer - only the resources created by
+   * ink-sdl (TextRenderer, render target texture). The caller is responsible
+   * for destroying the window/renderer they provided.
    */
   destroy() {
     if (this.textRenderer) {
@@ -2453,14 +2393,22 @@ var SdlUiRenderer = class {
       this.sdl.destroyTexture(this.renderTarget);
       this.renderTarget = null;
     }
-    if (this.renderer) {
+    if (this.ownsRenderer && this.renderer) {
       this.sdl.destroyRenderer(this.renderer);
-      this.renderer = null;
     }
-    if (this.window) {
+    this.renderer = null;
+    if (this.ownsWindow && this.window) {
       this.sdl.destroyWindow(this.window);
-      this.window = null;
     }
+    this.window = null;
+  }
+  /**
+   * Check if this renderer owns the SDL window
+   *
+   * Returns false when using an existing window via the `existing` option.
+   */
+  ownsResources() {
+    return this.ownsWindow && this.ownsRenderer;
   }
   /**
    * Reset state for reuse

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   createSdlStreams
-} from "./chunk-BOQYTA3S.js";
+} from "./chunk-LP5C65TH.js";
 
 // src/cli.tsx
 import { parseArgs } from "util";

package/dist/index.d.ts

@@ -220,6 +220,19 @@ declare const createSDLRect: (x: number, y: number, w: number, h: number) => Buf
  * from Ink and renders it to an SDL window using text rendering.
  */
 
+/**
+ * Existing SDL resources to use instead of creating new ones.
+ *
+ * When provided, ink-sdl will use these resources instead of creating its own.
+ * The caller retains ownership and is responsible for destroying them after
+ * ink-sdl is done.
+ */
+interface ExistingSdlResources {
+    /** Existing SDL window pointer */
+    window: SDLPointer;
+    /** Existing SDL renderer pointer */
+    renderer: SDLPointer;
+}
 interface SdlUiRendererOptions {
     width?: number;
     height?: number;
@@ -243,6 +256,19 @@ interface SdlUiRendererOptions {
     minWidth?: number | undefined;
     /** Minimum window height in pixels */
     minHeight?: number | undefined;
+    /**
+     * Use existing SDL window and renderer instead of creating new ones.
+     *
+     * When provided, ink-sdl will:
+     * - Use the existing window/renderer for all rendering
+     * - NOT destroy them when destroy() is called (caller retains ownership)
+     * - Read dimensions from the existing window
+     * - Ignore width/height/title/fullscreen/borderless options (window already exists)
+     *
+     * This enables sharing a single SDL window between ink-sdl and other renderers,
+     * such as an emulator that switches between menu UI and game rendering.
+     */
+    existing?: ExistingSdlResources | undefined;
 }
 /** Result from processing SDL events */
 interface ProcessEventsResult {
@@ -265,6 +291,10 @@ declare class SdlUiRenderer {
     private renderer;
     private textRenderer;
     private renderTarget;
+    /** Whether we own the window (should destroy it on cleanup) */
+    private ownsWindow;
+    /** Whether we own the renderer (should destroy it on cleanup) */
+    private ownsRenderer;
     private ansiParser;
     private inputBridge;
     private windowWidth;
@@ -291,6 +321,14 @@ declare class SdlUiRenderer {
      * Initialize SDL window and renderer
      */
     private initSDL;
+    /**
+     * Initialize with existing SDL window and renderer
+     */
+    private initWithExistingResources;
+    /**
+     * Initialize by creating new SDL window and renderer
+     */
+    private initNewResources;
     /**
      * Update terminal dimensions based on window size
      */
@@ -334,6 +372,10 @@ declare class SdlUiRenderer {
      * Clear the entire screen
      */
     clear(): void;
+    /**
+     * Set the SDL render draw color
+     */
+    private setDrawColor;
     /**
      * Clear a line from a specific position
      */
@@ -379,8 +421,19 @@ declare class SdlUiRenderer {
     getScaleFactor(): number;
     /**
      * Clean up resources
+     *
+     * When using existing window/renderer (via `existing` option), this method
+     * will NOT destroy the window or renderer - only the resources created by
+     * ink-sdl (TextRenderer, render target texture). The caller is responsible
+     * for destroying the window/renderer they provided.
      */
     destroy(): void;
+    /**
+     * Check if this renderer owns the SDL window
+     *
+     * Returns false when using an existing window via the `existing` option.
+     */
+    ownsResources(): boolean;
     /**
      * Reset state for reuse
      */
@@ -549,6 +602,37 @@ interface SdlStreamsOptions {
     minWidth?: number | undefined;
     /** Minimum window height in pixels */
     minHeight?: number | undefined;
+    /**
+     * Use existing SDL window and renderer instead of creating new ones.
+     *
+     * When provided, ink-sdl will:
+     * - Use the existing window/renderer for all rendering
+     * - NOT destroy them when the window is closed (caller retains ownership)
+     * - Read dimensions from the existing window
+     * - Ignore width/height/title/fullscreen/borderless options
+     *
+     * @example
+     * ```typescript
+     * // Create your own SDL window and renderer
+     * const myWindow = SDL_CreateWindow(...);
+     * const myRenderer = SDL_CreateRenderer(myWindow, ...);
+     *
+     * // Use them with ink-sdl
+     * const streams = createSdlStreams({
+     *   existing: { window: myWindow, renderer: myRenderer },
+     *   fontSize: 16,
+     * });
+     *
+     * // When done with ink-sdl, clean up
+     * streams.window.close();
+     *
+     * // You can now use the window/renderer for other purposes
+     * // or destroy them yourself when fully done
+     * SDL_DestroyRenderer(myRenderer);
+     * SDL_DestroyWindow(myWindow);
+     * ```
+     */
+    existing?: ExistingSdlResources | undefined;
 }
 /**
  * SDL Window wrapper that emits events
@@ -1055,4 +1139,4 @@ declare class InputBridge {
  */
 declare const isSdlAvailable: () => boolean;
 
-export { AnsiParser, type Color, type DrawCommand, type InkKeyEvent, InputBridge, type SDLPointer, Sdl2, SdlInputStream, type SdlKeyEvent, SdlOutputStream, type SdlStreams, type SdlStreamsOptions, SdlTtf, SdlUiRenderer, type SdlUiRendererOptions, SdlWindow, TextRenderer, createSDLRect, createSdlStreams, getSdl2, getSdlTtf, isSdl2Available, isSdlAvailable, isSdlTtfAvailable };
+export { AnsiParser, type Color, type DrawCommand, type ExistingSdlResources, type InkKeyEvent, InputBridge, type SDLPointer, Sdl2, SdlInputStream, type SdlKeyEvent, SdlOutputStream, type SdlStreams, type SdlStreamsOptions, SdlTtf, SdlUiRenderer, type SdlUiRendererOptions, SdlWindow, TextRenderer, createSDLRect, createSdlStreams, getSdl2, getSdlTtf, isSdl2Available, isSdlAvailable, isSdlTtfAvailable };

package/dist/index.js

@@ -15,7 +15,7 @@ import {
   isSdl2Available,
   isSdlAvailable,
   isSdlTtfAvailable
-} from "./chunk-BOQYTA3S.js";
+} from "./chunk-LP5C65TH.js";
 export {
   AnsiParser,
   InputBridge,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ink-sdl",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Render Ink terminal apps in native SDL windows",
   "type": "module",
   "main": "dist/index.js",