@jackuait/blok 0.10.0-beta.9 → 0.10.1

package/src/components/modules/uiControllers/controllers/blockHover.ts

@@ -34,6 +34,13 @@ export class BlockHoverController extends Controller {
    */
   private static readonly HOVER_COOLDOWN_MS = 50;
 
+  /**
+   * Maximum horizontal distance from content edges for extended hover zone.
+   * When cursor is within this distance of the content area, nearest-block
+   * detection activates. Beyond this distance, no hover event is emitted.
+   */
+  private static readonly HOVER_ZONE_SIZE = 100;
+
   constructor(options: {
     config: Controller['config'];
     eventsDispatcher: Controller['eventsDispatcher'];
@@ -104,9 +111,10 @@ export class BlockHoverController extends Controller {
 
       /**
        * If no block element found directly, find the nearest block by Y distance
+       * but only if the cursor is within the extended hover zone (100px from content edges).
        */
       if (!hoveredBlockElement) {
-        this.emitNearestBlockHovered(event.clientY);
+        this.emitNearestBlockHoveredInZone(event.clientX, event.clientY);
 
         return;
       }
@@ -169,6 +177,41 @@ export class BlockHoverController extends Controller {
     });
   }
 
+  /**
+   * Emits a BlockHovered event for the nearest block, but only if the cursor
+   * is within the extended hover zone (HOVER_ZONE_SIZE px from content edges).
+   * @param clientX - Cursor X position
+   * @param clientY - Cursor Y position
+   */
+  private emitNearestBlockHoveredInZone(clientX: number, clientY: number): void {
+    const blocks = this.Blok.BlockManager.blocks;
+    const topLevelBlocks = blocks.filter(block =>
+      block.holder.closest('[data-blok-table-cell-blocks], [data-blok-toggle-children]') === null
+    );
+
+    if (topLevelBlocks.length === 0) {
+      return;
+    }
+
+    const contentEl = topLevelBlocks[0].holder.querySelector<HTMLElement>('[data-blok-element-content]');
+
+    if (!contentEl) {
+      this.emitNearestBlockHovered(clientY);
+
+      return;
+    }
+
+    const contentRect = contentEl.getBoundingClientRect();
+    const distLeft = Math.abs(clientX - contentRect.left);
+    const distRight = Math.abs(clientX - contentRect.right);
+    const withinZone = distLeft <= BlockHoverController.HOVER_ZONE_SIZE
+      || distRight <= BlockHoverController.HOVER_ZONE_SIZE;
+
+    if (withinZone) {
+      this.emitNearestBlockHovered(clientY);
+    }
+  }
+
   /**
    * Finds the nearest block by vertical distance to cursor position.
    * Returns the block whose vertical center is closest to the cursor Y position.

package/src/components/tools/block.ts

@@ -69,6 +69,16 @@ export class BlockToolAdapter extends BaseToolAdapter<ToolType.Block, IBlockTool
     return (this.constructable as BlockToolConstructable)[InternalBlockToolSettings.IsReadOnlySupported] === true;
   }
 
+  /**
+   * Returns true if the Tool's prototype has a setReadOnly method,
+   * enabling the in-place read-only toggle path (no save/clear/render cycle).
+   */
+  public get supportsInPlaceReadOnly(): boolean {
+    const prototype = (this.constructable as unknown as { prototype?: { setReadOnly?: unknown } })?.prototype;
+
+    return typeof prototype?.setReadOnly === 'function';
+  }
+
   /**
    * Returns true if Tool supports linebreaks
    */

package/src/components/utils/placeholder.ts

@@ -132,11 +132,18 @@ export const setupPlaceholder = (
   element: HTMLElement,
   placeholder?: string,
   attributeName: 'data-placeholder' | 'data-blok-placeholder-active' = 'data-placeholder'
-): void => {
+): (() => void) => {
   // Always set the attribute, even if empty (for consistency and testing)
   element.setAttribute(attributeName, placeholder ?? '');
 
-  element.addEventListener('focus', () => handleEmptyElement(element));
+  const handler = (): void => handleEmptyElement(element);
+
+  element.addEventListener('focus', handler);
+
+  return () => {
+    element.removeEventListener('focus', handler);
+    element.removeAttribute(attributeName);
+  };
 };
 
 /**

package/src/components/utils/popover/components/popover-item/popover-item-default/popover-item-default.ts

@@ -281,6 +281,17 @@ export class PopoverItemDefault extends PopoverItem {
       this.nodes.secondaryLabelEl = secondaryEl;
     }
 
+    // Trailing icon (right-side indicator, e.g. checkmark)
+    if (params.trailingIcon) {
+      const trailingEl = document.createElement('div');
+
+      trailingEl.className = 'ml-auto shrink-0 flex items-center justify-center [&_svg]:w-icon [&_svg]:h-icon';
+      trailingEl.setAttribute('data-blok-testid', 'popover-item-trailing-icon');
+      trailingEl.innerHTML = params.trailingIcon;
+
+      root.appendChild(trailingEl);
+    }
+
     // Chevron
     const showChevron = this.hasChildren && !this.isChevronHidden;
 

package/src/components/utils/popover/popover-abstract.ts

@@ -102,6 +102,13 @@ export abstract class PopoverAbstract<Nodes extends PopoverNodes = PopoverNodes>
     return this.nodes.popover;
   }
 
+  /**
+   * Whether the popover is currently shown
+   */
+  public get isShown(): boolean {
+    return this.nodes.popover.hasAttribute(DATA_ATTR.popoverOpened);
+  }
+
   /**
    * Open popover
    */

package/src/styles/main.css

@@ -644,6 +644,10 @@
   --color-swatch-ring-hover: var(--blok-swatch-ring-hover);
   --color-swatch-ring-active: var(--blok-swatch-ring-active);
 
+  /* Surface tokens (code blocks, secondary containers) */
+  --color-bg-secondary: var(--blok-bg-secondary);
+  --color-border-secondary: var(--blok-border-secondary);
+
 }
 
 @layer utilities {
@@ -725,6 +729,10 @@
   --blok-swatch-ring-hover: rgba(0, 0, 0, 0.10);
   --blok-swatch-ring-active: rgba(0, 0, 0, 0.30);
 
+  /* Surface tokens (code blocks, secondary containers) */
+  --blok-bg-secondary: #f7f8fa;
+  --blok-border-secondary: rgba(55, 53, 47, 0.09);
+
   /* Marker colors — light theme */
   --blok-color-gray-text: #787774;
   --blok-color-gray-bg: #f1f1ef;
@@ -818,6 +826,10 @@
     --blok-swatch-ring-hover: rgba(255, 255, 255, 0.15);
     --blok-swatch-ring-active: rgba(255, 255, 255, 0.35);
 
+    /* Surface tokens (code blocks, secondary containers) */
+    --blok-bg-secondary: rgba(255, 255, 255, 0.04);
+    --blok-border-secondary: rgba(255, 255, 255, 0.08);
+
     /* Marker colors — dark theme */
     --blok-color-gray-text: #9b9b9b;
     --blok-color-gray-bg: #2f2f2f;
@@ -910,6 +922,10 @@
   --blok-swatch-ring-hover: rgba(255, 255, 255, 0.15);
   --blok-swatch-ring-active: rgba(255, 255, 255, 0.35);
 
+  /* Surface tokens (code blocks, secondary containers) */
+  --blok-bg-secondary: rgba(255, 255, 255, 0.04);
+  --blok-border-secondary: rgba(255, 255, 255, 0.08);
+
   /* Marker colors — dark theme */
   --blok-color-gray-text: #9b9b9b;
   --blok-color-gray-bg: #2f2f2f;

package/src/tools/callout/constants.ts

@@ -25,7 +25,8 @@ export const EMOJI_CATEGORY_FLAGS_KEY = 'tools.callout.emojiCategoryFlags';
 export const DEFAULT_EMOJI = '💡';
 
 // CSS — Tailwind classes
-export const WRAPPER_STYLES = 'rounded-xl px-4 py-[5px] my-1 flex items-start gap-2';
+export const WRAPPER_STYLES = 'rounded-xl pl-8 pr-4 py-[5px] my-1 flex items-start gap-2 relative';
 // h-[38px] = py-[7px]×2 + 1.5rem×1 = 14+24; explicit height prevents platform-specific emoji font metrics from inflating the button
 export const EMOJI_BUTTON_STYLES = 'text-[1.5rem] leading-[1] cursor-pointer bg-transparent border-0 px-0 py-[7px] h-[38px] flex-shrink-0 select-none';
 export const CHILDREN_STYLES = 'flex-1 min-w-0';
+export const DRAG_ZONE_STYLES = 'absolute left-0 top-0 h-full cursor-grab select-none';

package/src/tools/callout/dom-builder.ts

@@ -1,16 +1,19 @@
 // src/tools/callout/dom-builder.ts
 
+import { DATA_ATTR } from '../../components/constants/data-attributes';
 import { TOGGLE_ATTR } from '../toggle/constants';
 import {
   WRAPPER_STYLES,
   EMOJI_BUTTON_STYLES,
   CHILDREN_STYLES,
+  DRAG_ZONE_STYLES,
 } from './constants';
 
 export interface CalloutDOMRefs {
   wrapper: HTMLElement;
   emojiButton: HTMLButtonElement;
   childContainer: HTMLElement;
+  dragZone: HTMLElement;
 }
 
 export interface BuildCalloutDOMOptions {
@@ -43,11 +46,20 @@ export function buildCalloutDOM(options: BuildCalloutDOMOptions): CalloutDOMRefs
   const childContainer = document.createElement('div');
   childContainer.className = CHILDREN_STYLES;
   childContainer.setAttribute(TOGGLE_ATTR.toggleChildren, '');
+  childContainer.setAttribute(DATA_ATTR.nestedBlocks, '');
   childContainer.setAttribute('data-blok-child-toolbar', '');
   childContainer.setAttribute('data-blok-mutation-free', 'true');
 
   wrapper.appendChild(emojiButton);
   wrapper.appendChild(childContainer);
 
-  return { wrapper, emojiButton, childContainer };
+  // Drag zone — covers left padding area (x=[0,16px]) for drag handle,
+  // sits behind emoji button so emoji clicks pass through
+  const dragZone = document.createElement('span');
+  dragZone.className = DRAG_ZONE_STYLES;
+  dragZone.style.width = '32px'; // matches pl-8 left padding
+  dragZone.setAttribute('data-callout-drag-zone', '');
+  wrapper.prepend(dragZone);
+
+  return { wrapper, emojiButton, childContainer, dragZone };
 }

package/src/tools/callout/index.ts

@@ -16,6 +16,7 @@ import type { CalloutData, CalloutConfig } from './types';
 import { buildCalloutDOM, type CalloutDOMRefs } from './dom-builder';
 import { saveCallout } from './block-operations';
 import { handleCalloutFirstChildBackspace } from './callout-keyboard';
+import { mountChildBlocks } from '../nested-blocks';
 import { createColorPicker, type ColorPickerHandle } from '../../components/shared/color-picker';
 import { colorVarName } from '../../components/shared/color-presets';
 import { mapToNearestPresetName } from '../../components/utils/color-mapping';
@@ -60,11 +61,12 @@ const VARIANT_TO_BG_PRESET: Record<string, string | null> = {
 
 export class CalloutTool implements BlockTool {
   private readonly api: API;
-  private readonly readOnly: boolean;
+  private readOnly: boolean;
   private _data: CalloutData;
   private _dom: CalloutDOMRefs | null = null;
   private _emojiPicker: EmojiPicker | null = null;
   private _colorPicker: ColorPickerHandle | null = null;
+  private _dragZone: HTMLElement | null = null;
   private blockId?: string;
 
   constructor({ data, api, readOnly, block }: BlockToolConstructorOptions<CalloutData, CalloutConfig>) {
@@ -108,6 +110,10 @@ export class CalloutTool implements BlockTool {
   }
 
   public render(): HTMLElement {
+    if (this._dom) {
+      return this._dom.wrapper;
+    }
+
     const dom = buildCalloutDOM({
       emoji: this._data.emoji,
       readOnly: this.readOnly,
@@ -115,6 +121,7 @@ export class CalloutTool implements BlockTool {
     });
 
     this._dom = dom;
+    this._dragZone = dom.dragZone;
     this.applyColors();
 
     if (!this.readOnly) {
@@ -144,12 +151,7 @@ export class CalloutTool implements BlockTool {
 
     const children = this.api.blocks.getChildren(this.blockId);
 
-    // Append existing children to the container
-    for (const child of children) {
-      if (child.holder.parentElement !== this._dom.childContainer) {
-        this._dom.childContainer.appendChild(child.holder);
-      }
-    }
+    mountChildBlocks(this._dom.childContainer, children);
 
     // Auto-create initial paragraph child when callout has no children
     if (children.length === 0) {
@@ -252,6 +254,18 @@ export class CalloutTool implements BlockTool {
     // No-op — no subscriptions to clean up
   }
 
+  public setReadOnly(state: boolean): void {
+    this.readOnly = state;
+
+    if (this._dom) {
+      this._dom.emojiButton.disabled = state;
+    }
+  }
+
+  public get dragZone(): HTMLElement | null {
+    return this._dragZone;
+  }
+
   private syncPickerActiveColors(): void {
     if (this._colorPicker === null) {
       return;

package/src/tools/code/constants.ts

@@ -5,7 +5,6 @@ export const PLACEHOLDER_KEY = 'tools.code.placeholder';
 export const LANGUAGE_KEY = 'tools.code.language';
 export const COPIED_KEY = 'tools.code.copied';
 export const COPY_CODE_KEY = 'tools.code.copyCode';
-export const WRAP_LINES_KEY = 'tools.code.wrapLines';
 export const SEARCH_LANGUAGE_KEY = 'tools.code.searchLanguage';
 
 // Default values
@@ -53,10 +52,12 @@ export const LANGUAGES: LanguageEntry[] = [
 ];
 
 // CSS — Tailwind classes
-export const WRAPPER_STYLES = 'flex flex-col rounded-lg bg-bg-secondary overflow-hidden my-1';
-export const HEADER_STYLES = 'flex items-center gap-1 px-3 py-1.5 border-b border-border-primary text-xs text-gray-text';
-export const LANGUAGE_BUTTON_STYLES = 'px-1.5 py-0.5 rounded cursor-pointer bg-transparent border-0 text-xs text-gray-text font-medium transition-colors can-hover:hover:bg-item-hover-bg select-none';
+export const WRAPPER_STYLES = 'group/code flex flex-col rounded-xl border border-border-secondary bg-bg-secondary overflow-hidden my-2';
+export const HEADER_STYLES = 'flex items-center gap-1 px-3 py-1.5 text-xs text-gray-text';
+export const LANGUAGE_BUTTON_STYLES = 'inline-flex items-center px-1.5 py-0.5 rounded cursor-pointer bg-transparent border-0 text-xs text-gray-text font-medium transition-colors can-hover:hover:bg-item-hover-bg select-none';
+export const HEADER_CONTROLS_STYLES = 'flex items-center gap-1 opacity-0 group-hover/code:opacity-100 transition-opacity';
 export const HEADER_BUTTON_STYLES = 'p-1 rounded cursor-pointer bg-transparent border-0 text-gray-text transition-colors can-hover:hover:bg-item-hover-bg flex items-center justify-center';
+export const HEADER_BUTTON_MATCHED_STYLES = 'p-1.5 rounded-lg cursor-pointer bg-transparent border-0 text-gray-text transition-colors can-hover:hover:bg-item-hover-bg flex items-center justify-center';
 export const CODE_AREA_STYLES = 'block px-4 py-3 font-mono text-sm leading-relaxed outline-hidden whitespace-pre-wrap overflow-x-auto min-h-[1.5em]';
 export const COPIED_FEEDBACK_STYLES = 'text-xs text-gray-text font-medium select-none';
 
@@ -73,6 +74,28 @@ export const TAB_ACTIVE_STYLES = 'bg-blue-500 text-white';
 export const TAB_INACTIVE_STYLES = 'bg-transparent text-gray-text can-hover:hover:bg-item-hover-bg';
 export const PREVIEW_AREA_STYLES = 'px-4 py-3 overflow-x-auto min-h-[1.5em] flex justify-center';
 
+// i18n key — preview toggle
+export const PREVIEW_TOGGLE_KEY = 'tools.code.previewToggle';
+
+// i18n key — side-by-side view mode
+export const SIDE_BY_SIDE_KEY = 'tools.code.sideBySide';
+
+// View mode type
+export type CodeViewMode = 'code' | 'preview' | 'split';
+
+// CSS — view mode segmented control
+export const VIEW_MODE_CONTAINER_STYLES = 'flex items-center rounded-lg border border-border-secondary p-0.5 gap-0.5';
+export const VIEW_MODE_BUTTON_STYLES = 'p-1 rounded cursor-pointer bg-transparent border-0 text-gray-text transition-colors flex items-center justify-center';
+export const VIEW_MODE_BUTTON_ACTIVE_STYLES = 'p-1 rounded cursor-pointer bg-item-hover-bg border-0 text-primary transition-colors flex items-center justify-center';
+// Preview icon is 16x16 (vs 20x20 for code/split), so extra 2px padding keeps containers equal
+export const VIEW_MODE_PREVIEW_BUTTON_STYLES = 'p-[6px] rounded cursor-pointer bg-transparent border-0 text-gray-text transition-colors flex items-center justify-center';
+export const VIEW_MODE_PREVIEW_BUTTON_ACTIVE_STYLES = 'p-[6px] rounded cursor-pointer bg-item-hover-bg border-0 text-primary transition-colors flex items-center justify-center';
+
+// CSS — split container
+export const SPLIT_CONTAINER_STYLES = 'flex flex-col overflow-hidden';
+export const SPLIT_CONTAINER_SPLIT_STYLES = 'flex flex-row overflow-hidden';
+export const SPLIT_HALF_STYLES = 'flex-1 min-w-0 overflow-hidden';
+
 // Shiki theme names for syntax highlighting
 export const SHIKI_LIGHT_THEME = 'one-light';
 export const SHIKI_DARK_THEME = 'vitesse-dark';
@@ -87,10 +110,7 @@ export const HIGHLIGHTABLE_LANGUAGES = new Set(
     .filter((id) => id !== DEFAULT_LANGUAGE)
 );
 
-// i18n key — line numbers toggle
-export const LINE_NUMBERS_KEY = 'tools.code.lineNumbers';
-
 // CSS — line number gutter
 export const CODE_BODY_STYLES = 'flex overflow-hidden';
-export const GUTTER_STYLES = 'select-none text-right pr-3 py-3 font-mono text-sm leading-relaxed text-gray-text/40 border-r border-border-primary shrink-0';
+export const GUTTER_STYLES = 'select-none text-right pl-4 pr-3 py-3 font-mono text-sm leading-relaxed text-gray-text/40 shrink-0';
 export const GUTTER_LINE_STYLES = 'leading-relaxed';

package/src/tools/code/dom-builder.ts

@@ -2,30 +2,41 @@ import {
   WRAPPER_STYLES,
   HEADER_STYLES,
   LANGUAGE_BUTTON_STYLES,
+  HEADER_CONTROLS_STYLES,
   HEADER_BUTTON_STYLES,
+  HEADER_BUTTON_MATCHED_STYLES,
   CODE_AREA_STYLES,
-  TAB_STYLES,
-  TAB_ACTIVE_STYLES,
-  TAB_INACTIVE_STYLES,
   PREVIEW_AREA_STYLES,
   CODE_BODY_STYLES,
   GUTTER_STYLES,
   GUTTER_LINE_STYLES,
+  VIEW_MODE_CONTAINER_STYLES,
+  VIEW_MODE_BUTTON_STYLES,
+  VIEW_MODE_BUTTON_ACTIVE_STYLES,
+  VIEW_MODE_PREVIEW_BUTTON_STYLES,
+  VIEW_MODE_PREVIEW_BUTTON_ACTIVE_STYLES,
+  SPLIT_CONTAINER_STYLES,
+  SPLIT_HALF_STYLES,
 } from './constants';
-import { IconCopy, IconWrap, IconLineNumbers } from '../../components/icons';
+import type { CodeViewMode } from './constants';
+import { IconCopy, IconCode, IconPreview, IconSplitView, IconChevronDown } from '../../components/icons';
 
 export interface CodeDOMRefs {
   wrapper: HTMLElement;
   languageButton: HTMLButtonElement;
-  lineNumbersButton: HTMLButtonElement;
   copyButton: HTMLButtonElement;
-  wrapButton: HTMLButtonElement;
   preElement: HTMLPreElement;
   codeElement: HTMLElement;
   gutterElement: HTMLElement;
-  codeTab: HTMLButtonElement | null;
-  previewTab: HTMLButtonElement | null;
+  viewModeContainer: HTMLElement | null;
   previewElement: HTMLDivElement | null;
+  splitContainer: HTMLElement | null;
+}
+
+export interface ViewModeLabels {
+  code: string;
+  preview: string;
+  split: string;
 }
 
 export interface BuildCodeDOMOptions {
@@ -33,41 +44,83 @@ export interface BuildCodeDOMOptions {
   languageName: string;
   readOnly: boolean;
   copyLabel: string;
-  wrapLabel: string;
-  lineNumbersLabel?: string;
   previewable?: boolean;
-  codeTabLabel?: string;
-  previewTabLabel?: string;
+  viewModeLabels?: ViewModeLabels;
 }
 
-function buildPreviewElements(
-  codeTabLabel?: string,
-  previewTabLabel?: string,
-): { codeTab: HTMLButtonElement; previewTab: HTMLButtonElement; previewElement: HTMLDivElement } {
-  const codeTab = document.createElement('button');
-
-  codeTab.type = 'button';
-  codeTab.className = `${TAB_STYLES} ${TAB_INACTIVE_STYLES}`;
-  codeTab.textContent = codeTabLabel ?? 'Code';
-  codeTab.setAttribute('data-blok-testid', 'code-code-tab');
-
-  const previewTab = document.createElement('button');
+interface ViewModeElements {
+  viewModeContainer: HTMLElement;
+  previewElement: HTMLDivElement;
+  splitContainer: HTMLElement;
+}
 
-  previewTab.type = 'button';
-  previewTab.className = `${TAB_STYLES} ${TAB_ACTIVE_STYLES}`;
-  previewTab.textContent = previewTabLabel ?? 'Preview';
-  previewTab.setAttribute('data-blok-testid', 'code-preview-tab');
+function buildViewModeElements(
+  labels: ViewModeLabels,
+): ViewModeElements {
+  // Segmented control container
+  const viewModeContainer = document.createElement('div');
+
+  viewModeContainer.className = VIEW_MODE_CONTAINER_STYLES;
+  viewModeContainer.setAttribute('role', 'group');
+  viewModeContainer.setAttribute('data-blok-testid', 'code-view-mode');
+
+  const modes: Array<{ mode: CodeViewMode; icon: string; label: string }> = [
+    { mode: 'code', icon: IconCode, label: labels.code },
+    { mode: 'preview', icon: IconPreview, label: labels.preview },
+    { mode: 'split', icon: IconSplitView, label: labels.split },
+  ];
+
+  for (const { mode, icon, label } of modes) {
+    const button = document.createElement('button');
+    const isPreview = mode === 'preview';
+
+    button.type = 'button';
+    button.className = isPreview ? VIEW_MODE_PREVIEW_BUTTON_STYLES : VIEW_MODE_BUTTON_STYLES;
+    button.innerHTML = icon;
+    button.setAttribute('aria-label', label);
+    button.setAttribute('aria-pressed', 'false');
+    button.setAttribute('data-blok-testid', `code-mode-${mode}`);
+    button.setAttribute('data-mode', mode);
+    viewModeContainer.appendChild(button);
+  }
 
+  // Preview container
   const previewElement = document.createElement('div');
 
   previewElement.className = PREVIEW_AREA_STYLES;
   previewElement.setAttribute('data-blok-testid', 'code-preview');
 
-  return { codeTab, previewTab, previewElement };
+  // Split container — wraps code body + preview
+  const splitContainer = document.createElement('div');
+
+  splitContainer.className = SPLIT_CONTAINER_STYLES;
+  splitContainer.setAttribute('data-blok-testid', 'code-split-container');
+
+  return { viewModeContainer, previewElement, splitContainer };
+}
+
+/**
+ * Set the active view mode button styling and aria-pressed state.
+ */
+export function setActiveViewMode(viewModeContainer: HTMLElement, mode: CodeViewMode): void {
+  const buttons = Array.from(viewModeContainer.querySelectorAll<HTMLButtonElement>('[data-mode]'));
+
+  for (const btn of buttons) {
+    const isActive = btn.getAttribute('data-mode') === mode;
+    const isPreview = btn.getAttribute('data-mode') === 'preview';
+
+    btn.setAttribute('aria-pressed', String(isActive));
+
+    if (isPreview) {
+      btn.className = isActive ? VIEW_MODE_PREVIEW_BUTTON_ACTIVE_STYLES : VIEW_MODE_PREVIEW_BUTTON_STYLES;
+    } else {
+      btn.className = isActive ? VIEW_MODE_BUTTON_ACTIVE_STYLES : VIEW_MODE_BUTTON_STYLES;
+    }
+  }
 }
 
 export function buildCodeDOM(options: BuildCodeDOMOptions): CodeDOMRefs {
-  const { code, languageName, readOnly, copyLabel, wrapLabel, lineNumbersLabel, previewable, codeTabLabel, previewTabLabel } = options;
+  const { code, languageName, readOnly, copyLabel, previewable, viewModeLabels } = options;
 
   // Wrapper
   const wrapper = document.createElement('div');
@@ -77,43 +130,43 @@ export function buildCodeDOM(options: BuildCodeDOMOptions): CodeDOMRefs {
   const header = document.createElement('div');
   header.className = HEADER_STYLES;
 
-  // Language button (opens language picker)
+  // Language button (opens language picker) — includes text + chevron icon
   const languageButton = document.createElement('button');
   languageButton.type = 'button';
   languageButton.className = LANGUAGE_BUTTON_STYLES;
-  languageButton.textContent = languageName;
   languageButton.setAttribute('aria-haspopup', 'listbox');
   languageButton.setAttribute('data-blok-testid', 'code-language-btn');
 
+  const langText = document.createElement('span');
+  langText.textContent = languageName;
+  languageButton.appendChild(langText);
+
+  const chevronSpan = document.createElement('span');
+  chevronSpan.className = 'inline-flex items-center ml-0.5 -mr-0.5';
+  chevronSpan.innerHTML = IconChevronDown;
+  languageButton.appendChild(chevronSpan);
+
   // Spacer
   const spacer = document.createElement('div');
   spacer.className = 'flex-1';
 
-  // Tab buttons (only when previewable)
-  const { codeTab, previewTab, previewElement } = previewable
-    ? buildPreviewElements(codeTabLabel, previewTabLabel)
-    : { codeTab: null, previewTab: null, previewElement: null };
-
-  // Wrap toggle button
-  const wrapButton = document.createElement('button');
-  wrapButton.type = 'button';
-  wrapButton.className = HEADER_BUTTON_STYLES;
-  wrapButton.innerHTML = IconWrap;
-  wrapButton.setAttribute('aria-label', wrapLabel);
-  wrapButton.setAttribute('data-blok-testid', 'code-wrap-btn');
-
-  // Line numbers toggle button
-  const lineNumbersButton = document.createElement('button');
-  lineNumbersButton.type = 'button';
-  lineNumbersButton.className = HEADER_BUTTON_STYLES;
-  lineNumbersButton.innerHTML = IconLineNumbers;
-  lineNumbersButton.setAttribute('aria-label', lineNumbersLabel ?? 'Line numbers');
-  lineNumbersButton.setAttribute('data-blok-testid', 'code-line-numbers-btn');
+  // View mode segmented control — always built in edit mode, hidden for non-previewable languages
+  const viewModeResult = !readOnly && viewModeLabels
+    ? buildViewModeElements(viewModeLabels)
+    : null;
+
+  const viewModeContainer = viewModeResult?.viewModeContainer ?? null;
+  const previewElement = viewModeResult?.previewElement ?? null;
+  const splitContainer = viewModeResult?.splitContainer ?? null;
+
+  if (viewModeContainer) {
+    viewModeContainer.hidden = !previewable;
+  }
 
   // Copy button
   const copyButton = document.createElement('button');
   copyButton.type = 'button';
-  copyButton.className = HEADER_BUTTON_STYLES;
+  copyButton.className = previewable ? HEADER_BUTTON_MATCHED_STYLES : HEADER_BUTTON_STYLES;
   copyButton.innerHTML = IconCopy;
   copyButton.setAttribute('aria-label', copyLabel);
   copyButton.setAttribute('data-blok-testid', 'code-copy-btn');
@@ -146,18 +199,21 @@ export function buildCodeDOM(options: BuildCodeDOMOptions): CodeDOMRefs {
     gutterElement.appendChild(lineEl);
   });
 
-  // Assemble header
+  // Assemble header: [language] [spacer] [controls: view mode? | copy]
   header.appendChild(languageButton);
   header.appendChild(spacer);
 
-  if (codeTab && previewTab) {
-    header.appendChild(codeTab);
-    header.appendChild(previewTab);
+  // Controls container — hidden by default, visible on wrapper hover
+  const controls = document.createElement('div');
+  controls.className = HEADER_CONTROLS_STYLES;
+
+  if (viewModeContainer) {
+    controls.appendChild(viewModeContainer);
   }
 
-  header.appendChild(lineNumbersButton);
-  header.appendChild(wrapButton);
-  header.appendChild(copyButton);
+  controls.appendChild(copyButton);
+
+  header.appendChild(controls);
 
   // Pre wrapper for semantic HTML
   const preElement = document.createElement('pre');
@@ -171,11 +227,24 @@ export function buildCodeDOM(options: BuildCodeDOMOptions): CodeDOMRefs {
 
   // Assemble wrapper
   wrapper.appendChild(header);
-  wrapper.appendChild(codeBody);
 
-  if (previewElement) {
-    wrapper.appendChild(previewElement);
+  if (splitContainer && previewElement) {
+    // Edit mode: always wrap code body + preview in split container.
+    // previewElement is hidden initially; shown when a previewable language is active.
+    const codeHalf = document.createElement('div');
+    codeHalf.className = SPLIT_HALF_STYLES;
+    codeHalf.appendChild(codeBody);
+
+    const previewHalf = document.createElement('div');
+    previewHalf.className = SPLIT_HALF_STYLES;
+    previewHalf.appendChild(previewElement);
+
+    splitContainer.appendChild(codeHalf);
+    splitContainer.appendChild(previewHalf);
+    wrapper.appendChild(splitContainer);
+  } else {
+    wrapper.appendChild(codeBody);
   }
 
-  return { wrapper, languageButton, lineNumbersButton, copyButton, wrapButton, preElement, codeElement, gutterElement, codeTab, previewTab, previewElement };
+  return { wrapper, languageButton, copyButton, preElement, codeElement, gutterElement, viewModeContainer, previewElement, splitContainer };
 }