@blorkfield/blork-tabs 0.3.1 → 0.4.0

package/README.md

@@ -8,6 +8,7 @@ A framework-agnostic tab/panel management system with snapping and docking capab
 - **Anchor Docking** - Dock panels to predefined screen positions
 - **Drag Modes** - Drag entire groups or detach individual panels
 - **Collapse/Expand** - Panels can be collapsed with automatic repositioning
+- **Pin** - Pin panels to prevent dragging and opt out of auto-hide
 - **Auto-Hide** - Panels can hide after inactivity and show on interaction
 - **Event System** - Subscribe to drag, snap, and collapse events
 - **Fully Typed** - Complete TypeScript support
@@ -54,6 +55,7 @@ manager.registerPanel('my-panel', document.getElementById('my-panel'), {
 });
 
 // Position panels and create snap chains
+// positionPanelsFromRight takes IDs right-to-left; createSnapChain takes them left-to-right
 manager.positionPanelsFromRight(['tools', 'settings']);
 manager.createSnapChain(['settings', 'tools']);
 
@@ -99,6 +101,40 @@ const manager = new TabManager({
 });
 ```
 
+## Panel Configuration
+
+Each panel accepts the following options via `addPanel(config)`:
+
+```typescript
+manager.addPanel({
+  id: 'my-panel',           // Required. Unique identifier.
+  title: 'My Panel',        // Header text.
+  width: 300,               // Panel width in px (default: 300).
+  initialPosition: { x: 100, y: 100 },  // Starting position. Auto-placed if omitted.
+  content: '<div>...</div>', // HTML string or HTMLElement for the content area.
+
+  // Collapse
+  startCollapsed: true,     // Whether the panel starts collapsed (default: true).
+  collapsible: true,        // Show collapse button (default: true).
+
+  // Pin
+  pinnable: false,          // Show pin button in header (default: false).
+  startPinned: false,       // Initial pin state (default: false).
+
+  // Drag
+  draggable: true,          // Allow dragging (default: true).
+  detachable: true,         // Show detach grip for single-panel drag (default: true).
+
+  // Auto-hide overrides (see Auto-Hide section)
+  startHidden: false,       // Override global startHidden for this panel.
+  autoHideDelay: undefined, // Override global autoHideDelay (0 = disable auto-hide).
+
+  // Z-index
+  zIndex: 1000,             // Default z-index (default: 1000).
+  dragZIndex: 1002,         // Z-index while dragging (default: 1002).
+});
+```
+
 ## API Reference
 
 ### TabManager
@@ -115,12 +151,23 @@ const manager = new TabManager({
 - `getSnapChain(panelId)` - Get all panels in same chain
 - `snap(leftPanelId, rightPanelId)` - Manually snap two panels
 - `detach(panelId)` - Detach panel from chain
-- `createSnapChain(panelIds)` - Create chain from panel IDs
+- `createSnapChain(panelIds)` - Create chain from panel IDs (left-to-right order)
 - `updatePositions()` - Recalculate snapped positions
 
 #### Positioning
-- `positionPanelsFromRight(panelIds, gap?)` - Position from right edge
-- `positionPanelsFromLeft(panelIds, gap?)` - Position from left edge
+
+`positionPanelsFromRight` and `positionPanelsFromLeft` take panel IDs in **opposite orders**:
+
+- `positionPanelsFromRight(panelIds, gap?)` — first ID is placed at the **right edge**, rest go leftward. Pass IDs **right-to-left**.
+- `positionPanelsFromLeft(panelIds, gap?)` — first ID is placed at the **left edge**, rest go rightward. Pass IDs **left-to-right**.
+
+Because `createSnapChain` uses left-to-right order, you'll typically reverse the array between the two calls:
+
+```typescript
+// Visual order left-to-right: properties, tools, settings
+manager.positionPanelsFromRight(['settings', 'tools', 'properties']); // right-to-left
+manager.createSnapChain(['properties', 'tools', 'settings']);          // left-to-right
+```
 
 #### Anchors
 - `addAnchor(config)` - Add custom anchor
@@ -149,10 +196,54 @@ const manager = new TabManager({
 | `snap:panel` | Panels snapped together |
 | `snap:anchor` | Panels snapped to anchor |
 | `panel:detached` | Panel detached from chain |
+| `panel:pin` | Panel pinned/unpinned |
 | `panel:collapse` | Panel collapsed/expanded |
 | `panel:show` | Panel became visible (auto-hide) |
 | `panel:hide` | Panel became hidden (auto-hide) |
 
+## Drag Modes
+
+Each panel header has two drag zones:
+
+- **Detach grip** (small handle on the left of the header) — drags only that panel. It is detached from its snap chain and moved independently.
+- **Title / header area** — drags the entire connected snap chain as a group.
+
+Set `detachable: false` to hide the grip and make the header always drag the group.
+
+## Pinning
+
+Pinning locks a panel in place and exempts it from auto-hide. Enable the pin button with `pinnable: true`:
+
+```typescript
+manager.addPanel({
+  id: 'hud',
+  title: 'HUD',
+  pinnable: true,
+  startPinned: true,   // start already pinned
+  autoHideDelay: 5000, // pin will override this
+});
+```
+
+### What pinning does
+
+- **Prevents dragging** — a pinned panel cannot be moved, even when dragging its header.
+- **Immune to auto-hide** — a pinned panel is always visible regardless of the `autoHideDelay`. Pinning cancels any pending hide timer and shows the panel if it was hidden. Unpinning restarts the timer.
+- **Splits snap chains on drag** — if a pinned panel sits in the middle of a chain and you drag a neighbour, the chain severs at the pin boundary. Only the panels on the same side as the grabbed panel move; the pinned panel and everything beyond it stay put.
+
+```typescript
+// Chain: A — B — [P pinned] — C — D
+// Grabbing B moves [A, B] and severs the B↔P bond.
+// Grabbing C moves [C, D] and severs the P↔C bond.
+```
+
+### Events
+
+```typescript
+manager.on('panel:pin', ({ panel, isPinned }) => {
+  console.log(`${panel.id} is now ${isPinned ? 'pinned' : 'unpinned'}`);
+});
+```
+
 ## Multi-Section Panel Content
 
 When creating panels with multiple sections (like a command menu with categories), put all sections within a **single `content` string**. Do not use multiple panels or multiple content wrappers—this breaks scrolling and causes content cutoff.
@@ -231,6 +322,10 @@ manager.addPanel({
 | `false` | `3000` | Starts visible, hides after 3s of inactivity |
 | `true` | `3000` | Starts hidden, shows on activity, hides after 3s of inactivity |
 
+### Pin interaction
+
+Pinning a panel overrides auto-hide entirely for that panel — it stays visible regardless of inactivity. Unpinning re-enables the timer. Each panel is tracked independently; pinning one panel in a group has no effect on its neighbours.
+
 ### Events
 
 ```typescript

package/dist/index.cjs

@@ -39,6 +39,7 @@ __export(index_exports, {
   getDefaultZIndex: () => getDefaultZIndex,
   getDragZIndex: () => getDragZIndex,
   getLeftmostPanel: () => getLeftmostPanel,
+  getMovingGroupRespectingPins: () => getMovingGroupRespectingPins,
   getPanelDimensions: () => getPanelDimensions,
   getPanelPosition: () => getPanelPosition,
   getRightmostPanel: () => getRightmostPanel,
@@ -50,6 +51,7 @@ __export(index_exports, {
   snapPanels: () => snapPanels,
   snapPanelsToTarget: () => snapPanelsToTarget,
   toggleCollapse: () => toggleCollapse,
+  togglePin: () => togglePin,
   unsnap: () => unsnap,
   updateSnappedPositions: () => updateSnappedPositions
 });
@@ -199,6 +201,8 @@ function setupHoverEnlarge(config) {
 }
 
 // src/Panel.ts
+var PIN_ICON_UNPINNED = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:block"><line x1="12" y1="17" x2="12" y2="22"/><path d="M5 17H19V16L17 11V4H7L5 11V16Z"/><line x1="5" y1="11" x2="19" y2="11"/></svg>`;
+var PIN_ICON_PINNED = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="14" height="14" fill="currentColor" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:block;transform:rotate(90deg)"><line x1="12" y1="17" x2="12" y2="22"/><path d="M5 17H19V16L17 11V4H7L5 11V16Z"/><line x1="5" y1="11" x2="19" y2="11"/></svg>`;
 function createPanelElement(config, classes) {
   const element = document.createElement("div");
   element.className = classes.panel;
@@ -221,6 +225,14 @@ function createPanelElement(config, classes) {
     title.textContent = config.title;
     header.appendChild(title);
   }
+  let pinButton = null;
+  if (config.pinnable === true) {
+    pinButton = document.createElement("button");
+    pinButton.className = classes.pinButton;
+    pinButton.id = `${config.id}-pin-btn`;
+    pinButton.innerHTML = config.startPinned === true ? PIN_ICON_PINNED : PIN_ICON_UNPINNED;
+    header.appendChild(pinButton);
+  }
   let collapseButton = null;
   if (config.collapsible !== false) {
     collapseButton = document.createElement("button");
@@ -247,6 +259,7 @@ function createPanelElement(config, classes) {
   return {
     element,
     dragHandle: header,
+    pinButton,
     collapseButton,
     contentWrapper,
     detachGrip
@@ -255,12 +268,14 @@ function createPanelElement(config, classes) {
 function createPanelState(config, classes, globalConfig) {
   let element;
   let dragHandle;
+  let pinButton;
   let collapseButton;
   let contentWrapper;
   let detachGrip;
   if (config.element) {
     element = config.element;
     dragHandle = config.dragHandle ?? element.querySelector(`.${classes.panelHeader}`);
+    pinButton = config.pinButton ?? element.querySelector(`.${classes.pinButton}`);
     collapseButton = config.collapseButton ?? element.querySelector(`.${classes.collapseButton}`);
     contentWrapper = config.contentWrapper ?? element.querySelector(`.${classes.panelContent}`);
     detachGrip = config.detachGrip ?? element.querySelector(`.${classes.detachGrip}`);
@@ -268,6 +283,7 @@ function createPanelState(config, classes, globalConfig) {
     const created = createPanelElement(config, classes);
     element = created.element;
     dragHandle = created.dragHandle;
+    pinButton = created.pinButton;
     collapseButton = created.collapseButton;
     contentWrapper = created.contentWrapper;
     detachGrip = created.detachGrip;
@@ -281,9 +297,11 @@ function createPanelState(config, classes, globalConfig) {
     id: config.id,
     element,
     dragHandle,
+    pinButton,
     collapseButton,
     contentWrapper,
     detachGrip,
+    isPinned: config.startPinned === true,
     isCollapsed: config.startCollapsed !== false,
     snappedTo: null,
     snappedFrom: null,
@@ -305,6 +323,14 @@ function toggleCollapse(state, classes, collapsed) {
   }
   return newState;
 }
+function togglePin(state, pinned) {
+  const newState = pinned ?? !state.isPinned;
+  state.isPinned = newState;
+  if (state.pinButton) {
+    state.pinButton.innerHTML = newState ? PIN_ICON_PINNED : PIN_ICON_UNPINNED;
+  }
+  return newState;
+}
 function showPanel(state, classes) {
   if (!state.isHidden) return;
   state.isHidden = false;
@@ -482,6 +508,28 @@ function snapPanels(leftPanel, rightPanel) {
   leftPanel.snappedTo = rightPanel.id;
   rightPanel.snappedFrom = leftPanel.id;
 }
+function getMovingGroupRespectingPins(grabbedPanel, panels) {
+  if (grabbedPanel.isPinned) return [];
+  const fullGroup = getConnectedGroup(grabbedPanel, panels);
+  const grabbedIndex = fullGroup.indexOf(grabbedPanel);
+  const leftPanels = [];
+  for (let i = grabbedIndex; i >= 0; i--) {
+    if (fullGroup[i].isPinned) {
+      unsnap(fullGroup[i], fullGroup[i + 1]);
+      break;
+    }
+    leftPanels.unshift(fullGroup[i]);
+  }
+  const rightPanels = [];
+  for (let i = grabbedIndex + 1; i < fullGroup.length; i++) {
+    if (fullGroup[i].isPinned) {
+      unsnap(fullGroup[i - 1], fullGroup[i]);
+      break;
+    }
+    rightPanels.push(fullGroup[i]);
+  }
+  return [...leftPanels, ...rightPanels];
+}
 function unsnap(leftPanel, rightPanel) {
   if (leftPanel.snappedTo === rightPanel.id) {
     leftPanel.snappedTo = null;
@@ -509,18 +557,18 @@ var DragManager = class {
   startDrag(e, panel, mode) {
     e.preventDefault();
     e.stopPropagation();
-    const connectedPanels = getConnectedGroup(panel, this.panels);
-    const initialGroupPositions = /* @__PURE__ */ new Map();
-    for (const p of connectedPanels) {
-      const rect2 = p.element.getBoundingClientRect();
-      initialGroupPositions.set(p.id, { x: rect2.left, y: rect2.top });
-    }
     let movingPanels;
     if (mode === "single") {
       detachFromGroup(panel, this.panels);
       movingPanels = [panel];
     } else {
-      movingPanels = connectedPanels;
+      movingPanels = getMovingGroupRespectingPins(panel, this.panels);
+      if (movingPanels.length === 0) return;
+    }
+    const initialGroupPositions = /* @__PURE__ */ new Map();
+    for (const p of movingPanels) {
+      const rect2 = p.element.getBoundingClientRect();
+      initialGroupPositions.set(p.id, { x: rect2.left, y: rect2.top });
     }
     const rect = panel.element.getBoundingClientRect();
     this.activeDrag = {
@@ -1010,6 +1058,7 @@ var AutoHideManager = class {
    */
   handleActivity() {
     for (const panel of this.panels.values()) {
+      if (panel.isPinned) continue;
       if (this.pausedPanels.has(panel.id)) continue;
       if (panel.resolvedAutoHideDelay !== void 0 || panel.isHidden) {
         this.show(panel, "activity");
@@ -1070,9 +1119,27 @@ var AutoHideManager = class {
    */
   hide(panel, trigger) {
     if (panel.isHidden) return;
+    if (panel.isPinned) return;
     hidePanel(panel, this.classes);
     this.callbacks.onHide?.(panel, trigger);
   }
+  /**
+   * Called when a panel's pin state changes.
+   * Pinning cancels the hide timer and reveals the panel if hidden.
+   * Unpinning restarts the timer if the panel participates in auto-hide.
+   */
+  onPanelPinChanged(panel) {
+    if (panel.isPinned) {
+      this.clearTimer(panel.id);
+      if (panel.isHidden) {
+        this.show(panel, "api");
+      }
+    } else {
+      if (!panel.isHidden && panel.resolvedAutoHideDelay !== void 0) {
+        this.scheduleHide(panel);
+      }
+    }
+  }
   /**
    * Initialize a newly added panel's auto-hide state
    */
@@ -1127,6 +1194,7 @@ function generateClasses(prefix) {
     panelContent: `${prefix}-content`,
     panelContentCollapsed: `${prefix}-content-collapsed`,
     detachGrip: `${prefix}-detach-grip`,
+    pinButton: `${prefix}-pin-btn`,
     collapseButton: `${prefix}-collapse-btn`,
     snapPreview: `${prefix}-snap-preview`,
     snapPreviewVisible: `${prefix}-snap-preview-visible`,
@@ -1217,6 +1285,7 @@ var TabManager = class {
       id,
       element,
       dragHandle: options.dragHandle,
+      pinButton: options.pinButton,
       collapseButton: options.collapseButton,
       contentWrapper: options.contentWrapper,
       detachGrip: options.detachGrip,
@@ -1306,15 +1375,25 @@ var TabManager = class {
         this.emit("panel:collapse", { panel: state, isCollapsed: newState });
       });
     }
+    if (state.pinButton) {
+      state.pinButton.addEventListener("click", () => {
+        const isPinned = togglePin(state);
+        this.autoHideManager.onPanelPinChanged(state);
+        this.emit("panel:pin", { panel: state, isPinned });
+      });
+    }
     if (state.detachGrip) {
       state.detachGrip.addEventListener("mousedown", (e) => {
+        if (state.isPinned) return;
         this.dragManager.startDrag(e, state, "single");
       });
     }
     state.dragHandle.addEventListener("mousedown", (e) => {
-      if (e.target === state.collapseButton || e.target === state.detachGrip) {
+      const target = e.target;
+      if (e.target === state.collapseButton || e.target === state.detachGrip || state.pinButton && state.pinButton.contains(target)) {
         return;
       }
+      if (state.isPinned) return;
       this.dragManager.startDrag(e, state, "group");
     });
   }
@@ -1575,6 +1654,7 @@ var TabManager = class {
   getDefaultZIndex,
   getDragZIndex,
   getLeftmostPanel,
+  getMovingGroupRespectingPins,
   getPanelDimensions,
   getPanelPosition,
   getRightmostPanel,
@@ -1586,6 +1666,7 @@ var TabManager = class {
   snapPanels,
   snapPanelsToTarget,
   toggleCollapse,
+  togglePin,
   unsnap,
   updateSnappedPositions
 });

package/dist/index.d.cts

@@ -52,6 +52,8 @@ interface PanelConfig {
     title?: string;
     /** Initial width (default: 300) */
     width?: number;
+    /** Initial pin state (default: false) */
+    startPinned?: boolean;
     /** Initial collapsed state (default: true) */
     startCollapsed?: boolean;
     /** Initial position (optional - will be auto-positioned if not provided) */
@@ -65,12 +67,16 @@ interface PanelConfig {
     element?: HTMLDivElement;
     /** Custom drag handle element */
     dragHandle?: HTMLDivElement;
+    /** Custom pin button element */
+    pinButton?: HTMLButtonElement;
     /** Custom collapse button element */
     collapseButton?: HTMLButtonElement;
     /** Custom content wrapper element */
     contentWrapper?: HTMLDivElement;
     /** Custom detach grip element */
     detachGrip?: HTMLDivElement;
+    /** Whether panel can be pinned (default: false) */
+    pinnable?: boolean;
     /** Whether panel can be collapsed (default: true) */
     collapsible?: boolean;
     /** Whether panel can be detached from group (default: true) */
@@ -111,12 +117,16 @@ interface PanelState {
     element: HTMLDivElement;
     /** Drag handle element */
     dragHandle: HTMLDivElement;
+    /** Pin button element (if pinable) */
+    pinButton: HTMLButtonElement | null;
     /** Collapse button element (if collapsible) */
     collapseButton: HTMLButtonElement | null;
     /** Content wrapper element */
     contentWrapper: HTMLDivElement;
     /** Detach grip element (if detachable) */
     detachGrip: HTMLDivElement | null;
+    /** Whether panel is currently pinned */
+    isPinned: boolean;
     /** Whether panel is currently collapsed */
     isCollapsed: boolean;
     /** ID of panel this is snapped to on its right (outgoing link) */
@@ -226,6 +236,8 @@ interface TabManagerEvents {
     'snap:anchor': AnchorSnapEvent;
     /** Fired when a panel is detached from group */
     'panel:detached': PanelDetachedEvent;
+    /** Fired when panel pin state changes */
+    'panel:pin': PanelPinEvent;
     /** Fired when panel collapse state changes */
     'panel:collapse': PanelCollapseEvent;
     /** Fired when a panel becomes visible (auto-hide) */
@@ -269,6 +281,10 @@ interface PanelDetachedEvent {
     panel: PanelState;
     previousGroup: PanelState[];
 }
+interface PanelPinEvent {
+    panel: PanelState;
+    isPinned: boolean;
+}
 interface PanelCollapseEvent {
     panel: PanelState;
     isCollapsed: boolean;
@@ -295,6 +311,7 @@ interface CSSClasses {
     panelContent: string;
     panelContentCollapsed: string;
     detachGrip: string;
+    pinButton: string;
     collapseButton: string;
     snapPreview: string;
     snapPreviewVisible: string;
@@ -403,6 +420,7 @@ declare class TabManager {
      */
     registerPanel(id: string, element: HTMLDivElement, options?: {
         dragHandle?: HTMLDivElement;
+        pinButton?: HTMLButtonElement;
         collapseButton?: HTMLButtonElement;
         contentWrapper?: HTMLDivElement;
         detachGrip?: HTMLDivElement;
@@ -734,6 +752,12 @@ declare class AutoHideManager {
      * Hide a panel
      */
     hide(panel: PanelState, trigger: 'timeout' | 'api'): void;
+    /**
+     * Called when a panel's pin state changes.
+     * Pinning cancels the hide timer and reveals the panel if hidden.
+     * Unpinning restarts the timer if the panel participates in auto-hide.
+     */
+    onPanelPinChanged(panel: PanelState): void;
     /**
      * Initialize a newly added panel's auto-hide state
      */
@@ -810,6 +834,7 @@ declare function setupHoverEnlarge(config: HoverEnlargeConfig): void;
 declare function createPanelElement(config: PanelConfig, classes: CSSClasses): {
     element: HTMLDivElement;
     dragHandle: HTMLDivElement;
+    pinButton: HTMLButtonElement | null;
     collapseButton: HTMLButtonElement | null;
     contentWrapper: HTMLDivElement;
     detachGrip: HTMLDivElement | null;
@@ -825,6 +850,10 @@ declare function createPanelState(config: PanelConfig, classes: CSSClasses, glob
  * Toggle panel collapse state
  */
 declare function toggleCollapse(state: PanelState, classes: CSSClasses, collapsed?: boolean): boolean;
+/**
+ * Toggle panel pin state
+ */
+declare function togglePin(state: PanelState, pinned?: boolean): boolean;
 /**
  * Show a hidden panel
  */
@@ -909,9 +938,21 @@ declare function areInSameChain(panel1: PanelState, panel2: PanelState, panels:
  * Establish a snap relationship between two panels
  */
 declare function snapPanels(leftPanel: PanelState, rightPanel: PanelState): void;
+/**
+ * Get the subset of connected panels that should move when a panel is grabbed,
+ * stopping at any pinned panel in the chain.
+ *
+ * Pinned panels act as immoveable barriers — the chain splits at each one,
+ * and only the panels on the same side as the grabbed panel are returned.
+ * The snap bonds at each pin boundary are severed as a side effect.
+ *
+ * Example: chain [A, B, P(pinned), C, D], grab B → returns [A, B], unseats B↔P
+ * Example: chain [A, P(pinned), B, C], grab C → returns [B, C], unseats P↔B
+ */
+declare function getMovingGroupRespectingPins(grabbedPanel: PanelState, panels: Map<string, PanelState>): PanelState[];
 /**
  * Break the snap relationship between two specific panels
  */
 declare function unsnap(leftPanel: PanelState, rightPanel: PanelState): void;
 
-export { type AnchorConfig, AnchorManager, type AnchorPreset, type AnchorSnapEvent, type AnchorSnapResult, type AnchorState, type AutoHideCallbacks, AutoHideManager, type Bounds, type CSSClasses, type DebugLog, type DebugLogConfig, type DebugLogLevel, type DebugPanel, type DebugPanelConfig, type DragEndEvent, DragManager, type DragMode, type DragMoveEvent, type DragStartEvent, type DragState, type EventListener, type PanelAddedEvent, type PanelCollapseEvent, type PanelConfig, type PanelDetachedEvent, type PanelHideEvent, type PanelRemovedEvent, type PanelShowEvent, type PanelSnapEvent, type PanelState, type Position, type ResolvedTabManagerConfig, SnapPreview, type SnapSide, type SnapTarget, TabManager, type TabManagerConfig, type TabManagerEvents, areInSameChain, createDebugLog, createDebugPanelContent, createDebugPanelInterface, createPanelElement, createPanelState, createPresetAnchor, detachFromGroup, findSnapTarget, getConnectedGroup, getDefaultAnchorConfigs, getDefaultZIndex, getDragZIndex, getLeftmostPanel, getPanelDimensions, getPanelPosition, getRightmostPanel, hidePanel, setPanelPosition, setPanelZIndex, setupHoverEnlarge, showPanel, snapPanels, snapPanelsToTarget, toggleCollapse, unsnap, updateSnappedPositions };
+export { type AnchorConfig, AnchorManager, type AnchorPreset, type AnchorSnapEvent, type AnchorSnapResult, type AnchorState, type AutoHideCallbacks, AutoHideManager, type Bounds, type CSSClasses, type DebugLog, type DebugLogConfig, type DebugLogLevel, type DebugPanel, type DebugPanelConfig, type DragEndEvent, DragManager, type DragMode, type DragMoveEvent, type DragStartEvent, type DragState, type EventListener, type PanelAddedEvent, type PanelCollapseEvent, type PanelConfig, type PanelDetachedEvent, type PanelHideEvent, type PanelPinEvent, type PanelRemovedEvent, type PanelShowEvent, type PanelSnapEvent, type PanelState, type Position, type ResolvedTabManagerConfig, SnapPreview, type SnapSide, type SnapTarget, TabManager, type TabManagerConfig, type TabManagerEvents, areInSameChain, createDebugLog, createDebugPanelContent, createDebugPanelInterface, createPanelElement, createPanelState, createPresetAnchor, detachFromGroup, findSnapTarget, getConnectedGroup, getDefaultAnchorConfigs, getDefaultZIndex, getDragZIndex, getLeftmostPanel, getMovingGroupRespectingPins, getPanelDimensions, getPanelPosition, getRightmostPanel, hidePanel, setPanelPosition, setPanelZIndex, setupHoverEnlarge, showPanel, snapPanels, snapPanelsToTarget, toggleCollapse, togglePin, unsnap, updateSnappedPositions };

package/dist/index.d.ts

@@ -52,6 +52,8 @@ interface PanelConfig {
     title?: string;
     /** Initial width (default: 300) */
     width?: number;
+    /** Initial pin state (default: false) */
+    startPinned?: boolean;
     /** Initial collapsed state (default: true) */
     startCollapsed?: boolean;
     /** Initial position (optional - will be auto-positioned if not provided) */
@@ -65,12 +67,16 @@ interface PanelConfig {
     element?: HTMLDivElement;
     /** Custom drag handle element */
     dragHandle?: HTMLDivElement;
+    /** Custom pin button element */
+    pinButton?: HTMLButtonElement;
     /** Custom collapse button element */
     collapseButton?: HTMLButtonElement;
     /** Custom content wrapper element */
     contentWrapper?: HTMLDivElement;
     /** Custom detach grip element */
     detachGrip?: HTMLDivElement;
+    /** Whether panel can be pinned (default: false) */
+    pinnable?: boolean;
     /** Whether panel can be collapsed (default: true) */
     collapsible?: boolean;
     /** Whether panel can be detached from group (default: true) */
@@ -111,12 +117,16 @@ interface PanelState {
     element: HTMLDivElement;
     /** Drag handle element */
     dragHandle: HTMLDivElement;
+    /** Pin button element (if pinable) */
+    pinButton: HTMLButtonElement | null;
     /** Collapse button element (if collapsible) */
     collapseButton: HTMLButtonElement | null;
     /** Content wrapper element */
     contentWrapper: HTMLDivElement;
     /** Detach grip element (if detachable) */
     detachGrip: HTMLDivElement | null;
+    /** Whether panel is currently pinned */
+    isPinned: boolean;
     /** Whether panel is currently collapsed */
     isCollapsed: boolean;
     /** ID of panel this is snapped to on its right (outgoing link) */
@@ -226,6 +236,8 @@ interface TabManagerEvents {
     'snap:anchor': AnchorSnapEvent;
     /** Fired when a panel is detached from group */
     'panel:detached': PanelDetachedEvent;
+    /** Fired when panel pin state changes */
+    'panel:pin': PanelPinEvent;
     /** Fired when panel collapse state changes */
     'panel:collapse': PanelCollapseEvent;
     /** Fired when a panel becomes visible (auto-hide) */
@@ -269,6 +281,10 @@ interface PanelDetachedEvent {
     panel: PanelState;
     previousGroup: PanelState[];
 }
+interface PanelPinEvent {
+    panel: PanelState;
+    isPinned: boolean;
+}
 interface PanelCollapseEvent {
     panel: PanelState;
     isCollapsed: boolean;
@@ -295,6 +311,7 @@ interface CSSClasses {
     panelContent: string;
     panelContentCollapsed: string;
     detachGrip: string;
+    pinButton: string;
     collapseButton: string;
     snapPreview: string;
     snapPreviewVisible: string;
@@ -403,6 +420,7 @@ declare class TabManager {
      */
     registerPanel(id: string, element: HTMLDivElement, options?: {
         dragHandle?: HTMLDivElement;
+        pinButton?: HTMLButtonElement;
         collapseButton?: HTMLButtonElement;
         contentWrapper?: HTMLDivElement;
         detachGrip?: HTMLDivElement;
@@ -734,6 +752,12 @@ declare class AutoHideManager {
      * Hide a panel
      */
     hide(panel: PanelState, trigger: 'timeout' | 'api'): void;
+    /**
+     * Called when a panel's pin state changes.
+     * Pinning cancels the hide timer and reveals the panel if hidden.
+     * Unpinning restarts the timer if the panel participates in auto-hide.
+     */
+    onPanelPinChanged(panel: PanelState): void;
     /**
      * Initialize a newly added panel's auto-hide state
      */
@@ -810,6 +834,7 @@ declare function setupHoverEnlarge(config: HoverEnlargeConfig): void;
 declare function createPanelElement(config: PanelConfig, classes: CSSClasses): {
     element: HTMLDivElement;
     dragHandle: HTMLDivElement;
+    pinButton: HTMLButtonElement | null;
     collapseButton: HTMLButtonElement | null;
     contentWrapper: HTMLDivElement;
     detachGrip: HTMLDivElement | null;
@@ -825,6 +850,10 @@ declare function createPanelState(config: PanelConfig, classes: CSSClasses, glob
  * Toggle panel collapse state
  */
 declare function toggleCollapse(state: PanelState, classes: CSSClasses, collapsed?: boolean): boolean;
+/**
+ * Toggle panel pin state
+ */
+declare function togglePin(state: PanelState, pinned?: boolean): boolean;
 /**
  * Show a hidden panel
  */
@@ -909,9 +938,21 @@ declare function areInSameChain(panel1: PanelState, panel2: PanelState, panels:
  * Establish a snap relationship between two panels
  */
 declare function snapPanels(leftPanel: PanelState, rightPanel: PanelState): void;
+/**
+ * Get the subset of connected panels that should move when a panel is grabbed,
+ * stopping at any pinned panel in the chain.
+ *
+ * Pinned panels act as immoveable barriers — the chain splits at each one,
+ * and only the panels on the same side as the grabbed panel are returned.
+ * The snap bonds at each pin boundary are severed as a side effect.
+ *
+ * Example: chain [A, B, P(pinned), C, D], grab B → returns [A, B], unseats B↔P
+ * Example: chain [A, P(pinned), B, C], grab C → returns [B, C], unseats P↔B
+ */
+declare function getMovingGroupRespectingPins(grabbedPanel: PanelState, panels: Map<string, PanelState>): PanelState[];
 /**
  * Break the snap relationship between two specific panels
  */
 declare function unsnap(leftPanel: PanelState, rightPanel: PanelState): void;
 
-export { type AnchorConfig, AnchorManager, type AnchorPreset, type AnchorSnapEvent, type AnchorSnapResult, type AnchorState, type AutoHideCallbacks, AutoHideManager, type Bounds, type CSSClasses, type DebugLog, type DebugLogConfig, type DebugLogLevel, type DebugPanel, type DebugPanelConfig, type DragEndEvent, DragManager, type DragMode, type DragMoveEvent, type DragStartEvent, type DragState, type EventListener, type PanelAddedEvent, type PanelCollapseEvent, type PanelConfig, type PanelDetachedEvent, type PanelHideEvent, type PanelRemovedEvent, type PanelShowEvent, type PanelSnapEvent, type PanelState, type Position, type ResolvedTabManagerConfig, SnapPreview, type SnapSide, type SnapTarget, TabManager, type TabManagerConfig, type TabManagerEvents, areInSameChain, createDebugLog, createDebugPanelContent, createDebugPanelInterface, createPanelElement, createPanelState, createPresetAnchor, detachFromGroup, findSnapTarget, getConnectedGroup, getDefaultAnchorConfigs, getDefaultZIndex, getDragZIndex, getLeftmostPanel, getPanelDimensions, getPanelPosition, getRightmostPanel, hidePanel, setPanelPosition, setPanelZIndex, setupHoverEnlarge, showPanel, snapPanels, snapPanelsToTarget, toggleCollapse, unsnap, updateSnappedPositions };
+export { type AnchorConfig, AnchorManager, type AnchorPreset, type AnchorSnapEvent, type AnchorSnapResult, type AnchorState, type AutoHideCallbacks, AutoHideManager, type Bounds, type CSSClasses, type DebugLog, type DebugLogConfig, type DebugLogLevel, type DebugPanel, type DebugPanelConfig, type DragEndEvent, DragManager, type DragMode, type DragMoveEvent, type DragStartEvent, type DragState, type EventListener, type PanelAddedEvent, type PanelCollapseEvent, type PanelConfig, type PanelDetachedEvent, type PanelHideEvent, type PanelPinEvent, type PanelRemovedEvent, type PanelShowEvent, type PanelSnapEvent, type PanelState, type Position, type ResolvedTabManagerConfig, SnapPreview, type SnapSide, type SnapTarget, TabManager, type TabManagerConfig, type TabManagerEvents, areInSameChain, createDebugLog, createDebugPanelContent, createDebugPanelInterface, createPanelElement, createPanelState, createPresetAnchor, detachFromGroup, findSnapTarget, getConnectedGroup, getDefaultAnchorConfigs, getDefaultZIndex, getDragZIndex, getLeftmostPanel, getMovingGroupRespectingPins, getPanelDimensions, getPanelPosition, getRightmostPanel, hidePanel, setPanelPosition, setPanelZIndex, setupHoverEnlarge, showPanel, snapPanels, snapPanelsToTarget, toggleCollapse, togglePin, unsnap, updateSnappedPositions };

package/dist/index.js

@@ -142,6 +142,8 @@ function setupHoverEnlarge(config) {
 }
 
 // src/Panel.ts
+var PIN_ICON_UNPINNED = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:block"><line x1="12" y1="17" x2="12" y2="22"/><path d="M5 17H19V16L17 11V4H7L5 11V16Z"/><line x1="5" y1="11" x2="19" y2="11"/></svg>`;
+var PIN_ICON_PINNED = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="14" height="14" fill="currentColor" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:block;transform:rotate(90deg)"><line x1="12" y1="17" x2="12" y2="22"/><path d="M5 17H19V16L17 11V4H7L5 11V16Z"/><line x1="5" y1="11" x2="19" y2="11"/></svg>`;
 function createPanelElement(config, classes) {
   const element = document.createElement("div");
   element.className = classes.panel;
@@ -164,6 +166,14 @@ function createPanelElement(config, classes) {
     title.textContent = config.title;
     header.appendChild(title);
   }
+  let pinButton = null;
+  if (config.pinnable === true) {
+    pinButton = document.createElement("button");
+    pinButton.className = classes.pinButton;
+    pinButton.id = `${config.id}-pin-btn`;
+    pinButton.innerHTML = config.startPinned === true ? PIN_ICON_PINNED : PIN_ICON_UNPINNED;
+    header.appendChild(pinButton);
+  }
   let collapseButton = null;
   if (config.collapsible !== false) {
     collapseButton = document.createElement("button");
@@ -190,6 +200,7 @@ function createPanelElement(config, classes) {
   return {
     element,
     dragHandle: header,
+    pinButton,
     collapseButton,
     contentWrapper,
     detachGrip
@@ -198,12 +209,14 @@ function createPanelElement(config, classes) {
 function createPanelState(config, classes, globalConfig) {
   let element;
   let dragHandle;
+  let pinButton;
   let collapseButton;
   let contentWrapper;
   let detachGrip;
   if (config.element) {
     element = config.element;
     dragHandle = config.dragHandle ?? element.querySelector(`.${classes.panelHeader}`);
+    pinButton = config.pinButton ?? element.querySelector(`.${classes.pinButton}`);
     collapseButton = config.collapseButton ?? element.querySelector(`.${classes.collapseButton}`);
     contentWrapper = config.contentWrapper ?? element.querySelector(`.${classes.panelContent}`);
     detachGrip = config.detachGrip ?? element.querySelector(`.${classes.detachGrip}`);
@@ -211,6 +224,7 @@ function createPanelState(config, classes, globalConfig) {
     const created = createPanelElement(config, classes);
     element = created.element;
     dragHandle = created.dragHandle;
+    pinButton = created.pinButton;
     collapseButton = created.collapseButton;
     contentWrapper = created.contentWrapper;
     detachGrip = created.detachGrip;
@@ -224,9 +238,11 @@ function createPanelState(config, classes, globalConfig) {
     id: config.id,
     element,
     dragHandle,
+    pinButton,
     collapseButton,
     contentWrapper,
     detachGrip,
+    isPinned: config.startPinned === true,
     isCollapsed: config.startCollapsed !== false,
     snappedTo: null,
     snappedFrom: null,
@@ -248,6 +264,14 @@ function toggleCollapse(state, classes, collapsed) {
   }
   return newState;
 }
+function togglePin(state, pinned) {
+  const newState = pinned ?? !state.isPinned;
+  state.isPinned = newState;
+  if (state.pinButton) {
+    state.pinButton.innerHTML = newState ? PIN_ICON_PINNED : PIN_ICON_UNPINNED;
+  }
+  return newState;
+}
 function showPanel(state, classes) {
   if (!state.isHidden) return;
   state.isHidden = false;
@@ -425,6 +449,28 @@ function snapPanels(leftPanel, rightPanel) {
   leftPanel.snappedTo = rightPanel.id;
   rightPanel.snappedFrom = leftPanel.id;
 }
+function getMovingGroupRespectingPins(grabbedPanel, panels) {
+  if (grabbedPanel.isPinned) return [];
+  const fullGroup = getConnectedGroup(grabbedPanel, panels);
+  const grabbedIndex = fullGroup.indexOf(grabbedPanel);
+  const leftPanels = [];
+  for (let i = grabbedIndex; i >= 0; i--) {
+    if (fullGroup[i].isPinned) {
+      unsnap(fullGroup[i], fullGroup[i + 1]);
+      break;
+    }
+    leftPanels.unshift(fullGroup[i]);
+  }
+  const rightPanels = [];
+  for (let i = grabbedIndex + 1; i < fullGroup.length; i++) {
+    if (fullGroup[i].isPinned) {
+      unsnap(fullGroup[i - 1], fullGroup[i]);
+      break;
+    }
+    rightPanels.push(fullGroup[i]);
+  }
+  return [...leftPanels, ...rightPanels];
+}
 function unsnap(leftPanel, rightPanel) {
   if (leftPanel.snappedTo === rightPanel.id) {
     leftPanel.snappedTo = null;
@@ -452,18 +498,18 @@ var DragManager = class {
   startDrag(e, panel, mode) {
     e.preventDefault();
     e.stopPropagation();
-    const connectedPanels = getConnectedGroup(panel, this.panels);
-    const initialGroupPositions = /* @__PURE__ */ new Map();
-    for (const p of connectedPanels) {
-      const rect2 = p.element.getBoundingClientRect();
-      initialGroupPositions.set(p.id, { x: rect2.left, y: rect2.top });
-    }
     let movingPanels;
     if (mode === "single") {
       detachFromGroup(panel, this.panels);
       movingPanels = [panel];
     } else {
-      movingPanels = connectedPanels;
+      movingPanels = getMovingGroupRespectingPins(panel, this.panels);
+      if (movingPanels.length === 0) return;
+    }
+    const initialGroupPositions = /* @__PURE__ */ new Map();
+    for (const p of movingPanels) {
+      const rect2 = p.element.getBoundingClientRect();
+      initialGroupPositions.set(p.id, { x: rect2.left, y: rect2.top });
     }
     const rect = panel.element.getBoundingClientRect();
     this.activeDrag = {
@@ -953,6 +999,7 @@ var AutoHideManager = class {
    */
   handleActivity() {
     for (const panel of this.panels.values()) {
+      if (panel.isPinned) continue;
       if (this.pausedPanels.has(panel.id)) continue;
       if (panel.resolvedAutoHideDelay !== void 0 || panel.isHidden) {
         this.show(panel, "activity");
@@ -1013,9 +1060,27 @@ var AutoHideManager = class {
    */
   hide(panel, trigger) {
     if (panel.isHidden) return;
+    if (panel.isPinned) return;
     hidePanel(panel, this.classes);
     this.callbacks.onHide?.(panel, trigger);
   }
+  /**
+   * Called when a panel's pin state changes.
+   * Pinning cancels the hide timer and reveals the panel if hidden.
+   * Unpinning restarts the timer if the panel participates in auto-hide.
+   */
+  onPanelPinChanged(panel) {
+    if (panel.isPinned) {
+      this.clearTimer(panel.id);
+      if (panel.isHidden) {
+        this.show(panel, "api");
+      }
+    } else {
+      if (!panel.isHidden && panel.resolvedAutoHideDelay !== void 0) {
+        this.scheduleHide(panel);
+      }
+    }
+  }
   /**
    * Initialize a newly added panel's auto-hide state
    */
@@ -1070,6 +1135,7 @@ function generateClasses(prefix) {
     panelContent: `${prefix}-content`,
     panelContentCollapsed: `${prefix}-content-collapsed`,
     detachGrip: `${prefix}-detach-grip`,
+    pinButton: `${prefix}-pin-btn`,
     collapseButton: `${prefix}-collapse-btn`,
     snapPreview: `${prefix}-snap-preview`,
     snapPreviewVisible: `${prefix}-snap-preview-visible`,
@@ -1160,6 +1226,7 @@ var TabManager = class {
       id,
       element,
       dragHandle: options.dragHandle,
+      pinButton: options.pinButton,
       collapseButton: options.collapseButton,
       contentWrapper: options.contentWrapper,
       detachGrip: options.detachGrip,
@@ -1249,15 +1316,25 @@ var TabManager = class {
         this.emit("panel:collapse", { panel: state, isCollapsed: newState });
       });
     }
+    if (state.pinButton) {
+      state.pinButton.addEventListener("click", () => {
+        const isPinned = togglePin(state);
+        this.autoHideManager.onPanelPinChanged(state);
+        this.emit("panel:pin", { panel: state, isPinned });
+      });
+    }
     if (state.detachGrip) {
       state.detachGrip.addEventListener("mousedown", (e) => {
+        if (state.isPinned) return;
         this.dragManager.startDrag(e, state, "single");
       });
     }
     state.dragHandle.addEventListener("mousedown", (e) => {
-      if (e.target === state.collapseButton || e.target === state.detachGrip) {
+      const target = e.target;
+      if (e.target === state.collapseButton || e.target === state.detachGrip || state.pinButton && state.pinButton.contains(target)) {
         return;
       }
+      if (state.isPinned) return;
       this.dragManager.startDrag(e, state, "group");
     });
   }
@@ -1517,6 +1594,7 @@ export {
   getDefaultZIndex,
   getDragZIndex,
   getLeftmostPanel,
+  getMovingGroupRespectingPins,
   getPanelDimensions,
   getPanelPosition,
   getRightmostPanel,
@@ -1528,6 +1606,7 @@ export {
   snapPanels,
   snapPanelsToTarget,
   toggleCollapse,
+  togglePin,
   unsnap,
   updateSnappedPositions
 };

package/dist/styles.css

@@ -83,6 +83,26 @@
   background: var(--blork-tabs-accent, #4a90d9);
 }
 
+/* Pin Button */
+.blork-tabs-pin-btn {
+  width: 24px;
+  height: 24px;
+  border: none;
+  background: transparent;
+  color: var(--blork-tabs-header-color, #e0e0e0);
+  cursor: pointer;
+  border-radius: 4px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  transition: background 0.2s;
+}
+
+.blork-tabs-pin-btn:hover {
+  background: rgba(255, 255, 255, 0.1);
+}
+
 /* Collapse Button */
 .blork-tabs-collapse-btn {
   width: 24px;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blorkfield/blork-tabs",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "A framework-agnostic tab/panel management system with snapping and docking",
   "packageManager": "pnpm@10.28.2",
   "type": "module",

package/src/AutoHideManager.ts

@@ -50,9 +50,10 @@ export class AutoHideManager {
    */
   private handleActivity(): void {
     for (const panel of this.panels.values()) {
+      // Pinned panels are immune to activity-based show/hide
+      if (panel.isPinned) continue;
       // Skip paused panels - they handle their own timing
       if (this.pausedPanels.has(panel.id)) continue;
-
       // Only process panels that participate in auto-hide
       if (panel.resolvedAutoHideDelay !== undefined || panel.isHidden) {
         this.show(panel, 'activity');
@@ -120,10 +121,29 @@ export class AutoHideManager {
    */
   hide(panel: PanelState, trigger: 'timeout' | 'api'): void {
     if (panel.isHidden) return;
+    if (panel.isPinned) return; // Pinned panels are always visible
     hidePanel(panel, this.classes);
     this.callbacks.onHide?.(panel, trigger);
   }
 
+  /**
+   * Called when a panel's pin state changes.
+   * Pinning cancels the hide timer and reveals the panel if hidden.
+   * Unpinning restarts the timer if the panel participates in auto-hide.
+   */
+  onPanelPinChanged(panel: PanelState): void {
+    if (panel.isPinned) {
+      this.clearTimer(panel.id);
+      if (panel.isHidden) {
+        this.show(panel, 'api');
+      }
+    } else {
+      if (!panel.isHidden && panel.resolvedAutoHideDelay !== undefined) {
+        this.scheduleHide(panel);
+      }
+    }
+  }
+
   /**
    * Initialize a newly added panel's auto-hide state
    */

package/src/DragManager.ts

@@ -13,7 +13,7 @@ import type {
   ResolvedTabManagerConfig,
 } from './types';
 import {
-  getConnectedGroup,
+  getMovingGroupRespectingPins,
   detachFromGroup,
   findSnapTarget,
   snapPanelsToTarget,
@@ -76,24 +76,24 @@ export class DragManager {
     e.preventDefault();
     e.stopPropagation();
 
-    const connectedPanels = getConnectedGroup(panel, this.panels);
-
-    // Store initial positions
-    const initialGroupPositions = new Map<string, Position>();
-    for (const p of connectedPanels) {
-      const rect = p.element.getBoundingClientRect();
-      initialGroupPositions.set(p.id, { x: rect.left, y: rect.top });
-    }
-
     let movingPanels: PanelState[];
 
     if (mode === 'single') {
-      // Detach this panel from its group
+      // Detach this panel from its group and move it alone
       detachFromGroup(panel, this.panels);
       movingPanels = [panel];
     } else {
-      // Move entire group
-      movingPanels = connectedPanels;
+      // Group drag: collect panels on either side of the grabbed panel,
+      // splitting at any pinned panel and severing those bonds
+      movingPanels = getMovingGroupRespectingPins(panel, this.panels);
+      if (movingPanels.length === 0) return;
+    }
+
+    // Store initial positions for the panels that will actually move
+    const initialGroupPositions = new Map<string, Position>();
+    for (const p of movingPanels) {
+      const rect = p.element.getBoundingClientRect();
+      initialGroupPositions.set(p.id, { x: rect.left, y: rect.top });
     }
 
     const rect = panel.element.getBoundingClientRect();

package/src/Panel.ts

@@ -9,6 +9,9 @@ import type {
   CSSClasses,
 } from './types';
 
+const PIN_ICON_UNPINNED = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:block"><line x1="12" y1="17" x2="12" y2="22"/><path d="M5 17H19V16L17 11V4H7L5 11V16Z"/><line x1="5" y1="11" x2="19" y2="11"/></svg>`;
+const PIN_ICON_PINNED = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="14" height="14" fill="currentColor" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:block;transform:rotate(90deg)"><line x1="12" y1="17" x2="12" y2="22"/><path d="M5 17H19V16L17 11V4H7L5 11V16Z"/><line x1="5" y1="11" x2="19" y2="11"/></svg>`;
+
 /**
  * Creates the default panel DOM structure
  */
@@ -18,6 +21,7 @@ export function createPanelElement(
 ): {
   element: HTMLDivElement;
   dragHandle: HTMLDivElement;
+  pinButton: HTMLButtonElement | null;
   collapseButton: HTMLButtonElement | null;
   contentWrapper: HTMLDivElement;
   detachGrip: HTMLDivElement | null;
@@ -50,6 +54,16 @@ export function createPanelElement(
     header.appendChild(title);
   }
 
+  // Pin button (only if explicitly pinnable)
+  let pinButton: HTMLButtonElement | null = null;
+  if (config.pinnable === true) {
+    pinButton = document.createElement('button');
+    pinButton.className = classes.pinButton;
+    pinButton.id = `${config.id}-pin-btn`;
+    pinButton.innerHTML = config.startPinned === true ? PIN_ICON_PINNED : PIN_ICON_UNPINNED;
+    header.appendChild(pinButton);
+  }
+
   // Collapse button (if collapsible)
   let collapseButton: HTMLButtonElement | null = null;
   if (config.collapsible !== false) {
@@ -84,6 +98,7 @@ export function createPanelElement(
   return {
     element,
     dragHandle: header,
+    pinButton,
     collapseButton,
     contentWrapper,
     detachGrip,
@@ -100,6 +115,7 @@ export function createPanelState(
 ): PanelState {
   let element: HTMLDivElement;
   let dragHandle: HTMLDivElement;
+  let pinButton: HTMLButtonElement | null;
   let collapseButton: HTMLButtonElement | null;
   let contentWrapper: HTMLDivElement;
   let detachGrip: HTMLDivElement | null;
@@ -108,6 +124,7 @@ export function createPanelState(
     // Use existing DOM elements
     element = config.element;
     dragHandle = config.dragHandle ?? (element.querySelector(`.${classes.panelHeader}`) as HTMLDivElement);
+    pinButton = config.pinButton ?? (element.querySelector(`.${classes.pinButton}`) as HTMLButtonElement | null);
     collapseButton = config.collapseButton ?? (element.querySelector(`.${classes.collapseButton}`) as HTMLButtonElement | null);
     contentWrapper = config.contentWrapper ?? (element.querySelector(`.${classes.panelContent}`) as HTMLDivElement);
     detachGrip = config.detachGrip ?? (element.querySelector(`.${classes.detachGrip}`) as HTMLDivElement | null);
@@ -116,6 +133,7 @@ export function createPanelState(
     const created = createPanelElement(config, classes);
     element = created.element;
     dragHandle = created.dragHandle;
+    pinButton = created.pinButton;
     collapseButton = created.collapseButton;
     contentWrapper = created.contentWrapper;
     detachGrip = created.detachGrip;
@@ -136,9 +154,11 @@ export function createPanelState(
     id: config.id,
     element,
     dragHandle,
+    pinButton,
     collapseButton,
     contentWrapper,
     detachGrip,
+    isPinned: config.startPinned === true,
     isCollapsed: config.startCollapsed !== false,
     snappedTo: null,
     snappedFrom: null,
@@ -172,6 +192,23 @@ export function toggleCollapse(
   return newState;
 }
 
+/**
+ * Toggle panel pin state
+ */
+export function togglePin(
+  state: PanelState,
+  pinned?: boolean
+): boolean {
+  const newState = pinned ?? !state.isPinned;
+  state.isPinned = newState;
+
+  if (state.pinButton) {
+    state.pinButton.innerHTML = newState ? PIN_ICON_PINNED : PIN_ICON_UNPINNED;
+  }
+
+  return newState;
+}
+
 /**
  * Show a hidden panel
  */

package/src/SnapChain.ts

@@ -273,6 +273,51 @@ export function snapPanels(
   rightPanel.snappedFrom = leftPanel.id;
 }
 
+/**
+ * Get the subset of connected panels that should move when a panel is grabbed,
+ * stopping at any pinned panel in the chain.
+ *
+ * Pinned panels act as immoveable barriers — the chain splits at each one,
+ * and only the panels on the same side as the grabbed panel are returned.
+ * The snap bonds at each pin boundary are severed as a side effect.
+ *
+ * Example: chain [A, B, P(pinned), C, D], grab B → returns [A, B], unseats B↔P
+ * Example: chain [A, P(pinned), B, C], grab C → returns [B, C], unseats P↔B
+ */
+export function getMovingGroupRespectingPins(
+  grabbedPanel: PanelState,
+  panels: Map<string, PanelState>
+): PanelState[] {
+  if (grabbedPanel.isPinned) return [];
+
+  const fullGroup = getConnectedGroup(grabbedPanel, panels);
+  const grabbedIndex = fullGroup.indexOf(grabbedPanel);
+
+  // Walk left from the grabbed panel, stopping before any pinned panel
+  const leftPanels: PanelState[] = [];
+  for (let i = grabbedIndex; i >= 0; i--) {
+    if (fullGroup[i].isPinned) {
+      // Sever the bond between this pinned panel and the next moveable panel
+      unsnap(fullGroup[i], fullGroup[i + 1]);
+      break;
+    }
+    leftPanels.unshift(fullGroup[i]);
+  }
+
+  // Walk right from the grabbed panel, stopping before any pinned panel
+  const rightPanels: PanelState[] = [];
+  for (let i = grabbedIndex + 1; i < fullGroup.length; i++) {
+    if (fullGroup[i].isPinned) {
+      // Sever the bond between the last moveable panel and this pinned panel
+      unsnap(fullGroup[i - 1], fullGroup[i]);
+      break;
+    }
+    rightPanels.push(fullGroup[i]);
+  }
+
+  return [...leftPanels, ...rightPanels];
+}
+
 /**
  * Break the snap relationship between two specific panels
  */

package/src/TabManager.ts

@@ -24,7 +24,7 @@ import type {
   DebugLog,
 } from './types';
 import { createDebugPanelContent, createDebugPanelInterface, createDebugLog, setupHoverEnlarge, DebugPanelElements } from './DebugPanel';
-import { createPanelState, toggleCollapse, setPanelPosition } from './Panel';
+import { createPanelState, toggleCollapse, togglePin, setPanelPosition } from './Panel';
 import { getConnectedGroup, detachFromGroup, updateSnappedPositions, snapPanels } from './SnapChain';
 import { DragManager } from './DragManager';
 import { AnchorManager } from './AnchorManager';
@@ -58,6 +58,7 @@ function generateClasses(prefix: string): CSSClasses {
     panelContent: `${prefix}-content`,
     panelContentCollapsed: `${prefix}-content-collapsed`,
     detachGrip: `${prefix}-detach-grip`,
+    pinButton: `${prefix}-pin-btn`,
     collapseButton: `${prefix}-collapse-btn`,
     snapPreview: `${prefix}-snap-preview`,
     snapPreviewVisible: `${prefix}-snap-preview-visible`,
@@ -181,6 +182,7 @@ export class TabManager {
     element: HTMLDivElement,
     options: {
       dragHandle?: HTMLDivElement;
+      pinButton?: HTMLButtonElement;
       collapseButton?: HTMLButtonElement;
       contentWrapper?: HTMLDivElement;
       detachGrip?: HTMLDivElement;
@@ -191,6 +193,7 @@ export class TabManager {
       id,
       element,
       dragHandle: options.dragHandle,
+      pinButton: options.pinButton,
       collapseButton: options.collapseButton,
       contentWrapper: options.contentWrapper,
       detachGrip: options.detachGrip,
@@ -309,22 +312,35 @@ export class TabManager {
       });
     }
 
+    // Pin button
+    if (state.pinButton) {
+      state.pinButton.addEventListener('click', () => {
+        const isPinned = togglePin(state);
+        this.autoHideManager.onPanelPinChanged(state);
+        this.emit('panel:pin', { panel: state, isPinned });
+      });
+    }
+
     // Detach grip - single panel drag
     if (state.detachGrip) {
       state.detachGrip.addEventListener('mousedown', (e) => {
+        if (state.isPinned) return;
         this.dragManager.startDrag(e, state, 'single');
       });
     }
 
     // Main drag handle - group drag
     state.dragHandle.addEventListener('mousedown', (e) => {
-      // Ignore if clicking on collapse button or detach grip
+      // Ignore if clicking on collapse button, pin button, or detach grip
+      const target = e.target as Node;
       if (
         e.target === state.collapseButton ||
-        e.target === state.detachGrip
+        e.target === state.detachGrip ||
+        (state.pinButton && state.pinButton.contains(target))
       ) {
         return;
       }
+      if (state.isPinned) return;
       this.dragManager.startDrag(e, state, 'group');
     });
   }

package/src/index.ts

@@ -48,6 +48,7 @@ export {
   createPanelElement,
   createPanelState,
   toggleCollapse,
+  togglePin,
   showPanel,
   hidePanel,
   setPanelPosition,
@@ -59,6 +60,7 @@ export {
 } from './Panel';
 export {
   getConnectedGroup,
+  getMovingGroupRespectingPins,
   detachFromGroup,
   findSnapTarget,
   snapPanelsToTarget,
@@ -103,6 +105,7 @@ export type {
   PanelSnapEvent,
   AnchorSnapEvent,
   PanelDetachedEvent,
+  PanelPinEvent,
   PanelCollapseEvent,
   PanelShowEvent,
   PanelHideEvent,

package/src/types.ts

@@ -57,6 +57,8 @@ export interface PanelConfig {
   title?: string;
   /** Initial width (default: 300) */
   width?: number;
+  /** Initial pin state (default: false) */
+  startPinned?: boolean;
   /** Initial collapsed state (default: true) */
   startCollapsed?: boolean;
   /** Initial position (optional - will be auto-positioned if not provided) */
@@ -67,12 +69,16 @@ export interface PanelConfig {
   element?: HTMLDivElement;
   /** Custom drag handle element */
   dragHandle?: HTMLDivElement;
+  /** Custom pin button element */
+  pinButton?: HTMLButtonElement;
   /** Custom collapse button element */
   collapseButton?: HTMLButtonElement;
   /** Custom content wrapper element */
   contentWrapper?: HTMLDivElement;
   /** Custom detach grip element */
   detachGrip?: HTMLDivElement;
+  /** Whether panel can be pinned (default: false) */
+  pinnable?: boolean;
   /** Whether panel can be collapsed (default: true) */
   collapsible?: boolean;
   /** Whether panel can be detached from group (default: true) */
@@ -126,12 +132,16 @@ export interface PanelState {
   element: HTMLDivElement;
   /** Drag handle element */
   dragHandle: HTMLDivElement;
+  /** Pin button element (if pinable) */
+  pinButton: HTMLButtonElement | null;
   /** Collapse button element (if collapsible) */
   collapseButton: HTMLButtonElement | null;
   /** Content wrapper element */
   contentWrapper: HTMLDivElement;
   /** Detach grip element (if detachable) */
   detachGrip: HTMLDivElement | null;
+  /** Whether panel is currently pinned */
+  isPinned: boolean;
   /** Whether panel is currently collapsed */
   isCollapsed: boolean;
   /** ID of panel this is snapped to on its right (outgoing link) */
@@ -254,6 +264,8 @@ export interface TabManagerEvents {
   'snap:anchor': AnchorSnapEvent;
   /** Fired when a panel is detached from group */
   'panel:detached': PanelDetachedEvent;
+  /** Fired when panel pin state changes */
+  'panel:pin': PanelPinEvent;
   /** Fired when panel collapse state changes */
   'panel:collapse': PanelCollapseEvent;
   /** Fired when a panel becomes visible (auto-hide) */
@@ -306,6 +318,11 @@ export interface PanelDetachedEvent {
   previousGroup: PanelState[];
 }
 
+export interface PanelPinEvent {
+  panel: PanelState;
+  isPinned: boolean;
+}
+
 export interface PanelCollapseEvent {
   panel: PanelState;
   isCollapsed: boolean;
@@ -338,6 +355,7 @@ export interface CSSClasses {
   panelContent: string;
   panelContentCollapsed: string;
   detachGrip: string;
+  pinButton: string;
   collapseButton: string;
   snapPreview: string;
   snapPreviewVisible: string;