@twick/visualizer 0.15.13 → 0.15.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@twick/visualizer",
-  "version": "0.15.13",
+  "version": "0.15.15",
   "license": "https://github.com/ncounterspecialist/twick/blob/main/LICENSE.md",
   "scripts": {
     "start": "twick editor --projectFile ./src/live.tsx",
@@ -22,18 +22,18 @@
   },
   "dependencies": {
     "@preact/signals": "^1.2.1",
-    "@twick/2d": "^0.15.13",
-    "@twick/core": "^0.15.13",
-    "@twick/renderer": "^0.15.13",
-    "@twick/vite-plugin": "^0.15.13",
+    "@twick/2d": "^0.15.15",
+    "@twick/core": "^0.15.15",
+    "@twick/renderer": "^0.15.15",
+    "@twick/vite-plugin": "^0.15.15",
     "date-fns": "^4.1.0",
     "preact": "^10.19.2",
     "crelt": "^1.0.6",
-    "@twick/media-utils": "0.15.13"
+    "@twick/media-utils": "0.15.15"
   },
   "devDependencies": {
-    "@twick/cli": "^0.15.13",
-    "@twick/ui": "^0.15.13",
+    "@twick/cli": "^0.15.15",
+    "@twick/ui": "^0.15.15",
     "typescript": "5.4.2",
     "typedoc": "^0.25.8",
     "typedoc-plugin-markdown": "^3.17.1",

package/src/animations/fade.tsx

@@ -74,10 +74,10 @@ import { AnimationParams } from "../helpers/types";
  *     animation: { name: "fade", animate: "enter", duration: 2 }
  *   },
  *   {
- *     id: "subtitle", 
+ *     id: "caption", 
  *     type: "text",
  *     s: 1, e: 8,
- *     t: "Subtitle",
+ *     t: "Caption",
  *     animation: { name: "fade", animate: "enter", duration: 2 }
  *   },
  *   {

package/src/components/track.tsx

@@ -3,8 +3,8 @@
  * including video, audio, captions, scenes, and elements.
  */
 
-import { Layout, Rect, View2D, Audio } from "@twick/2d";
-import { VisualizerTrack } from "../helpers/types";
+import { Layout, Rect, View2D, Audio, Img, Txt } from "@twick/2d";
+import { VisualizerTrack, WatermarkInput } from "../helpers/types";
 import { all, Color, createRef, ThreadGenerator, waitFor } from "@twick/core";
 import {
   CAPTION_STYLE,
@@ -13,6 +13,7 @@ import {
 } from "../helpers/constants";
 import { logger } from "../helpers/log.utils";
 import elementController from "../controllers/element.controller";
+import watermarkController from "../controllers/watermark.controller";
 import { hexToRGB } from "../helpers/utils";
 
 /**
@@ -218,3 +219,28 @@ export function* makeElementTrack({
   yield* all(...sequence);
   yield elementTrackRef().remove();
 }
+
+/**
+ * Creates a watermark overlay on top of all tracks.
+ * Dispatches to the registered watermark renderer by type (text | image).
+ * Added last to ensure it renders on top of all content.
+ */
+export function* makeWatermarkTrack({
+  view,
+  watermark,
+  duration,
+}: {
+  view: View2D;
+  watermark: WatermarkInput;
+  duration: number;
+}) {
+  if (duration <= 0) return;
+
+  // Add watermark after other tracks have started (ensures it renders on top)
+  yield* waitFor(0.001);
+
+  const renderer = watermarkController.get(watermark.type);
+  if (renderer) {
+    yield* renderer.render({ view, watermark, duration });
+  }
+}

package/src/controllers/element.controller.ts

@@ -1,7 +1,6 @@
 import { AudioElement } from "../elements/audio.element";
 import { CaptionElement } from "../elements/caption.element";
 import { CircleElement } from "../elements/circle.element";
-import { IconElement } from "../elements/icon.element";
 import { ImageElement } from "../elements/image.element";
 import { RectElement } from "../elements/rect.element";
 import { SceneElement } from "../elements/scene.element";
@@ -33,7 +32,6 @@ export class ElementController {
     elementController.register(TextElement);
     elementController.register(AudioElement);
     elementController.register(CircleElement);
-    elementController.register(IconElement);
     elementController.register(RectElement);
   }
 

package/src/controllers/watermark.controller.ts

@@ -0,0 +1,35 @@
+import type { WatermarkRendererContract } from "../helpers/watermark.types";
+import { TextWatermarkRenderer } from "../watermark-renderers/text.watermark";
+import { ImageWatermarkRenderer } from "../watermark-renderers/image.watermark";
+
+/**
+ * Registry for watermark renderers. Enables scalable dispatch by type:
+ * watermarkController.get(watermark.type)?.render({ view, watermark, duration }).
+ * Add new watermark types (e.g. svg) by registering a new renderer.
+ */
+export class WatermarkController {
+  private renderers = new Map<string, WatermarkRendererContract>();
+
+  register(renderer: WatermarkRendererContract) {
+    this.renderers.set(renderer.name, renderer);
+  }
+
+  get(name: string): WatermarkRendererContract | undefined {
+    return this.renderers.get(name);
+  }
+
+  list(): string[] {
+    return Array.from(this.renderers.keys());
+  }
+}
+
+const watermarkController = new WatermarkController();
+
+function registerWatermarkRenderers() {
+  watermarkController.register(TextWatermarkRenderer);
+  watermarkController.register(ImageWatermarkRenderer);
+}
+
+registerWatermarkRenderers();
+
+export default watermarkController;

package/src/elements/index.ts

@@ -10,5 +10,4 @@ export { TextElement } from './text.element';
 export { CaptionElement } from './caption.element';
 export { RectElement } from './rect.element';
 export { CircleElement } from './circle.element';
-export { IconElement } from './icon.element';
 export { SceneElement } from './scene.element';

package/src/elements/text.element.tsx

@@ -1,8 +1,8 @@
 import { ElementParams } from "../helpers/types";
-import { all, createRef, waitFor } from "@twick/core";
-import { Txt } from "@twick/2d";
+import { all, Color, createRef, waitFor } from "@twick/core";
+import { Rect, Txt } from "@twick/2d";
 import { addAnimation, addTextEffect } from "../helpers/element.utils";
-import { logger } from "../helpers/log.utils";
+import { hexToRGB } from "../helpers/utils";
 
 /**
  * @group TextElement
@@ -79,26 +79,85 @@ export const TextElement = {
      * });
      * ```
      */
-    *create({ containerRef, element, view }: ElementParams) { 
+    *create({ containerRef, element, view }: ElementParams) {
     const elementRef = createRef<any>();
+    const hasBackground =
+      element.props?.backgroundColor != null &&
+      element.props.backgroundColor !== "";
 
     yield* waitFor(element?.s);
-    yield containerRef().add(
-      <Txt
-        ref={elementRef}
-        key={element.id}
-        text={element.t}
-        textWrap={element.props?.textWrap ?? true}
-        textAlign={element.props?.textAlign ?? "center"}
-        {...element.props}
-      />
-    );
-    yield* all(
-      addAnimation({ elementRef: elementRef, element: element, view }),
-      addTextEffect({ elementRef: elementRef, element: element }),
-      waitFor(Math.max(0, element.e - element.s))
-    );
-    yield elementRef().remove();
-}
+
+    if (hasBackground) {
+      const textRef = createRef<Txt>();
+      const wrapperRef = createRef<any>();
+      const innerTextRef = createRef<Txt>();
+
+      yield containerRef().add(
+        <Txt
+          ref={textRef}
+          key={`${element.id}-measure`}
+          text={element.t}
+          textWrap={element.props?.textWrap ?? true}
+          textAlign={element.props?.textAlign ?? "center"}
+          opacity={0}
+          {...element.props}
+        />
+      );
+
+      const bgColor = new Color({
+        ...hexToRGB(element.props!.backgroundColor!),
+        a: element.props?.backgroundOpacity ?? 1,
+      });
+      const paddingX = 20;
+      const paddingY = 4;
+
+      yield containerRef().add(
+        <Rect
+          ref={wrapperRef}
+          key={element.id}
+          fill={bgColor}
+          width={textRef().width() + paddingX}
+          height={textRef().height() + paddingY}
+          padding={[0, paddingX / 2]}
+          alignItems={"center"}
+          justifyContent={"center"}
+          layout
+        >
+          <Txt
+            ref={innerTextRef}
+            text={element.t}
+            textWrap={element.props?.textWrap ?? true}
+            textAlign={element.props?.textAlign ?? "center"}
+            {...element.props}
+          />
+        </Rect>
+      );
+      textRef().remove();
+
+      yield* all(
+        addAnimation({ elementRef: wrapperRef, element: element, view }),
+        addTextEffect({ elementRef: innerTextRef, element: element }),
+        waitFor(Math.max(0, element.e - element.s))
+      );
+      yield wrapperRef().remove();
+    } else {
+      yield containerRef().add(
+        <Txt
+          ref={elementRef}
+          key={element.id}
+          text={element.t}
+          textWrap={element.props?.textWrap ?? true}
+          textAlign={element.props?.textAlign ?? "center"}
+          {...element.props}
+        />
+      );
+      yield* all(
+        addAnimation({ elementRef: elementRef, element: element, view }),
+        addTextEffect({ elementRef: elementRef, element: element }),
+        waitFor(Math.max(0, element.e - element.s))
+      );
+      yield elementRef().remove();
+    }
+  },
   }
   

package/src/helpers/types.ts

@@ -1,19 +1,48 @@
 import { View2D } from "@twick/2d";
 import { Reference, ThreadGenerator, Vector2 } from "@twick/core";
 
+/**
+ * Watermark configuration for overlay on video.
+ * Supports text or image watermarks with position, rotation, and opacity.
+ * Compatible with WatermarkJSON from @twick/timeline.
+ */
+export type WatermarkInput = {
+  type: "text" | "image";
+  position?: Position;
+  rotation?: number;
+  opacity?: number;
+  props: {
+    text?: string;
+    fontSize?: number;
+    fontFamily?: string;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    textAlign?: string;
+    fontWeight?: number;
+    lineWidth?: number;
+    fontStyle?: string;
+    src?: string;
+    width?: number;
+    height?: number;
+    objectFit?: ObjectFit;
+  };
+};
+
 /**
  * Main input configuration for video visualization.
- * Contains player settings, background color, dimensions, and track definitions
- * for creating complete video visualizations.
+ * Contains player settings, background color, dimensions, track definitions,
+ * and optional watermark for creating complete video visualizations.
  */
 export type VideoInput = {
-  playerId: string,
+  playerId: string;
   backgroundColor: string;
   properties: {
     width: number;
     height: number;
   };
   tracks: VisualizerTrack[];
+  watermark?: WatermarkInput;
 };
 
 /**

package/src/helpers/watermark.types.ts

@@ -0,0 +1,23 @@
+import { View2D } from "@twick/2d";
+import { ThreadGenerator } from "@twick/core";
+import { WatermarkInput } from "./types";
+
+/**
+ * Parameters passed to a watermark renderer.
+ */
+export type WatermarkRendererParams = {
+  view: View2D;
+  watermark: WatermarkInput;
+  duration: number;
+};
+
+/**
+ * Interface for watermark renderers. Register with WatermarkController
+ * to support text, image, or future watermark types (e.g. svg).
+ */
+export interface WatermarkRendererContract {
+  /** Renderer type: "text" | "image" */
+  name: "text" | "image";
+  /** Renders the watermark overlay for the given duration */
+  render(params: WatermarkRendererParams): ThreadGenerator;
+}

package/src/index.ts

@@ -194,3 +194,8 @@ export * from './elements';
 export * from './text-effects';
 export * from './frame-effects';
 
+// Watermark renderer registry (Option B – register custom watermark types)
+export { default as watermarkController } from './controllers/watermark.controller';
+export { WatermarkController } from './controllers/watermark.controller';
+export type { WatermarkRendererContract, WatermarkRendererParams } from './helpers/watermark.types';
+

package/src/sample.ts

@@ -26,6 +26,18 @@ export const sample = {
         "orgId": "a251d9971a55"
       },
       "basePath": "carlyn",
+      "watermark": {
+        "id": "e-watermark",
+        "type": "text",
+        "position": { "x": 0, "y": -200 },
+        "opacity": 0.7,
+        "props": {
+          "text": "© Twick SDK",
+          "fontSize": 24,
+          "fontFamily": "Arial",
+          "fill": "#ffffff"
+      }
+    },
       "tracks": [
         {
           "id": "t-scene",

package/src/visualizer-grouped.ts

@@ -55,7 +55,6 @@ export { CaptionElement } from './elements/caption.element';
 // Shape and UI elements
 export { RectElement } from './elements/rect.element';
 export { CircleElement } from './elements/circle.element';
-export { IconElement } from './elements/icon.element';
 
 // Special elements
 export { SceneElement } from './elements/scene.element';

package/src/visualizer.tsx

@@ -57,6 +57,7 @@ import {
   makeElementTrack,
   makeSceneTrack,
   makeVideoTrack,
+  makeWatermarkTrack,
 } from "./components/track";
 import { dispatchWindowEvent } from "./helpers/event.utils";
 
@@ -133,7 +134,7 @@ export const scene = makeScene2D("scene", function* (view: View2D) {
       const movie = [];
       let index = 1;
 
-      // Iterate through each track element and create appropriate visualization
+      // Iterate through each track. Z-order is determined by track order (first track = back, last = front).
       for (const track of input.tracks) {
         switch (track.type) {
           case TRACK_TYPES.VIDEO:
@@ -159,6 +160,25 @@ export const scene = makeScene2D("scene", function* (view: View2D) {
         }
         index++;
       }
+
+      // Add watermark on top of all tracks when present
+      if (input.watermark) {
+        const duration =
+          input.tracks?.length > 0
+            ? Math.max(
+                0,
+                ...input.tracks.flatMap((t) => t.elements || []).map((e) => e.e)
+              )
+            : 10;
+        movie.push(
+          makeWatermarkTrack({
+            view,
+            watermark: input.watermark,
+            duration,
+          })
+        );
+      }
+
       // Execute all track animations in parallel
       yield* all(...movie);
       dispatchWindowEvent(EVENT_TYPES.PLAYER_UPDATE, {

package/src/watermark-renderers/image.watermark.tsx

@@ -0,0 +1,37 @@
+/**
+ * Image watermark renderer for the visualizer.
+ * Renders image overlay with position, rotation, opacity, and dimensions.
+ */
+
+import { Img } from "@twick/2d";
+import { createRef, waitFor } from "@twick/core";
+import type { WatermarkRendererContract } from "../helpers/watermark.types";
+
+export const ImageWatermarkRenderer: WatermarkRendererContract = {
+  name: "image",
+
+  *render({ view, watermark, duration }) {
+    const props = watermark.props;
+    if (!props?.src) return;
+
+    const position = watermark.position ?? { x: 0, y: 0 };
+    const rotation = (watermark.rotation ?? 0) * (Math.PI / 180);
+    const opacity = watermark.opacity ?? 1;
+
+    const watermarkRef = createRef<any>();
+    view.add(
+      <Img
+        ref={watermarkRef}
+        src={props.src}
+        x={position.x}
+        y={position.y}
+        width={props.width}
+        height={props.height}
+        rotation={rotation}
+        opacity={opacity}
+      />
+    );
+
+    yield* waitFor(duration);
+  },
+};

package/src/watermark-renderers/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Watermark renderers registry.
+ * Export renderers and shared types for the watermark controller.
+ */
+
+export { TextWatermarkRenderer } from "./text.watermark";
+export { ImageWatermarkRenderer } from "./image.watermark";

package/src/watermark-renderers/text.watermark.tsx

@@ -0,0 +1,43 @@
+/**
+ * Text watermark renderer for the visualizer.
+ * Renders text overlay with position, rotation, opacity, and text styling.
+ */
+
+import { Txt } from "@twick/2d";
+import { createRef, waitFor } from "@twick/core";
+import type { WatermarkRendererContract } from "../helpers/watermark.types";
+
+export const TextWatermarkRenderer: WatermarkRendererContract = {
+  name: "text",
+
+  *render({ view, watermark, duration }) {
+    const props = watermark.props;
+    if (!props?.text) return;
+
+    const position = watermark.position ?? { x: 0, y: 0 };
+    const rotation = (watermark.rotation ?? 0) * (Math.PI / 180);
+    const opacity = watermark.opacity ?? 1;
+
+    const watermarkRef = createRef<any>();
+    view.add(
+      <Txt
+        ref={watermarkRef}
+        text={props.text}
+        x={position.x}
+        y={position.y}
+        rotation={rotation}
+        opacity={opacity}
+        fontSize={props.fontSize ?? 24}
+        fontFamily={props.fontFamily ?? "Arial"}
+        fill={props.fill ?? "#ffffff"}
+        stroke={props.stroke}
+        lineWidth={props.lineWidth ?? props.strokeWidth ?? 0}
+        textAlign={(props.textAlign as any) ?? "center"}
+        fontWeight={props.fontWeight ?? 400}
+        fontStyle={props.fontStyle ?? "normal"}
+      />
+    );
+
+    yield* waitFor(duration);
+  },
+};

package/src/elements/icon.element.tsx

@@ -1,88 +0,0 @@
-import { ElementParams } from "../helpers/types";
-import { all, createRef, waitFor } from "@twick/core";
-import { Icon } from "@twick/2d";
-import { addAnimation } from "../helpers/element.utils";
-
-/**
- * @group IconElement
- * IconElement creates and manages icon elements in the visualizer scene.
- * Handles icon rendering, styling, and animations for UI elements and
- * visual design components.
- *
- * Features:
- * - Icon rendering with custom styling
- * - Size and position control
- * - Color and opacity customization
- * - Animation support
- *
- * @param containerRef - Reference to the container element
- * @param element - Icon element configuration and properties
- * @param view - The main scene view for rendering
- * 
- * @example
- * ```js
- * // Basic icon element
- * {
- *   id: "play-icon",
- *   type: "icon",
- *   s: 0,
- *   e: 20,
- *   props: {
- *     icon: "play",
- *     size: 64,
- *     fill: "#ffffff"
- *   }
- * }
- * 
- * // Icon with animation
- * {
- *   id: "animated-icon",
- *   type: "icon",
- *   s: 2,
- *   e: 15,
- *   props: {
- *     icon: "pause",
- *     size: 48,
- *     fill: "#ff0000",
- *     opacity: 0.8
- *   },
- *   animation: {
- *     name: "fade",
- *     animate: "enter",
- *     duration: 2
- *   }
- * }
- * ```
- */
-export const IconElement = {
-    name: "icon",
-
-    /**
-     * Generator function that creates and manages icon elements in the scene.
-     * Handles icon creation, styling, and cleanup.
-     *
-     * @param params - Element parameters including container reference, element config, and view
-     * @returns Generator that controls the icon element lifecycle
-     * 
-     * @example
-     * ```js
-     * yield* IconElement.create({
-     *   containerRef: mainContainer,
-     *   element: iconConfig,
-     *   view: sceneView
-     * });
-     * ```
-     */
-    *create({ containerRef, element, view }: ElementParams) {
-    const elementRef = createRef<any>();
-    yield* waitFor(element?.s);
-    yield containerRef().add(
-      <Icon ref={elementRef} key={element.id} {...element.props} />
-    );
-    yield* all(
-      addAnimation({ elementRef: elementRef, element: element, view }),
-      waitFor(Math.max(0, element.e - element.s))
-    );
-    yield elementRef().remove();
-  },
-};