captions.js 0.1.2 → 0.2.0

package/README.md

@@ -11,7 +11,9 @@ A modern JavaScript library for adding captions to HTML5 videos with ease.
 
 [**Live Demo**](https://maskin25.github.io/captions.js/)
 
-[![Storybook](https://raw.githubusercontent.com/storybookjs/brand/refs/heads/main/badge/badge-storybook.svg)](https://main--68e681805917843931c33a87.chromatic.com/)
+[**Docs & API Reference**](https://maskin25.github.io/captions.js/docs/)
+
+<!-- [![Storybook](https://raw.githubusercontent.com/storybookjs/brand/refs/heads/main/badge/badge-storybook.svg)](https://main--68e681805917843931c33a87.chromatic.com/) -->
 
 ## Features
 

package/dist/index.d.mts

@@ -1,5 +1,18 @@
+/**
+ * Whitelisted Google Fonts that the renderer knows how to lazy-load.
+ *
+ * @remarks
+ * Restricting the list keeps bundle size predictable across consumers.
+ *
+ * @public
+ */
 declare const googleFontsList: readonly ["Roboto", "Open Sans", "Lato", "Montserrat", "Nunito", "Poppins", "Ubuntu", "PT Sans", "Merriweather Sans", "Lobster", "Amatic SC", "Pacifico", "Raleway", "Cinzel", "Quicksand", "Zilla Slab", "Caveat", "Crimson Pro", "Bebas Neue", "Comfortaa", "Satisfy", "Permanent Marker", "Oswald", "Onset", "Bangers", "Kanit", "Work Sans", "Fira Sans", "Anton", "Playfair Display", "Rubik", "Alumni Sans", "Righteous", "Comico", "Excon", "Kalam", "Tanker", "Arsenal", "Balsamiq Sans", "Bona Nova SC"];
 
+/**
+ * Shared schema describing how a preset styles captions plus rough layout hints.
+ *
+ * @public
+ */
 interface StylePreset {
     id: number;
     captionsSettings: {
@@ -37,17 +50,37 @@ interface StylePreset {
         fitLayoutAspectRatio: string;
     };
 }
+/**
+ * Curated set of presets that ship with captions.js out of the box.
+ *
+ * @remarks
+ * Downstream apps can reference them directly or clone/extend as needed.
+ *
+ * @public
+ */
 declare const stylePresets: StylePreset[];
 
+/**
+ * Server/worker-friendly helper that paints a text string onto a provided canvas.
+ *
+ * @remarks
+ * Uses the same Konva pipeline as the video overlay renderer so the results
+ * match what users see in the browser.
+ *
+ * @param canvas - Destination canvas that should receive the rendered text.
+ * @param text - Arbitrary content that needs to be painted.
+ * @param options - Rendering options that include the style preset.
+ * @returns Resolves once the frame has been painted (always resolves to `true`).
+ */
 declare function renderString(canvas: HTMLCanvasElement, text: string, options: {
     preset: StylePreset;
 }): Promise<boolean>;
 
-declare const attachToVideo: (videoElement: HTMLVideoElement, container?: HTMLDivElement, options?: any) => {
-    detach: () => void;
-    update: (newOptions: any) => Promise<void>;
-};
-
+/**
+ * Single timed word/segment that will be highlighted as audio plays.
+ *
+ * @public
+ */
 interface Caption {
     word: string;
     startTime: number;
@@ -55,6 +88,112 @@ interface Caption {
     highlightColor?: string;
 }
 
+/**
+ * Configuration passed to the captions runtime when binding to a video element.
+ *
+ * @public
+ */
+type CaptionsOptions = {
+    /** Video element that should receive overlays. */
+    video: HTMLVideoElement;
+    /** Optional custom container to host the Konva stage. */
+    container?: HTMLDivElement;
+    /** Initial preset controlling font, colors, animations. */
+    preset: StylePreset;
+    /** Initial caption track. */
+    captions?: Caption[] | null;
+    /** When false, caller must invoke {@link Captions.enable} manually. */
+    autoEnable?: boolean;
+};
+/**
+ * Imperative controller that owns the Konva stage lifecycle for a single video element.
+ *
+ * @public
+ */
+declare class Captions {
+    private enabled;
+    private readonly video;
+    private readonly providedContainer?;
+    private presetState;
+    private captionsState;
+    private containerElement?;
+    private ownsContainer;
+    private stage;
+    private layer;
+    private resizeObserver?;
+    private animationFrameId;
+    private videoWidth;
+    private videoHeight;
+    private readonly handleResize;
+    private readonly handleMetadata;
+    private readonly animationLoop;
+    /**
+     * Create a controller bound to the provided video element and preset.
+     *
+     * @param options - Complete configuration for the controller.
+     */
+    constructor(options: CaptionsOptions);
+    /**
+     * Mount caption overlays onto the configured video if they are not active yet.
+     */
+    enable(): void;
+    /**
+     * Tear down overlays, observers and animation loops to free resources.
+     */
+    disable(): void;
+    /**
+      * Alias for {@link Captions.disable | disable()} to match typical imperative controller APIs.
+     */
+    destroy(): void;
+    /**
+     * Swap the active preset and re-render with updated typography/colors.
+     *
+     * @param nextPreset - Preset that becomes the new render baseline.
+     */
+    preset(nextPreset: StylePreset): void;
+    /**
+     * Replace the current caption track and repaint without reloading fonts.
+     *
+     * @param nextCaptions - Timed words that should drive the overlay.
+     */
+    captions(nextCaptions: Caption[] | null): void;
+    /**
+     * Whether the Konva overlay is currently attached to the video element.
+     *
+     * @returns `true` when the overlay is mounted on top of the video.
+     */
+    isEnabled(): boolean;
+    private refreshFrame;
+    private loadFontForCurrentPreset;
+    private updateFrame;
+    private syncStageDimensions;
+    private createOverlay;
+}
+/**
+ * Convenience alias for the concrete controller class.
+ *
+ * @public
+ */
+type CaptionsInstance = Captions;
+/**
+ * Factory mirroring the legacy default export for ergonomic imports.
+ *
+ * @param options - Same options accepted by the {@link Captions} constructor.
+ * @returns New controller instance.
+ */
+declare function captionsjs(options: CaptionsOptions): Captions;
+
+/**
+ * Simple canvas demo renderer used only for the docs playground.
+ *
+ * @remarks
+ * Keeps a reference implementation of drawing raw text to a canvas so we can
+ * showcase caption styling without a video element.
+ *
+ * @param ctx - Target 2D context to draw on.
+ * @param text - Arbitrary string that should be painted on the canvas.
+ * @returns Always returns `true` to match the historical API surface.
+ */
 declare function renderCaptions(ctx: CanvasRenderingContext2D, text: string): boolean;
 
-export { type Caption, type StylePreset, attachToVideo, googleFontsList, renderCaptions, renderString, stylePresets };
+export { type Caption, Captions, type CaptionsInstance, type CaptionsOptions, type StylePreset, captionsjs, captionsjs as default, googleFontsList, renderCaptions, renderString, stylePresets };

package/dist/index.d.ts

@@ -1,5 +1,18 @@
+/**
+ * Whitelisted Google Fonts that the renderer knows how to lazy-load.
+ *
+ * @remarks
+ * Restricting the list keeps bundle size predictable across consumers.
+ *
+ * @public
+ */
 declare const googleFontsList: readonly ["Roboto", "Open Sans", "Lato", "Montserrat", "Nunito", "Poppins", "Ubuntu", "PT Sans", "Merriweather Sans", "Lobster", "Amatic SC", "Pacifico", "Raleway", "Cinzel", "Quicksand", "Zilla Slab", "Caveat", "Crimson Pro", "Bebas Neue", "Comfortaa", "Satisfy", "Permanent Marker", "Oswald", "Onset", "Bangers", "Kanit", "Work Sans", "Fira Sans", "Anton", "Playfair Display", "Rubik", "Alumni Sans", "Righteous", "Comico", "Excon", "Kalam", "Tanker", "Arsenal", "Balsamiq Sans", "Bona Nova SC"];
 
+/**
+ * Shared schema describing how a preset styles captions plus rough layout hints.
+ *
+ * @public
+ */
 interface StylePreset {
     id: number;
     captionsSettings: {
@@ -37,17 +50,37 @@ interface StylePreset {
         fitLayoutAspectRatio: string;
     };
 }
+/**
+ * Curated set of presets that ship with captions.js out of the box.
+ *
+ * @remarks
+ * Downstream apps can reference them directly or clone/extend as needed.
+ *
+ * @public
+ */
 declare const stylePresets: StylePreset[];
 
+/**
+ * Server/worker-friendly helper that paints a text string onto a provided canvas.
+ *
+ * @remarks
+ * Uses the same Konva pipeline as the video overlay renderer so the results
+ * match what users see in the browser.
+ *
+ * @param canvas - Destination canvas that should receive the rendered text.
+ * @param text - Arbitrary content that needs to be painted.
+ * @param options - Rendering options that include the style preset.
+ * @returns Resolves once the frame has been painted (always resolves to `true`).
+ */
 declare function renderString(canvas: HTMLCanvasElement, text: string, options: {
     preset: StylePreset;
 }): Promise<boolean>;
 
-declare const attachToVideo: (videoElement: HTMLVideoElement, container?: HTMLDivElement, options?: any) => {
-    detach: () => void;
-    update: (newOptions: any) => Promise<void>;
-};
-
+/**
+ * Single timed word/segment that will be highlighted as audio plays.
+ *
+ * @public
+ */
 interface Caption {
     word: string;
     startTime: number;
@@ -55,6 +88,112 @@ interface Caption {
     highlightColor?: string;
 }
 
+/**
+ * Configuration passed to the captions runtime when binding to a video element.
+ *
+ * @public
+ */
+type CaptionsOptions = {
+    /** Video element that should receive overlays. */
+    video: HTMLVideoElement;
+    /** Optional custom container to host the Konva stage. */
+    container?: HTMLDivElement;
+    /** Initial preset controlling font, colors, animations. */
+    preset: StylePreset;
+    /** Initial caption track. */
+    captions?: Caption[] | null;
+    /** When false, caller must invoke {@link Captions.enable} manually. */
+    autoEnable?: boolean;
+};
+/**
+ * Imperative controller that owns the Konva stage lifecycle for a single video element.
+ *
+ * @public
+ */
+declare class Captions {
+    private enabled;
+    private readonly video;
+    private readonly providedContainer?;
+    private presetState;
+    private captionsState;
+    private containerElement?;
+    private ownsContainer;
+    private stage;
+    private layer;
+    private resizeObserver?;
+    private animationFrameId;
+    private videoWidth;
+    private videoHeight;
+    private readonly handleResize;
+    private readonly handleMetadata;
+    private readonly animationLoop;
+    /**
+     * Create a controller bound to the provided video element and preset.
+     *
+     * @param options - Complete configuration for the controller.
+     */
+    constructor(options: CaptionsOptions);
+    /**
+     * Mount caption overlays onto the configured video if they are not active yet.
+     */
+    enable(): void;
+    /**
+     * Tear down overlays, observers and animation loops to free resources.
+     */
+    disable(): void;
+    /**
+      * Alias for {@link Captions.disable | disable()} to match typical imperative controller APIs.
+     */
+    destroy(): void;
+    /**
+     * Swap the active preset and re-render with updated typography/colors.
+     *
+     * @param nextPreset - Preset that becomes the new render baseline.
+     */
+    preset(nextPreset: StylePreset): void;
+    /**
+     * Replace the current caption track and repaint without reloading fonts.
+     *
+     * @param nextCaptions - Timed words that should drive the overlay.
+     */
+    captions(nextCaptions: Caption[] | null): void;
+    /**
+     * Whether the Konva overlay is currently attached to the video element.
+     *
+     * @returns `true` when the overlay is mounted on top of the video.
+     */
+    isEnabled(): boolean;
+    private refreshFrame;
+    private loadFontForCurrentPreset;
+    private updateFrame;
+    private syncStageDimensions;
+    private createOverlay;
+}
+/**
+ * Convenience alias for the concrete controller class.
+ *
+ * @public
+ */
+type CaptionsInstance = Captions;
+/**
+ * Factory mirroring the legacy default export for ergonomic imports.
+ *
+ * @param options - Same options accepted by the {@link Captions} constructor.
+ * @returns New controller instance.
+ */
+declare function captionsjs(options: CaptionsOptions): Captions;
+
+/**
+ * Simple canvas demo renderer used only for the docs playground.
+ *
+ * @remarks
+ * Keeps a reference implementation of drawing raw text to a canvas so we can
+ * showcase caption styling without a video element.
+ *
+ * @param ctx - Target 2D context to draw on.
+ * @param text - Arbitrary string that should be painted on the canvas.
+ * @returns Always returns `true` to match the historical API surface.
+ */
 declare function renderCaptions(ctx: CanvasRenderingContext2D, text: string): boolean;
 
-export { type Caption, type StylePreset, attachToVideo, googleFontsList, renderCaptions, renderString, stylePresets };
+export { type Caption, Captions, type CaptionsInstance, type CaptionsOptions, type StylePreset, captionsjs, captionsjs as default, googleFontsList, renderCaptions, renderString, stylePresets };

package/dist/index.js

@@ -30,7 +30,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  attachToVideo: () => attachToVideo,
+  Captions: () => Captions,
+  captionsjs: () => captionsjs,
+  default: () => index_default,
   googleFontsList: () => googleFontsList,
   renderCaptions: () => renderCaptions,
   renderString: () => renderString,
@@ -952,7 +954,7 @@ async function renderString(canvas, text, options) {
   return true;
 }
 
-// src/render/attachToVideo.ts
+// src/captions/Captions.ts
 var import_konva5 = __toESM(require("konva"));
 
 // src/canvas-captions/index.ts
@@ -1532,71 +1534,209 @@ var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targ
   layer.draw();
 };
 
-// src/render/attachToVideo.ts
-var attachedVideos = /* @__PURE__ */ new WeakMap();
-var attachToVideo = (videoElement, container, options) => {
-  if (!container) {
-    container = document.createElement("div");
-    container.style.position = "absolute";
-    container.style.top = "0";
-    container.style.left = "0";
-    container.style.width = "100%";
-    container.style.height = "100%";
-    container.style.pointerEvents = "none";
-    videoElement.parentElement?.appendChild(container);
+// src/captions/Captions.ts
+var Captions = class {
+  /**
+   * Create a controller bound to the provided video element and preset.
+   *
+   * @param options - Complete configuration for the controller.
+   */
+  constructor(options) {
+    this.enabled = false;
+    this.ownsContainer = false;
+    this.stage = null;
+    this.layer = null;
+    this.animationFrameId = null;
+    this.videoWidth = 0;
+    this.videoHeight = 0;
+    this.handleResize = () => {
+      this.syncStageDimensions();
+    };
+    this.handleMetadata = () => {
+      this.syncStageDimensions();
+    };
+    this.animationLoop = () => {
+      this.updateFrame();
+      this.animationFrameId = requestAnimationFrame(this.animationLoop);
+    };
+    if (!options.video) {
+      throw new Error("captionsjs requires a video element");
+    }
+    this.video = options.video;
+    this.providedContainer = options.container;
+    this.presetState = options.preset;
+    this.captionsState = options.captions ?? null;
+    if (options.autoEnable ?? true) {
+      this.enable();
+    }
   }
-  const stage = new import_konva5.default.Stage({
-    container,
-    width: videoElement.videoWidth,
-    height: videoElement.videoHeight
-  });
-  const layer = new import_konva5.default.Layer();
-  stage.add(layer);
-  stage.width(container.clientWidth);
-  stage.height(container.clientHeight);
-  const update = () => {
-    console.log(
-      "update captions at",
-      options.preset.captionsSettings.style.name
-    );
-    layer.destroyChildren();
+  /**
+   * Mount caption overlays onto the configured video if they are not active yet.
+   */
+  enable() {
+    if (this.enabled) {
+      return;
+    }
+    this.containerElement = this.providedContainer ?? this.createOverlay();
+    this.ownsContainer = !this.providedContainer;
+    this.stage = new import_konva5.default.Stage({
+      container: this.containerElement
+    });
+    this.layer = new import_konva5.default.Layer();
+    this.stage.add(this.layer);
+    this.videoWidth = this.video.videoWidth;
+    this.videoHeight = this.video.videoHeight;
+    window.addEventListener("resize", this.handleResize);
+    if (typeof ResizeObserver !== "undefined") {
+      this.resizeObserver = new ResizeObserver(this.handleResize);
+      this.resizeObserver.observe(this.video);
+    }
+    this.video.addEventListener("loadedmetadata", this.handleMetadata);
+    this.syncStageDimensions();
+    this.animationFrameId = requestAnimationFrame(this.animationLoop);
+    this.enabled = true;
+    void this.refreshFrame();
+  }
+  /**
+   * Tear down overlays, observers and animation loops to free resources.
+   */
+  disable() {
+    if (!this.enabled) {
+      return;
+    }
+    if (this.animationFrameId !== null) {
+      cancelAnimationFrame(this.animationFrameId);
+      this.animationFrameId = null;
+    }
+    window.removeEventListener("resize", this.handleResize);
+    this.video.removeEventListener("loadedmetadata", this.handleMetadata);
+    this.resizeObserver?.disconnect();
+    this.resizeObserver = void 0;
+    if (this.ownsContainer && this.containerElement?.parentElement) {
+      this.containerElement.parentElement.removeChild(this.containerElement);
+    }
+    this.stage?.destroy();
+    this.stage = null;
+    this.layer = null;
+    this.containerElement = void 0;
+    this.ownsContainer = false;
+    this.enabled = false;
+  }
+  /**
+    * Alias for {@link Captions.disable | disable()} to match typical imperative controller APIs.
+   */
+  destroy() {
+    this.disable();
+  }
+  /**
+   * Swap the active preset and re-render with updated typography/colors.
+   *
+   * @param nextPreset - Preset that becomes the new render baseline.
+   */
+  preset(nextPreset) {
+    this.presetState = nextPreset;
+    if (!this.enabled) {
+      return;
+    }
+    void this.refreshFrame();
+  }
+  /**
+   * Replace the current caption track and repaint without reloading fonts.
+   *
+   * @param nextCaptions - Timed words that should drive the overlay.
+   */
+  captions(nextCaptions) {
+    this.captionsState = nextCaptions;
+    if (!this.enabled) {
+      return;
+    }
+    void this.refreshFrame(false);
+  }
+  /**
+   * Whether the Konva overlay is currently attached to the video element.
+   *
+   * @returns `true` when the overlay is mounted on top of the video.
+   */
+  isEnabled() {
+    return this.enabled;
+  }
+  async refreshFrame(loadFont = true) {
+    if (!this.layer || !this.stage) {
+      return;
+    }
+    if (loadFont) {
+      await this.loadFontForCurrentPreset();
+    }
+    this.updateFrame();
+  }
+  async loadFontForCurrentPreset() {
+    const fontFamily = this.presetState.captionsSettings.style.font.fontFamily;
+    await loadGoogleFont2(fontFamily);
+  }
+  updateFrame() {
+    if (!this.layer || !this.stage) {
+      return;
+    }
+    if (!this.videoWidth || !this.videoHeight) {
+      return;
+    }
+    this.layer.destroyChildren();
     renderFrame(
-      options.preset.captionsSettings,
+      this.presetState.captionsSettings,
       void 0,
-      options.captions || [],
-      videoElement.currentTime,
-      [640, 360],
-      layer,
+      this.captionsState || [],
+      this.video.currentTime,
+      [this.videoWidth, this.videoHeight],
+      this.layer,
       1,
       { type: "bottom", positionTopOffset: 50 }
     );
-  };
-  let animationFrameId;
-  const animationLoop = () => {
-    update();
-    animationFrameId = requestAnimationFrame(animationLoop);
-  };
-  animationLoop();
-  const controls = {
-    detach: () => {
-      cancelAnimationFrame(animationFrameId);
-      if (container && container.parentElement) {
-        container.parentElement.removeChild(container);
-      }
-      stage.destroy();
-      attachedVideos.delete(videoElement);
-    },
-    update: async (newOptions) => {
-      options = { ...options, ...newOptions };
-      await loadGoogleFont2(
-        options.preset.captionsSettings.style.font.fontFamily
-      );
-      update();
+  }
+  syncStageDimensions() {
+    if (!this.stage) {
+      return;
     }
-  };
-  attachedVideos.set(videoElement, controls);
-  return controls;
+    const currentVideoWidth = this.video.videoWidth || this.videoWidth;
+    const currentVideoHeight = this.video.videoHeight || this.videoHeight;
+    if (!currentVideoWidth || !currentVideoHeight) {
+      return;
+    }
+    this.videoWidth = currentVideoWidth;
+    this.videoHeight = currentVideoHeight;
+    this.stage.width(this.videoWidth);
+    this.stage.height(this.videoHeight);
+    const rect = this.video.getBoundingClientRect();
+    const stageContainer = this.stage.container();
+    const displayWidth = rect.width || stageContainer.offsetWidth || this.videoWidth;
+    const displayHeight = rect.height || stageContainer.offsetHeight || this.videoHeight;
+    if (displayWidth && displayHeight) {
+      stageContainer.style.width = `${displayWidth}px`;
+      stageContainer.style.height = `${displayHeight}px`;
+      const scaleX = displayWidth / this.videoWidth;
+      const scaleY = displayHeight / this.videoHeight;
+      this.stage.scale({ x: scaleX, y: scaleY });
+    } else {
+      this.stage.scale({ x: 1, y: 1 });
+      stageContainer.style.width = `${this.videoWidth}px`;
+      stageContainer.style.height = `${this.videoHeight}px`;
+    }
+    this.stage.batchDraw();
+  }
+  createOverlay() {
+    const container = document.createElement("div");
+    container.style.position = "absolute";
+    container.style.top = "0";
+    container.style.left = "0";
+    container.style.width = "100%";
+    container.style.height = "100%";
+    container.style.pointerEvents = "none";
+    this.video.parentElement?.appendChild(container);
+    return container;
+  }
 };
+function captionsjs(options) {
+  return new Captions(options);
+}
 
 // src/index.ts
 function renderCaptions(ctx, text) {
@@ -1605,9 +1745,11 @@ function renderCaptions(ctx, text) {
   ctx.fillText(text, 150, 50);
   return true;
 }
+var index_default = captionsjs;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  attachToVideo,
+  Captions,
+  captionsjs,
   googleFontsList,
   renderCaptions,
   renderString,

package/dist/index.mjs

@@ -912,7 +912,7 @@ async function renderString(canvas, text, options) {
   return true;
 }
 
-// src/render/attachToVideo.ts
+// src/captions/Captions.ts
 import Konva5 from "konva";
 
 // src/canvas-captions/index.ts
@@ -1492,71 +1492,209 @@ var renderFrame = (captionsSettings, layoutSettings, captions, currentTime, targ
   layer.draw();
 };
 
-// src/render/attachToVideo.ts
-var attachedVideos = /* @__PURE__ */ new WeakMap();
-var attachToVideo = (videoElement, container, options) => {
-  if (!container) {
-    container = document.createElement("div");
-    container.style.position = "absolute";
-    container.style.top = "0";
-    container.style.left = "0";
-    container.style.width = "100%";
-    container.style.height = "100%";
-    container.style.pointerEvents = "none";
-    videoElement.parentElement?.appendChild(container);
+// src/captions/Captions.ts
+var Captions = class {
+  /**
+   * Create a controller bound to the provided video element and preset.
+   *
+   * @param options - Complete configuration for the controller.
+   */
+  constructor(options) {
+    this.enabled = false;
+    this.ownsContainer = false;
+    this.stage = null;
+    this.layer = null;
+    this.animationFrameId = null;
+    this.videoWidth = 0;
+    this.videoHeight = 0;
+    this.handleResize = () => {
+      this.syncStageDimensions();
+    };
+    this.handleMetadata = () => {
+      this.syncStageDimensions();
+    };
+    this.animationLoop = () => {
+      this.updateFrame();
+      this.animationFrameId = requestAnimationFrame(this.animationLoop);
+    };
+    if (!options.video) {
+      throw new Error("captionsjs requires a video element");
+    }
+    this.video = options.video;
+    this.providedContainer = options.container;
+    this.presetState = options.preset;
+    this.captionsState = options.captions ?? null;
+    if (options.autoEnable ?? true) {
+      this.enable();
+    }
   }
-  const stage = new Konva5.Stage({
-    container,
-    width: videoElement.videoWidth,
-    height: videoElement.videoHeight
-  });
-  const layer = new Konva5.Layer();
-  stage.add(layer);
-  stage.width(container.clientWidth);
-  stage.height(container.clientHeight);
-  const update = () => {
-    console.log(
-      "update captions at",
-      options.preset.captionsSettings.style.name
-    );
-    layer.destroyChildren();
+  /**
+   * Mount caption overlays onto the configured video if they are not active yet.
+   */
+  enable() {
+    if (this.enabled) {
+      return;
+    }
+    this.containerElement = this.providedContainer ?? this.createOverlay();
+    this.ownsContainer = !this.providedContainer;
+    this.stage = new Konva5.Stage({
+      container: this.containerElement
+    });
+    this.layer = new Konva5.Layer();
+    this.stage.add(this.layer);
+    this.videoWidth = this.video.videoWidth;
+    this.videoHeight = this.video.videoHeight;
+    window.addEventListener("resize", this.handleResize);
+    if (typeof ResizeObserver !== "undefined") {
+      this.resizeObserver = new ResizeObserver(this.handleResize);
+      this.resizeObserver.observe(this.video);
+    }
+    this.video.addEventListener("loadedmetadata", this.handleMetadata);
+    this.syncStageDimensions();
+    this.animationFrameId = requestAnimationFrame(this.animationLoop);
+    this.enabled = true;
+    void this.refreshFrame();
+  }
+  /**
+   * Tear down overlays, observers and animation loops to free resources.
+   */
+  disable() {
+    if (!this.enabled) {
+      return;
+    }
+    if (this.animationFrameId !== null) {
+      cancelAnimationFrame(this.animationFrameId);
+      this.animationFrameId = null;
+    }
+    window.removeEventListener("resize", this.handleResize);
+    this.video.removeEventListener("loadedmetadata", this.handleMetadata);
+    this.resizeObserver?.disconnect();
+    this.resizeObserver = void 0;
+    if (this.ownsContainer && this.containerElement?.parentElement) {
+      this.containerElement.parentElement.removeChild(this.containerElement);
+    }
+    this.stage?.destroy();
+    this.stage = null;
+    this.layer = null;
+    this.containerElement = void 0;
+    this.ownsContainer = false;
+    this.enabled = false;
+  }
+  /**
+    * Alias for {@link Captions.disable | disable()} to match typical imperative controller APIs.
+   */
+  destroy() {
+    this.disable();
+  }
+  /**
+   * Swap the active preset and re-render with updated typography/colors.
+   *
+   * @param nextPreset - Preset that becomes the new render baseline.
+   */
+  preset(nextPreset) {
+    this.presetState = nextPreset;
+    if (!this.enabled) {
+      return;
+    }
+    void this.refreshFrame();
+  }
+  /**
+   * Replace the current caption track and repaint without reloading fonts.
+   *
+   * @param nextCaptions - Timed words that should drive the overlay.
+   */
+  captions(nextCaptions) {
+    this.captionsState = nextCaptions;
+    if (!this.enabled) {
+      return;
+    }
+    void this.refreshFrame(false);
+  }
+  /**
+   * Whether the Konva overlay is currently attached to the video element.
+   *
+   * @returns `true` when the overlay is mounted on top of the video.
+   */
+  isEnabled() {
+    return this.enabled;
+  }
+  async refreshFrame(loadFont = true) {
+    if (!this.layer || !this.stage) {
+      return;
+    }
+    if (loadFont) {
+      await this.loadFontForCurrentPreset();
+    }
+    this.updateFrame();
+  }
+  async loadFontForCurrentPreset() {
+    const fontFamily = this.presetState.captionsSettings.style.font.fontFamily;
+    await loadGoogleFont2(fontFamily);
+  }
+  updateFrame() {
+    if (!this.layer || !this.stage) {
+      return;
+    }
+    if (!this.videoWidth || !this.videoHeight) {
+      return;
+    }
+    this.layer.destroyChildren();
     renderFrame(
-      options.preset.captionsSettings,
+      this.presetState.captionsSettings,
       void 0,
-      options.captions || [],
-      videoElement.currentTime,
-      [640, 360],
-      layer,
+      this.captionsState || [],
+      this.video.currentTime,
+      [this.videoWidth, this.videoHeight],
+      this.layer,
       1,
       { type: "bottom", positionTopOffset: 50 }
     );
-  };
-  let animationFrameId;
-  const animationLoop = () => {
-    update();
-    animationFrameId = requestAnimationFrame(animationLoop);
-  };
-  animationLoop();
-  const controls = {
-    detach: () => {
-      cancelAnimationFrame(animationFrameId);
-      if (container && container.parentElement) {
-        container.parentElement.removeChild(container);
-      }
-      stage.destroy();
-      attachedVideos.delete(videoElement);
-    },
-    update: async (newOptions) => {
-      options = { ...options, ...newOptions };
-      await loadGoogleFont2(
-        options.preset.captionsSettings.style.font.fontFamily
-      );
-      update();
+  }
+  syncStageDimensions() {
+    if (!this.stage) {
+      return;
     }
-  };
-  attachedVideos.set(videoElement, controls);
-  return controls;
+    const currentVideoWidth = this.video.videoWidth || this.videoWidth;
+    const currentVideoHeight = this.video.videoHeight || this.videoHeight;
+    if (!currentVideoWidth || !currentVideoHeight) {
+      return;
+    }
+    this.videoWidth = currentVideoWidth;
+    this.videoHeight = currentVideoHeight;
+    this.stage.width(this.videoWidth);
+    this.stage.height(this.videoHeight);
+    const rect = this.video.getBoundingClientRect();
+    const stageContainer = this.stage.container();
+    const displayWidth = rect.width || stageContainer.offsetWidth || this.videoWidth;
+    const displayHeight = rect.height || stageContainer.offsetHeight || this.videoHeight;
+    if (displayWidth && displayHeight) {
+      stageContainer.style.width = `${displayWidth}px`;
+      stageContainer.style.height = `${displayHeight}px`;
+      const scaleX = displayWidth / this.videoWidth;
+      const scaleY = displayHeight / this.videoHeight;
+      this.stage.scale({ x: scaleX, y: scaleY });
+    } else {
+      this.stage.scale({ x: 1, y: 1 });
+      stageContainer.style.width = `${this.videoWidth}px`;
+      stageContainer.style.height = `${this.videoHeight}px`;
+    }
+    this.stage.batchDraw();
+  }
+  createOverlay() {
+    const container = document.createElement("div");
+    container.style.position = "absolute";
+    container.style.top = "0";
+    container.style.left = "0";
+    container.style.width = "100%";
+    container.style.height = "100%";
+    container.style.pointerEvents = "none";
+    this.video.parentElement?.appendChild(container);
+    return container;
+  }
 };
+function captionsjs(options) {
+  return new Captions(options);
+}
 
 // src/index.ts
 function renderCaptions(ctx, text) {
@@ -1565,8 +1703,11 @@ function renderCaptions(ctx, text) {
   ctx.fillText(text, 150, 50);
   return true;
 }
+var index_default = captionsjs;
 export {
-  attachToVideo,
+  Captions,
+  captionsjs,
+  index_default as default,
   googleFontsList,
   renderCaptions,
   renderString,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "captions.js",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -30,12 +30,6 @@
       "require": "./dist/index.js"
     }
   },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts",
-    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
-    "prepublishOnly": "cp ../../README.md ./README.md && pnpm run build",
-    "postpublish": "rm -f README.md"
-  },
   "devDependencies": {
     "@types/object-hash": "^3.0.6",
     "tsup": "^8.0.0",
@@ -44,5 +38,9 @@
   "dependencies": {
     "konva": "^10.0.2",
     "object-hash": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch"
   }
-}
+}