@coxwave/tap-kit-types 2.0.4 → 2.0.7

package/dist/index.d.ts

@@ -2,10 +2,10 @@ import * as CSS from 'csstype';
 import { ReactNode, CSSProperties } from 'react';
 
 /**
- * Alarm display duration (18 seconds total)
- * 말풍선 발생 후, 12초 뒤에 서서히 사라짐 (전체 시간 18초)
+ * Alarm display duration (16 seconds total)
+ * 12초 유지 + 4초 fade out = 16초 total
  */
-declare const ALARM_DURATION = 18000;
+declare const ALARM_DURATION = 16000;
 /**
  * Base style type for all elements
  * Uses csstype for accurate CSS property types
@@ -85,15 +85,101 @@ type AlarmType = "basic:welcome" | "basic:default" | "feat:quiz" | "feat:guide"
  * Complete alarm message definition
  * UI is fully defined via JSON Component Descriptor
  * Click behavior is simple: open chat + send message (if provided in content.payload)
- * Duration is always 18 seconds (handled in useAlarmEffects)
+ * Duration is always 16 seconds (12s visible + 4s fade, handled in useAlarmEffects)
  */
 interface AlarmMessageInstanceType {
     type: AlarmType;
     content: AlarmElement;
 }
 
-type TapMessageType = "tap:ready" | "tap:close" | "timeline:seek" | "alarm:click" | "alarm:fadeIn" | "popUp:open" | "popUp:close" | "material:view:open" | "material:view:close" | "material:view:error" | "container:mode:change" | "container:mode:change:ack" | "container:layout:state:changed" | "viewport:resize" | "config:update" | "GA_EVENT";
-type TapMessage = TapReadyMessage | TapCloseMessage | TimelineSeekMessage | AlarmClickMessage | AlarmFadeInMessage | PopUpOpenMessage | PopUpCloseMessage | MaterialViewOpenMessage | MaterialViewCloseMessage | MaterialViewErrorMessage | ContainerModeChangeMessage | ContainerModeChangeAckMessage | ContainerLayoutStateChangedMessage | ViewportResizeMessage | ConfigUpdateMessage | GAEventMessage;
+/**
+ * Styling Types
+ */
+/**
+ * Display mode for TapKit container (user-facing configuration)
+ *
+ * - "inline": Embedded at element position
+ * - "floating": Compact widget floating in document.body
+ * - "sidebar": Full-height sidebar in document.body
+ */
+type DisplayMode = "inline" | "floating" | "sidebar";
+/**
+ * Layout mode for runtime layout switching
+ *
+ * Excludes "inline" because inline mode doesn't participate in layout toggling.
+ * Used by ContainerStateStore, localStorage persistence, and layout manager.
+ */
+type LayoutMode = "floating" | "sidebar";
+type PositionType = {
+    top?: string;
+    left?: string;
+    right?: string;
+    bottom?: string;
+};
+/**
+ * Floating mode configuration
+ * Includes position, size, and style settings for floating container
+ */
+type FloatingConfig = {
+    /** Position (default: top: "50px", right: "24px") */
+    position?: PositionType;
+    /** Width (default: "340px") */
+    width?: string;
+    /** Height (default: "calc(100% - 116px)") */
+    height?: string;
+    /** Border radius (default: "16px") */
+    borderRadius?: string;
+    /** Expanded width for PDF viewer (default: "min(90vw, 1200px)") */
+    expandedWidth?: string;
+    /** Expanded height for PDF viewer (default: "90vh") */
+    expandedHeight?: string;
+    /** Expanded top position for PDF viewer (default: "5vh") */
+    expandedTop?: string;
+    /** Expanded right position for PDF viewer (default: "5vw") */
+    expandedRight?: string;
+};
+/**
+ * Sidebar Configuration
+ */
+type SidebarConfig = {
+    /** Maximum width of the sidebar (default: "min(50%, 1000px)") */
+    maxWidth?: string;
+    /** Expanded maximum width for PDF viewer (default: "min(70%, 1400px)") */
+    expandedMaxWidth?: string;
+    /** Minimum viewport width to enable sidebar mode (default: 768) */
+    minViewportWidth?: number;
+};
+/**
+ * Container Configuration (SSOT - Type Level)
+ *
+ * This is the SINGLE SOURCE OF TRUTH for container configuration at the TYPE level.
+ * - Public API: TapKitInitParams.container
+ * - Internal: Container class configuration
+ * - Protocol: ConfigUpdateMessage.container mirrors this structure
+ *
+ * When modifying this type, also update ConfigUpdateMessage.container in @coxwave/tap-messages
+ *
+ * @example
+ * // Custom styling for floating/sidebar modes
+ * const config: ContainerConfig = {
+ *   floatingConfig: { width: "400px", position: { top: "80px" } },
+ *   sidebarConfig: { maxWidth: "800px" }
+ * }
+ */
+type ContainerConfig = {
+    /**
+     * Display mode
+     * @see DisplayMode
+     */
+    mode?: DisplayMode;
+    /** Floating layout configuration (applied when SDK auto-creates container in floating layout) */
+    floatingConfig?: FloatingConfig;
+    /** Sidebar layout configuration (applied when SDK auto-creates container in sidebar layout) */
+    sidebarConfig?: SidebarConfig;
+};
+
+type TapMessageType = "tap:ready" | "tap:close" | "timeline:seek" | "alarm:click" | "alarm:fadeIn" | "popUp:open" | "popUp:close" | "material:view:open" | "material:view:close" | "material:view:error" | "html:view:open" | "html:view:close" | "container:mode:change" | "container:mode:change:ack" | "container:layout:state:changed" | "viewport:resize" | "config:update" | "GA_EVENT";
+type TapMessage = TapReadyMessage | TapCloseMessage | TimelineSeekMessage | AlarmClickMessage | AlarmFadeInMessage | PopUpOpenMessage | PopUpCloseMessage | MaterialViewOpenMessage | MaterialViewCloseMessage | MaterialViewErrorMessage | HtmlViewOpenMessage | HtmlViewCloseMessage | ContainerModeChangeMessage | ContainerModeChangeAckMessage | ContainerLayoutStateChangedMessage | ViewportResizeMessage | ConfigUpdateMessage | GAEventMessage;
 interface TapReadyMessage {
     type: "tap:ready";
     gaId: string;
@@ -155,6 +241,30 @@ interface MaterialViewErrorMessage {
     error: "fetch_failed" | "expired_url" | "extraction_failed" | "unknown";
     message?: string;
 }
+/**
+ * HTML View Open Request (iframe → parent, simple post pattern)
+ * Requests parent to open HTML viewer overlay
+ *
+ * Supports two content sources:
+ * - htmlUrl: Load HTML from URL (iframe src)
+ * - htmlContent: Render HTML string directly (iframe srcdoc)
+ */
+interface HtmlViewOpenMessage {
+    type: "html:view:open";
+    /** URL to load HTML content from */
+    htmlUrl?: string;
+    /** HTML string to render directly */
+    htmlContent?: string;
+    /** Optional title for the viewer header */
+    title?: string;
+}
+/**
+ * HTML View Close Request (iframe → parent, simple post pattern)
+ * Requests parent to close HTML viewer overlay
+ */
+interface HtmlViewCloseMessage {
+    type: "html:view:close";
+}
 /**
  * Container Mode Change Request (iframe → parent, call/handle pattern)
  *
@@ -226,14 +336,7 @@ interface ConfigUpdateMessage {
     courseId?: string;
     clipId?: string;
     clipPlayHead?: number;
-    /**
-     * Display mode
-     * - "inline": Container rendered at <tap-kit> position (embedded in page)
-     * - "floating": Container floats in document.body as compact widget
-     * - "sidebar": Container floats in document.body as full-height sidebar
-     * Default: "inline"
-     */
-    mode?: "inline" | "floating" | "sidebar";
+    mode?: DisplayMode;
     /**
      * Allow user to toggle between floating and sidebar layouts
      * @default true
@@ -2038,6 +2141,15 @@ declare const MaterialViewErrorSchema: ObjectSchema<{
     readonly error: UnionSchema<[LiteralSchema<"fetch_failed", undefined>, LiteralSchema<"expired_url", undefined>, LiteralSchema<"extraction_failed", undefined>, LiteralSchema<"unknown", undefined>], undefined>;
     readonly message: OptionalSchema<StringSchema<undefined>, undefined>;
 }, undefined>;
+declare const HtmlViewOpenSchema: ObjectSchema<{
+    readonly type: LiteralSchema<"html:view:open", undefined>;
+    readonly htmlUrl: OptionalSchema<StringSchema<undefined>, undefined>;
+    readonly htmlContent: OptionalSchema<StringSchema<undefined>, undefined>;
+    readonly title: OptionalSchema<StringSchema<undefined>, undefined>;
+}, undefined>;
+declare const HtmlViewCloseSchema: ObjectSchema<{
+    readonly type: LiteralSchema<"html:view:close", undefined>;
+}, undefined>;
 declare const ContainerModeChangeSchema: ObjectSchema<{
     readonly type: LiteralSchema<"container:mode:change", undefined>;
     readonly mode: UnionSchema<[LiteralSchema<"floating", undefined>, LiteralSchema<"sidebar", undefined>], undefined>;
@@ -2137,6 +2249,13 @@ declare const TapMessageSchema: UnionSchema<[ObjectSchema<{
     readonly materialId: StringSchema<undefined>;
     readonly error: UnionSchema<[LiteralSchema<"fetch_failed", undefined>, LiteralSchema<"expired_url", undefined>, LiteralSchema<"extraction_failed", undefined>, LiteralSchema<"unknown", undefined>], undefined>;
     readonly message: OptionalSchema<StringSchema<undefined>, undefined>;
+}, undefined>, ObjectSchema<{
+    readonly type: LiteralSchema<"html:view:open", undefined>;
+    readonly htmlUrl: OptionalSchema<StringSchema<undefined>, undefined>;
+    readonly htmlContent: OptionalSchema<StringSchema<undefined>, undefined>;
+    readonly title: OptionalSchema<StringSchema<undefined>, undefined>;
+}, undefined>, ObjectSchema<{
+    readonly type: LiteralSchema<"html:view:close", undefined>;
 }, undefined>, ObjectSchema<{
     readonly type: LiteralSchema<"container:mode:change", undefined>;
     readonly mode: UnionSchema<[LiteralSchema<"floating", undefined>, LiteralSchema<"sidebar", undefined>], undefined>;
@@ -2209,23 +2328,49 @@ type TapKitConfig = {
     apiKey: string;
 };
 /**
- * Runtime configuration sent to iframe via config:update message
- * Derived from ConfigUpdateMessage protocol (without 'type' field)
- * This ensures type consistency between iframe messages and config
+ * =============================================================================
+ * SSOT (Single Source of Truth) Type Hierarchy
+ * =============================================================================
+ *
+ * All configuration types derive from ConfigUpdateMessage:
+ *
+ * ConfigUpdateMessage (SSOT - protocol/messages.ts)
+ *     ↓ Omit<..., "type">
+ * ConfigUpdatePayload (모든 config 필드)
+ *     ↓ Partial<...>
+ * ConfigUpdateOptions (런타임 업데이트용, 모든 필드 optional)
+ *     ↓ Exclude<keyof ..., ...>
+ * SyncableConfigKey (iframe 동기화 대상 키들)
+ *
+ * Benefits:
+ * - 새 필드 추가 시 ConfigUpdateMessage만 수정
+ * - 다른 위치에서 컴파일 에러 발생으로 누락 방지
+ * =============================================================================
  */
-type TapKitRuntimeConfig = Omit<ConfigUpdateMessage, "type">;
 /**
- * All SDK Configuration Options (Internal API)
- * Derived from ConfigUpdateMessage protocol for type consistency
- * Used by Symbol-based config() method for advanced configuration
- *
- * Note: All fields (tapUrl, environment, etc.) are now part of TapKitRuntimeConfig
- * which is based on ConfigUpdateMessage. This ensures consistency between
- * SDK configuration and iframe message protocol.
+ * config:update 메시지의 payload (type 필드 제외)
+ * 모든 config 관련 타입의 기반
+ */
+type ConfigUpdatePayload = Omit<ConfigUpdateMessage, "type">;
+/**
+ * 런타임 업데이트 가능한 config 키
+ */
+type ConfigUpdateKey = keyof ConfigUpdatePayload;
+/**
+ * 런타임 config 업데이트용 (모든 필드 optional)
+ * updateConfig() 메서드에서 사용
+ */
+type ConfigUpdateOptions = Partial<ConfigUpdatePayload>;
+/**
+ * iframe 동기화 대상 키 (초기화 전용 키 제외)
+ * CONFIG_KEYS 배열의 타입 제약으로 사용
  *
- * @internal This is not part of the public API
+ * 제외 항목:
+ * - apiKey: 초기화 시에만 설정
+ * - hostOrigin: 자동 감지
+ * - tapUrl: 초기화 시에만 설정
  */
-type TapKitConfigOptions = TapKitRuntimeConfig;
+type SyncableConfigKey = Exclude<ConfigUpdateKey, "apiKey" | "hostOrigin" | "tapUrl">;
 /**
  * Course Information
  */
@@ -2481,16 +2626,19 @@ interface VideoPlayerAdapter {
  *
  * @example
  * ```typescript
- * // HTML5 Video
+ * // HTML5 Video (recommended - clipId auto-tracked)
  * const videoElement = document.querySelector('video');
- * sdk.video.bind(videoElement, 'clip-123');
+ * sdk.video.bind(videoElement);  // clipId from SDK config, auto-updates with setCourse()
  *
  * // Custom Adapter
  * const adapter = {
  *   getCurrentTime: () => player.currentTime,
  *   setCurrentTime: (time) => { player.currentTime = time; }
  * };
- * sdk.video.bind(adapter, 'clip-123');
+ * sdk.video.bind(adapter);
+ *
+ * // Manual clipId (for special cases)
+ * sdk.video.bind(videoElement, 'specific-clip-id');
  * ```
  */
 type VideoPlayerConfig = HTMLVideoElement | VideoPlayerAdapter;
@@ -2508,8 +2656,13 @@ interface TapKitInstance {
         onAlarmFadeIn: (handler: (messageInfo: AlarmMessageInstanceType) => void) => () => void;
     };
     video: {
-        /** Bind video player for timeline synchronization */
-        bind: (config: VideoPlayerConfig, clipId: string) => void;
+        /**
+         * Bind video player for timeline synchronization
+         *
+         * @param config - HTMLVideoElement or VideoPlayerAdapter
+         * @param clipId - Optional clipId. If not provided, uses SDK config (auto-tracks changes from setCourse)
+         */
+        bind: (config: VideoPlayerConfig, clipId?: string) => void;
         /** Unbind current video player */
         unbind: () => void;
     };
@@ -2523,87 +2676,17 @@ interface TapKitInstance {
     /** Hide chat container */
     hide(): void;
     /**
-     * Internal config update method (soft-private, discouraged)
-     *
-     * Accepts any config key-value pairs for advanced configuration.
-     * Type is intentionally generic to hide implementation details.
-     *
-     * @deprecated Use public APIs instead. This is kept for backward compatibility.
-     * Prefer using Symbol API via Symbol.for("tapkit.config") for advanced config.
-     *
-     * @internal Soft-private method (starts with _)
+     * Update course information
+     * @param course - Course info (courseId and clipId required, userId and clipPlayHead optional)
      */
-    _updateConfig?(options: Record<string, unknown>): void;
+    setCourse(course: Partial<Course> & {
+        courseId: string;
+        clipId: string;
+    }): void;
 }
 /** TapKit constructor type */
 type TapKitConstructor = new (config: TapKitConfig) => TapKitInstance;
 
-/**
- * Styling Types
- */
-type PositionType = {
-    top?: string;
-    left?: string;
-    right?: string;
-    bottom?: string;
-};
-/**
- * Floating mode configuration
- * Includes position, size, and style settings for floating container
- */
-type FloatingConfig = {
-    /** Position (default: top: "50px", right: "24px") */
-    position?: PositionType;
-    /** Width (default: "340px") */
-    width?: string;
-    /** Height (default: "calc(100% - 116px)") */
-    height?: string;
-    /** Border radius (default: "16px") */
-    borderRadius?: string;
-    /** Expanded width for PDF viewer (default: "min(90vw, 1200px)") */
-    expandedWidth?: string;
-    /** Expanded height for PDF viewer (default: "90vh") */
-    expandedHeight?: string;
-    /** Expanded top position for PDF viewer (default: "5vh") */
-    expandedTop?: string;
-    /** Expanded right position for PDF viewer (default: "5vw") */
-    expandedRight?: string;
-};
-/**
- * Sidebar Configuration
- */
-type SidebarConfig = {
-    /** Maximum width of the sidebar (default: "min(50%, 1000px)") */
-    maxWidth?: string;
-    /** Expanded maximum width for PDF viewer (default: "min(70%, 1400px)") */
-    expandedMaxWidth?: string;
-    /** Minimum viewport width to enable sidebar mode (default: 768) */
-    minViewportWidth?: number;
-};
-/**
- * Container Configuration (SSOT - Type Level)
- *
- * This is the SINGLE SOURCE OF TRUTH for container configuration at the TYPE level.
- * - Public API: TapKitInitParams.container
- * - Internal: Container class configuration
- * - Protocol: ConfigUpdateMessage.container mirrors this structure
- *
- * When modifying this type, also update ConfigUpdateMessage.container in @coxwave/tap-messages
- *
- * @example
- * // Custom styling for floating/sidebar modes
- * const config: ContainerConfig = {
- *   floatingConfig: { width: "400px", position: { top: "80px" } },
- *   sidebarConfig: { maxWidth: "800px" }
- * }
- */
-type ContainerConfig = {
-    /** Floating layout configuration (applied when SDK auto-creates container in floating layout) */
-    floatingConfig?: FloatingConfig;
-    /** Sidebar layout configuration (applied when SDK auto-creates container in sidebar layout) */
-    sidebarConfig?: SidebarConfig;
-};
-
 /**
  * Type declarations for <tap-button> Web Component
  *
@@ -2904,6 +2987,167 @@ interface TapContainerAttributes {
   onDestroy?: () => void;
 }
 
+/**
+ * Type declarations for <tap-html-viewer> Web Component
+ *
+ * Provides TypeScript support for using <tap-html-viewer> in JSX/TSX.
+ * The actual Web Component is registered by tap-kit-core when loaded.
+ */
+
+
+
+// React 19 requires module augmentation based on tsconfig jsx setting
+// - "jsx": "react-jsx" → augment "react/jsx-runtime"
+// - "jsx": "preserve" → augment "react" (Next.js default)
+
+// For Next.js (jsx: preserve)
+declare module "react" {
+  namespace JSX {
+    interface IntrinsicElements {
+      "tap-html-viewer": TapHtmlViewerAttributes;
+    }
+  }
+}
+
+// For CRA, Vite (jsx: react-jsx)
+declare module "react/jsx-runtime" {
+  namespace JSX {
+    interface IntrinsicElements {
+      "tap-html-viewer": TapHtmlViewerAttributes;
+    }
+  }
+}
+
+/**
+ * Configuration for opening HTML viewer
+ */
+interface HtmlViewConfig {
+  /**
+   * URL to load HTML content from (uses iframe src)
+   */
+  htmlUrl?: string;
+
+  /**
+   * HTML string to render directly (uses iframe srcdoc)
+   */
+  htmlContent?: string;
+
+  /**
+   * Optional title for the viewer header
+   */
+  title?: string;
+}
+
+/**
+ * Public API interface for TapHtmlViewerElement Web Component
+ *
+ * This interface defines the contract that tap-kit-core's TapHtmlViewerElement must implement.
+ * It provides type-safe access to the Web Component's public API.
+ *
+ * The HTML viewer displays HTML content in a sandboxed iframe overlay
+ * positioned relative to a container element.
+ */
+interface ITapHtmlViewerElement extends HTMLElement {
+  /**
+   * Container element reference for positioning
+   * Must be set before calling open()
+   */
+  containerElement: HTMLElement | null;
+
+  /**
+   * Open HTML viewer with configuration
+   *
+   * Displays HTML content in a sandboxed iframe overlay.
+   * Content source: htmlUrl (external) or htmlContent (inline).
+   *
+   * @param config - HTML view configuration
+   * @fires open - When viewer is successfully displayed
+   */
+  open(config: HtmlViewConfig): void;
+
+  /**
+   * Close HTML viewer and cleanup
+   *
+   * Hides overlay and resets state.
+   *
+   * @fires close - When viewer is closed
+   */
+  close(): void;
+
+  /**
+   * Update overlay position relative to container
+   *
+   * Automatically called on container resize/move.
+   * Can be manually triggered if needed.
+   */
+  updatePosition(): void;
+
+  /**
+   * Hide overlay without closing viewer
+   *
+   * Called when container is hidden. Preserves viewer state
+   * so it can be shown again when container becomes visible.
+   */
+  hideOverlay(): void;
+
+  /**
+   * Show overlay (if viewer has content)
+   *
+   * Called when container is shown. Only displays overlay
+   * if viewer has content loaded.
+   */
+  showOverlay(): void;
+
+  /**
+   * Check if viewer is currently visible
+   *
+   * @returns true if visible, false otherwise
+   */
+  readonly isVisible: boolean;
+}
+
+/**
+ * Props/Attributes for <tap-html-viewer> Web Component
+ */
+interface TapHtmlViewerAttributes {
+  /**
+   * Element ID attribute
+   */
+  id?: string;
+
+  /**
+   * CSS class name(s)
+   */
+  className?: string;
+
+  /**
+   * Container element reference for positioning
+   * Required before calling open()
+   */
+  containerElement?: HTMLElement | null;
+
+  /**
+   * Child content (not typically used for tap-html-viewer)
+   * The component automatically creates overlay content
+   */
+  children?: ReactNode;
+
+  /**
+   * Custom inline styles
+   */
+  style?: CSSProperties;
+
+  /**
+   * Event handler for when viewer is successfully displayed
+   */
+  onOpen?: () => void;
+
+  /**
+   * Event handler for when viewer is closed
+   */
+  onClose?: () => void;
+}
+
 /**
  * TapKit Web Component Type Definitions
  *
@@ -2929,7 +3173,22 @@ interface EventManager {
  * VideoController type (matches TapKitInstance.video)
  */
 interface VideoController {
-  bind: (config: VideoPlayerConfig, clipId: string) => void;
+  /**
+   * Bind video player for timeline synchronization
+   *
+   * @param config - HTMLVideoElement or VideoPlayerAdapter
+   * @param clipId - Optional clipId. If not provided, uses SDK config (auto-tracks changes from setCourse)
+   *
+   * @example
+   * ```typescript
+   * // Auto-tracking (recommended) - clipId syncs with setCourse()
+   * kit.video.bind(videoElement);
+   *
+   * // Manual clipId (for special cases)
+   * kit.video.bind(videoElement, 'specific-clip-id');
+   * ```
+   */
+  bind: (config: VideoPlayerConfig, clipId?: string) => void;
   unbind: () => void;
 }
 
@@ -3001,11 +3260,55 @@ interface TapKitElement extends HTMLElement {
   mode?: "inline" | "floating" | "sidebar";
 
   /**
-   * Auto-created flag (internal use only)
-   * Indicates SDK-controlled element (used by legacy TapKit class)
-   * @internal
+   * Allow user to toggle between floating and sidebar layouts
+   * Only applies when mode is "floating" or "sidebar"
+   * @default true
    */
-  autoCreated?: boolean;
+  allowLayoutToggle: boolean;
+
+  /**
+   * Video player target for timeline synchronization (recommended)
+   *
+   * Supports HTMLVideoElement or VideoPlayerAdapter.
+   * Survives lifecycle changes (mode change, reconnect).
+   *
+   * @example
+   * ```typescript
+   * // HTMLVideoElement
+   * kit.videoTarget = document.querySelector('video');
+   *
+   * // VideoPlayerAdapter (YouTube, Vimeo, etc.)
+   * kit.videoTarget = {
+   *   getCurrentTime: () => player.getCurrentTime(),
+   *   setCurrentTime: (t) => player.seekTo(t)
+   * };
+   * ```
+   */
+  videoTarget?: VideoPlayerConfig;
+
+  /**
+   * Root element - tracks the parent element where TapKit is rendered
+   *
+   * **Declarative mode** (`<TapKit />`, `<tap-kit>`):
+   * - Automatically set to `parentElement` on mount
+   * - Read-only after initialization
+   *
+   * **Imperative mode** (`createTapKit()`):
+   * - Set before mount (default: `document.body`)
+   * - Can be changed at runtime
+   *
+   * **Note:** Ignored in inline mode (element stays in declarative position).
+   *
+   * @example
+   * ```typescript
+   * // Imperative: set root before mount
+   * const kit = createTapKit({ apiKey: '...', root: myContainer });
+   *
+   * // Imperative: change root at runtime
+   * kit.root = document.getElementById('another-container');
+   * ```
+   */
+  root?: HTMLElement;
 
   // ===== Public Methods (Imperative API) =====
 
@@ -3159,9 +3462,6 @@ interface TapKitAttributes {
   /** Custom button element ID */
   "button-id"?: string;
 
-  /** Custom container element ID */
-  "container-id"?: string;
-
   /** Enable debug mode */
   debug?: boolean;
 
@@ -3173,6 +3473,12 @@ interface TapKitAttributes {
    */
   mode?: "inline" | "floating" | "sidebar";
 
+  /**
+   * Allow user to toggle between floating and sidebar layouts
+   * Only applies when mode is "floating" or "sidebar"
+   */
+  "allow-layout-toggle"?: boolean;
+
   /** Custom inline styles */
   style?: CSSProperties;
 
@@ -3301,6 +3607,8 @@ interface ITapMaterialViewerElement extends HTMLElement {
    * Downloads PDF from presigned URL, extracts specified pages,
    * and displays in an overlay positioned relative to containerElement.
    *
+   * Note: For HTML content, use TapHtmlViewerElement instead (Separation of Concerns).
+   *
    * @param config - Material view configuration
    * @throws {MaterialViewerError} If PDF fetch or processing fails
    * @fires error - When material loading fails
@@ -3473,4 +3781,4 @@ declare global {
   function cancelIdleCallback(handle: number): void;
 }
 
-export { ALARM_DURATION, type AlarmClickMessage, AlarmClickSchema, type AlarmElement, type AlarmElementProps, AlarmElementPropsSchema, AlarmElementSchema, type AlarmFadeInMessage, AlarmFadeInSchema, AlarmMessageInstanceSchema, type AlarmMessageInstanceType, type AlarmPayload, type AlarmType, type CSSStyle, CSSStyleSchema, type ConfigUpdateMessage, ConfigUpdateSchema, type ContainerConfig, type ContainerLayoutStateChangedMessage, ContainerLayoutStateChangedSchema, type ContainerModeChangeAckMessage, ContainerModeChangeAckSchema, type ContainerModeChangeMessage, ContainerModeChangeSchema, type ContainerVisibility, type Course, type EventManager, type FloatingConfig, type GAEventMessage, GAEventSchema, type ITapButtonElement, type ITapContainerElement, type ITapKitElement, type ITapMaterialViewerElement, TapKitInitializationError as InitializationError, type MaterialViewCloseMessage, MaterialViewCloseSchema, type MaterialViewConfig, type MaterialViewErrorMessage, MaterialViewErrorSchema, type MaterialViewOpenMessage, MaterialViewOpenSchema, MaterialViewerError, type PopUpCloseMessage, PopUpCloseSchema, type PopUpOpenMessage, PopUpOpenSchema, type PositionType, type SeekTimelineParamsType, type ShortcutKeyPropertiesType, type SidebarConfig, TAP_BUTTON_CLICK_EVENT, TAP_ERROR_MARKER, type TapButtonAttributes, type TapButtonClickEventDetail, type TapCloseMessage, TapCloseSchema, type TapContainerAttributes, type TapErrorOptions, type TapKitConfig, type TapKitConfigOptions, TapKitConfigurationError, type TapKitConstructor, type TapKitElement, type TapKitElementEventMap, TapKitError, TapKitIframeError, type TapKitInitParams, TapKitInitializationError, type TapKitInstance, TapKitLoaderError, TapKitMessageError, type TapKitRuntimeConfig, type TapMaterialViewerAttributes, type TapMessage, type TapMessageRecord, TapMessageSchema, type TapMessageType, type TapReadyMessage, TapReadySchema, type TimelineSeekMessage, TimelineSeekSchema, type VideoController, type VideoPlayerAdapter, type VideoPlayerConfig, type ViewportResizeMessage, ViewportResizeSchema };
+export { ALARM_DURATION, type AlarmClickMessage, AlarmClickSchema, type AlarmElement, type AlarmElementProps, AlarmElementPropsSchema, AlarmElementSchema, type AlarmFadeInMessage, AlarmFadeInSchema, AlarmMessageInstanceSchema, type AlarmMessageInstanceType, type AlarmPayload, type AlarmType, type CSSStyle, CSSStyleSchema, type ConfigUpdateKey, type ConfigUpdateMessage, type ConfigUpdateOptions, type ConfigUpdatePayload, ConfigUpdateSchema, type ContainerConfig, type ContainerLayoutStateChangedMessage, ContainerLayoutStateChangedSchema, type ContainerModeChangeAckMessage, ContainerModeChangeAckSchema, type ContainerModeChangeMessage, ContainerModeChangeSchema, type ContainerVisibility, type Course, type DisplayMode, type EventManager, type FloatingConfig, type GAEventMessage, GAEventSchema, type HtmlViewCloseMessage, HtmlViewCloseSchema, type HtmlViewConfig, type HtmlViewOpenMessage, HtmlViewOpenSchema, type ITapButtonElement, type ITapContainerElement, type ITapHtmlViewerElement, type ITapKitElement, type ITapMaterialViewerElement, TapKitInitializationError as InitializationError, type LayoutMode, type MaterialViewCloseMessage, MaterialViewCloseSchema, type MaterialViewConfig, type MaterialViewErrorMessage, MaterialViewErrorSchema, type MaterialViewOpenMessage, MaterialViewOpenSchema, MaterialViewerError, type PopUpCloseMessage, PopUpCloseSchema, type PopUpOpenMessage, PopUpOpenSchema, type PositionType, type SeekTimelineParamsType, type ShortcutKeyPropertiesType, type SidebarConfig, type SyncableConfigKey, TAP_BUTTON_CLICK_EVENT, TAP_ERROR_MARKER, type TapButtonAttributes, type TapButtonClickEventDetail, type TapCloseMessage, TapCloseSchema, type TapContainerAttributes, type TapErrorOptions, type TapHtmlViewerAttributes, type TapKitConfig, TapKitConfigurationError, type TapKitConstructor, type TapKitElement, type TapKitElementEventMap, TapKitError, TapKitIframeError, type TapKitInitParams, TapKitInitializationError, type TapKitInstance, TapKitLoaderError, TapKitMessageError, type TapMaterialViewerAttributes, type TapMessage, type TapMessageRecord, TapMessageSchema, type TapMessageType, type TapReadyMessage, TapReadySchema, type TimelineSeekMessage, TimelineSeekSchema, type VideoController, type VideoPlayerAdapter, type VideoPlayerConfig, type ViewportResizeMessage, ViewportResizeSchema };