ink-sdl 0.4.0 → 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-YE6CUIKT.js → chunk-LP5C65TH.js}

@@ -1886,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;
@@ -1920,38 +1924,13 @@ var SdlUiRenderer = class {
    * Initialize SDL window and renderer
    */
   initSDL(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 };
-    let windowFlags = SDL_WINDOW_SHOWN | SDL_WINDOW_ALLOW_HIGHDPI;
-    if (!options.fullscreen) {
-      windowFlags |= SDL_WINDOW_RESIZABLE;
-    }
-    if (options.fullscreen === "desktop") {
-      windowFlags |= SDL_WINDOW_FULLSCREEN_DESKTOP;
-    } else if (options.fullscreen === true) {
-      windowFlags |= SDL_WINDOW_FULLSCREEN;
-    }
-    if (options.borderless && !options.fullscreen) {
-      windowFlags |= SDL_WINDOW_BORDERLESS;
-    }
-    this.window = this.sdl.createWindow(
-      options.title ?? "ink-sdl",
-      SDL_WINDOWPOS_CENTERED,
-      SDL_WINDOWPOS_CENTERED,
-      this.windowWidth,
-      this.windowHeight,
-      windowFlags
-    );
-    if (options.minWidth !== void 0 || options.minHeight !== void 0) {
-      const minW = options.minWidth ?? 1;
-      const minH = options.minHeight ?? 1;
-      this.sdl.setWindowMinimumSize(this.window, minW, minH);
+    if (options.existing) {
+      this.initWithExistingResources(options);
+    } else {
+      this.initNewResources(options);
     }
-    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;
@@ -1979,7 +1958,62 @@ var SdlUiRenderer = class {
     this.sdl.setRenderTarget(this.renderer, null);
     this.sdl.renderClear(this.renderer);
     this.sdl.renderPresent(this.renderer);
-    this.sdl.raiseWindow(this.window);
+    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.ownsWindow = true;
+    this.ownsRenderer = true;
+    let windowFlags = SDL_WINDOW_SHOWN | SDL_WINDOW_ALLOW_HIGHDPI;
+    if (!options.fullscreen) {
+      windowFlags |= SDL_WINDOW_RESIZABLE;
+    }
+    if (options.fullscreen === "desktop") {
+      windowFlags |= SDL_WINDOW_FULLSCREEN_DESKTOP;
+    } else if (options.fullscreen === true) {
+      windowFlags |= SDL_WINDOW_FULLSCREEN;
+    }
+    if (options.borderless && !options.fullscreen) {
+      windowFlags |= SDL_WINDOW_BORDERLESS;
+    }
+    this.window = this.sdl.createWindow(
+      options.title ?? "ink-sdl",
+      SDL_WINDOWPOS_CENTERED,
+      SDL_WINDOWPOS_CENTERED,
+      this.windowWidth,
+      this.windowHeight,
+      windowFlags
+    );
+    if (options.minWidth !== void 0 || options.minHeight !== void 0) {
+      const minW = options.minWidth ?? 1;
+      const minH = options.minHeight ?? 1;
+      this.sdl.setWindowMinimumSize(this.window, minW, minH);
+    }
+    const rendererFlags = options.vsync !== false ? SDL_RENDERER_ACCELERATED | SDL_RENDERER_PRESENTVSYNC : SDL_RENDERER_ACCELERATED;
+    this.renderer = this.sdl.createRenderer(this.window, -1, rendererFlags);
   }
   /**
    * Update terminal dimensions based on window size
@@ -2344,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) {
@@ -2354,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-YE6CUIKT.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
      */
@@ -383,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
      */
@@ -553,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
@@ -1059,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-YE6CUIKT.js";
+} from "./chunk-LP5C65TH.js";
 export {
   AnsiParser,
   InputBridge,

package/package.json

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