comins-table 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## 0.1.9 - 2026-08-31
+
+- Added the packaged `DESIGN.md`, componentization guidance, a canonical Feature Manifest, full public-export and CSS-token classification, structured feature restrictions, and annotated/typechecked documentation examples.
+- Added Ctrl/Cmd discontiguous Cell selection while preserving the active Cell and rectangular range contracts, plus Row Drag lifecycle callbacks for before-start cancellation, semantic target changes, and final moved/cancelled/rejected results.
+- Preserved the last known Column order when dynamic Header Group Columns are hidden and restored, kept Row Group content visible during horizontally pinned scrolling, and connected Header Group and Rows Playground drag examples to controlled data and lifecycle feedback.
+- Standardized Playground toggle contrast, added deterministic collapse-all-Details coverage, and retained the existing Summary Row visible-column `colSpan` contract and example.
+- Added localized event and method reference tables above related Playground examples.
+- Clarified the browser compatibility contract versus Chromium-only automated evidence and expanded documentation/package gates so unclassified exports, tokens, examples, restrictions, or missing packaged design guidance fail closed.
+
+## 0.1.8 - 2026-08-28
+
+- Added responsive left/right Column Pinning for leaf Columns and atomic Header Groups, including persisted pin intent, position locking, resize-aware sticky offsets, wider-side inner-block demotion with a 48px center budget, opaque Header/Body/Skeleton/Summary surfaces, and Summary `colSpan` zone splitting while keeping full-width structural Rows non-sticky.
+- Added application-created Cross-Table Drag Coordinators for flat and grouped Rows and complete Group bundles, target-owned permission and reject/overwrite conflict callbacks, persistent empty Groups, immutable atomic source/target results, destination focus recovery, duplicate registration fail-closed behavior, and target-only vertical edge auto-scroll.
+- Added matching Korean/English Playground routes and public guides for Column Pinning and Cross-Table Row/Group Drag, including model ownership, supported combinations, destructive overwrite semantics, layout persistence, and responsive behavior.
+- Added non-blocking pointer-adjacent `Duplicate ID` rejection feedback with a reusable internal Tooltip Surface, restrained target outline, viewport collision handling, accessible live status, renderer/duration/disable controls, CSS theme tokens, and structured `onTransferRejected` notifications.
+- Corrected the Column Pinning Playground to guarantee observable horizontal overflow, and capped direct resize of effective pinned Columns and Header Groups at the 48px center budget so the active pinned surface no longer demotes beneath scrolling content.
+- Moved the single native horizontal scrollbar to the bottom of the complete Table, after Summary when configured, while preserving Body wheel input, vertical virtualization, synchronized Header/Body/Summary scrolling, and a visible final Row boundary when native scrollbar chrome auto-hides.
+- Corrected the bottom scrollbar range to use the Body's actual horizontal viewport width across native scrollbar layouts, so direct rail input reaches the final horizontal content without desynchronizing Header, Body, or Summary.
+
 ## 0.1.7 - 2026-08-27
 
 - Added controlled client-side Column Filtering with text, number, UTC calendar-day date, and boolean operators; application-owned Filter/open-popover state; semantic Header controls; filtered sorting, pagination, virtualization, Summary, and Row Grouping projection; explicit Group preservation; Row Drag and remote/Tree exclusions; and matching Korean/English Playground documentation.

package/DESIGN.md

@@ -0,0 +1,132 @@
+# Comins Table Design Contract
+
+Comins Table uses a restrained, data-first visual language. The application owns business meaning and data; the Table owns structural clarity, interaction feedback, focus visibility, and consistent state treatment. This document describes the public styling contract shipped with the package stylesheet.
+
+## Principles
+
+- Preserve density without hiding structure: borders, pinned boundaries, Group Rows, Details, and Summary remain distinguishable.
+- Use color to communicate state, not decoration. Selection and valid actions use the accent family; invalid and rejected drops use the danger family.
+- Keep focus visible independently from hover and selection.
+- Keep application overrides local. Importing `comins-table/styles.css` does not install a global reset.
+- Prefer container-driven behavior. Horizontal overflow, responsive pin demotion, and compact density respond to the Table container rather than the browser viewport.
+
+The default stylesheet targets light surfaces. The built-in dark theme supplies its own values. Applications that replace surface tokens are responsible for maintaining readable foreground, border, focus, disabled, and drag-feedback contrast.
+
+## Foundations
+
+Typography inherits the application font. Default text is compact, with Header and control labels using stronger weight rather than larger type. Spacing is based on Cell padding and Row/Header height tokens. Borders are one CSS pixel except for focus, selection, and drop indicators. The outer frame uses a small radius; internal Rows remain square so adjacent borders align.
+
+Motion is limited to short color, opacity, position, and resize feedback. Motion must not delay a model update or hide the final state. Overlays, menus, and Tooltip surfaces render above pinned content; application portals remain application-owned unless a documented Table component explicitly owns the portal.
+
+## Surfaces and states
+
+| Surface | Contract |
+| --- | --- |
+| Frame | Owns the outer border, radius, background, and the final horizontal scrollbar. |
+| Header | Uses an accent surface by default and retains visible focus, resize, sort, move, and pinned boundaries. |
+| Body Cell | Keeps grid borders and application Row backgrounds visible beneath selection indicators. |
+| Group Row | Uses one semantic full-width Cell. Its content remains visible at the Body viewport start during horizontal scrolling. |
+| Detail Row | Follows its owner Row and remains outside Cell selection and Clipboard addressing. |
+| Summary | Uses the same Column geometry and pin zones as Header and Body and remains above the final scrollbar. |
+| Tooltip | Is non-blocking drag feedback with `pointer-events: none`; it does not replace application Toasts or error handling. |
+
+Rest, hover, active, `focus-visible`, selected, disabled, loading, invalid, drag-source, valid-drop, and rejected-drop states must remain visually distinct. A custom renderer may change inner content but must not remove the owning semantic Cell, focus behavior, disabled state, or interaction feedback unless the corresponding public contract explicitly delegates those responsibilities.
+
+## Density and responsive behavior
+
+`theme.density` selects the built-in Row and Header measurements. Applications may override the documented height and padding tokens, but fixed-height virtualization still requires the resolved `rowHeight` contract to match the logical Row height. Pinned zones preserve a center-content budget and may demote inner pinned blocks when the container becomes too narrow; this is a rendering decision and does not change persisted pin intent.
+
+## CSS token stability
+
+The canonical machine-readable inventory is `docs/feature-manifest.json`. Stability means:
+
+- `public-stable`: supported theme input. Removal or incompatible meaning requires a breaking release.
+- `public-experimental`: available for advanced styling, but name or behavior may change in a minor release with CHANGELOG notice.
+- `internal`: implementation plumbing. Do not override it in application styles.
+
+### Public stable
+
+```text
+--comins-table-accent
+--comins-table-accent-foreground
+--comins-table-accent-soft
+--comins-table-background
+--comins-table-border
+--comins-table-cell-border
+--comins-table-cell-height
+--comins-table-focus
+--comins-table-foreground
+--comins-table-group-row-background
+--comins-table-group-row-color
+--comins-table-header-background
+--comins-table-header-border
+--comins-table-header-color
+--comins-table-header-split-border
+--comins-table-range-background
+--comins-table-row-border
+--comins-table-row-disabled-background
+--comins-table-row-disabled-color
+--comins-table-row-even-background
+--comins-table-row-height
+--comins-table-row-odd-background
+--comins-table-row-selected-background
+--comins-table-scrollbar-corner
+--comins-table-scrollbar-thumb
+--comins-table-scrollbar-track
+--comins-table-tooltip-danger-background
+--comins-table-tooltip-danger-border
+--comins-table-tooltip-danger-color
+--comins-table-tooltip-danger-muted
+--comins-table-tooltip-shadow
+```
+
+### Public experimental
+
+```text
+--comins-table-accent-strong
+--comins-table-cell-background
+--comins-table-cell-color
+--comins-table-cell-padding-x
+--comins-table-cell-padding-y
+--comins-table-component-accent
+--comins-table-component-accent-foreground
+--comins-table-component-accent-soft
+--comins-table-component-accent-strong
+--comins-table-component-border
+--comins-table-component-button-foreground
+--comins-table-component-focus
+--comins-table-component-foreground
+--comins-table-component-muted
+--comins-table-component-surface
+--comins-table-component-surface-muted
+--comins-table-component-virtual-list-height
+--comins-table-detail-background
+--comins-table-detail-border
+--comins-table-detail-padding
+--comins-table-drop-invalid
+--comins-table-drop-invalid-background
+--comins-table-drop-marker
+--comins-table-drop-valid
+--comins-table-drop-valid-background
+--comins-table-header-height
+--comins-table-muted
+--comins-table-resize-handle
+--comins-table-selected-range-background
+--comins-table-skeleton-background
+--comins-table-skeleton-highlight
+--comins-table-surface
+--comins-table-surface-muted
+--comins-table-virtual-list-item-height
+```
+
+### Internal
+
+```text
+--comins-table-row-custom-background
+```
+
+Stable tokens inherit through the Table root and use the current theme value as their fallback. Experimental component and structural tokens fall back to the related stable accent, surface, foreground, border, or resolved Row geometry. Internal tokens have no compatibility guarantee.
+
+## Extension choice
+
+Use a formatter for value presentation, a renderer for typed React content, a built-in component when the Table must own interaction isolation and accessibility, a CSS token for reusable visual policy, and `className`/`style` for one application instance or business state. See the [componentization guide](https://github.com/kim1124/comins-table/blob/main/docs/design/componentization.md) for the full decision contract.

package/README.md

@@ -1,13 +1,13 @@
 # Comins Table
 
-Comins Table is a controlled React data table for data-heavy application screens, with virtualized rendering, precise selection, movable headers, controlled Column Filtering, Row Grouping and Row Expand Details, Summary Row aggregation, Tree Grid data, built-in component cells, and framework-independent core helpers.
+Comins Table is a controlled React data table for data-heavy application screens. Applications keep ownership of their data and business models while the Table provides virtualized rendering, structured Rows, configurable Headers, precise selection, and customizable cells.
 
 [![npm version](https://img.shields.io/npm/v/comins-table)](https://www.npmjs.com/package/comins-table)
 [![TypeScript declarations](https://img.shields.io/npm/types/comins-table)](https://www.npmjs.com/package/comins-table)
 [![Verify](https://github.com/kim1124/comins-table/actions/workflows/verify.yml/badge.svg?branch=main)](https://github.com/kim1124/comins-table/actions/workflows/verify.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-![Comins Table sorting, column reorder, Row selection, Summary Row, and Tree Grid demo](https://raw.githubusercontent.com/kim1124/comins-table/main/docs/assets/comins-table-demo.gif)
+![Comins Table controlled Rows, Column Pinning, Row Grouping, Filtering, Tree Grid, and Cross-Table Drag overview](https://raw.githubusercontent.com/kim1124/comins-table/main/docs/assets/comins-table-overview.gif)
 
 ## Why Comins Table
 
@@ -15,12 +15,26 @@ Comins Table is a controlled React data table for data-heavy application screens
 | --- | --- |
 | Controlled data | Application-owned `data`, CRUD helpers, `onChangeData`, pagination, sorting, and layout callbacks |
 | Rendering and scale | Fixed-height virtualization with a tested 100,000-row route, infinite scroll, append-mode lazy loading, loading, and empty states |
-| Interaction | Accessible single and opt-in multi-column Header sorting, controlled Column Filtering, resize, 6-pixel horizontal column reorder with source placeholder, Row and Cell selection, ranges, clipboard, and context menu callbacks |
+| Interaction | Accessible single and opt-in multi-column Header sorting, controlled Column Filtering, resize, responsive Column Pinning, 6-pixel horizontal column reorder, Cross-Table Row/Group Drag, Row and Cell selection, ranges, clipboard, and context menu callbacks |
 | Data structure | Controlled client-side flat Row Grouping, flat Row Expand Details, Summary Row aggregation, and controlled Tree Grid expand/fold |
 | Custom UI | Cell/Header renderers, built-in button/input/checkbox/radio/select/toggle/progress/menu/Virtual List components, and CSS-variable themes |
 
 Comins Table is standalone and does not wrap another table or grid implementation.
 
+### Feature catalog
+
+This catalog is a consumer-oriented summary, not the complete status registry. Use the [Canonical Feature Manifest](https://github.com/kim1124/comins-table/blob/main/docs/feature-manifest.json) and the language indexes for every shipped, unsupported, and evidence-linked feature.
+
+| Area | Shipped capabilities | Live examples | Guides |
+| --- | --- | --- | --- |
+| Getting started | Controlled data, CRUD, Core state, loading, and empty states | [`Getting Started`](http://127.0.0.1:4002/docs/getting-started), [`CRUD`](http://127.0.0.1:4002/examples/crud) | [Quick Start](https://github.com/kim1124/comins-table/blob/main/docs/user/01-quick-start.md), [Data And CRUD](https://github.com/kim1124/comins-table/blob/main/docs/user/02-data-and-crud.md) |
+| Header and layout | Sort, multi-sort, resize, move, Header Groups, Filtering, and Pinning | [`Header`](http://127.0.0.1:4002/examples/header), [`Filtering`](http://127.0.0.1:4002/examples/column-filtering), [`Pinning`](http://127.0.0.1:4002/examples/column-pinning) | [Header](https://github.com/kim1124/comins-table/blob/main/docs/user/06-header.md), [Filtering](https://github.com/kim1124/comins-table/blob/main/docs/user/21-column-filtering.md), [Pinning](https://github.com/kim1124/comins-table/blob/main/docs/user/22-column-pinning.md) |
+| Rows, cells, and selection | Row and Cell callbacks, selection, Clipboard, Context Menu, and Row Expand | [`Selection`](http://127.0.0.1:4002/examples/selection-clipboard), [`Row Expand`](http://127.0.0.1:4002/examples/row-expand) | [Row](https://github.com/kim1124/comins-table/blob/main/docs/user/07-row.md), [Cell](https://github.com/kim1124/comins-table/blob/main/docs/user/08-cell.md), [Selection](https://github.com/kim1124/comins-table/blob/main/docs/user/10-selection.md) |
+| Structured rows | Summary Row, Tree Grid, Row Grouping, and Cross-Table Row/Group Drag | [`Summary`](http://127.0.0.1:4002/examples/summary-row), [`Tree`](http://127.0.0.1:4002/examples/tree-grid), [`Grouping`](http://127.0.0.1:4002/examples/row-grouping), [`Transfer`](http://127.0.0.1:4002/examples/cross-table-drag) | [Summary](https://github.com/kim1124/comins-table/blob/main/docs/user/18-summary-row.md), [Tree](https://github.com/kim1124/comins-table/blob/main/docs/user/17-tree-grid.md), [Grouping](https://github.com/kim1124/comins-table/blob/main/docs/user/20-row-grouping.md), [Transfer](https://github.com/kim1124/comins-table/blob/main/docs/user/23-cross-table-drag.md) |
+| Loading and performance | Pagination, fixed-height virtualization, Infinite Scroll, and Lazy Load | [`Pagination`](http://127.0.0.1:4002/performance/pagination), [`Virtualization`](http://127.0.0.1:4002/performance/virtualization) | [Pagination](https://github.com/kim1124/comins-table/blob/main/docs/user/05-pagination.md), [Virtualization](https://github.com/kim1124/comins-table/blob/main/docs/user/11-virtualization.md), [Lazy Load](https://github.com/kim1124/comins-table/blob/main/docs/user/16-lazy-load.md) |
+| Rendering and styling | Built-in components, custom renderers, themes, CSS variables, and export helpers | [`Components`](http://127.0.0.1:4002/examples/component), [`Theme`](http://127.0.0.1:4002/examples/theme), [`Export`](http://127.0.0.1:4002/examples/export) | [Cell](https://github.com/kim1124/comins-table/blob/main/docs/user/08-cell.md), [Styling](https://github.com/kim1124/comins-table/blob/main/docs/user/04-styling.md), [Export](https://github.com/kim1124/comins-table/blob/main/docs/user/14-export.md) |
+| API and utilities | Ref controls, framework-independent Core helpers, Clipboard, and selection helpers | [`Ref API`](http://127.0.0.1:4002/api/ref), [`Props`](http://127.0.0.1:4002/api/props) | [Core State](https://github.com/kim1124/comins-table/blob/main/docs/user/03-core-state.md), [Clipboard](https://github.com/kim1124/comins-table/blob/main/docs/user/09-clipboard.md) |
+
 ## Support
 
 | Surface | Support |
@@ -34,12 +48,15 @@ Comins Table is standalone and does not wrap another table or grid implementatio
 | SSR | Client boundary required; server rendering is not currently supported |
 | Runtime network behavior | No package-owned requests, remote assets, telemetry, or error reporting |
 
+The Chrome and Edge row is the compatibility contract. The automated browser gate is evidence from Playwright-bundled Chromium only; it is not a claim that Firefox, Safari, or every installed Edge build was tested.
+
 ## Installation
 
 ```bash
 npm install comins-table react react-dom
 ```
 
+<!-- comins-doc-example: fragment -->
 ```tsx
 import { CominsTable, type CominsTableColumn } from "comins-table";
 import "comins-table/styles.css";
@@ -47,8 +64,22 @@ import "comins-table/styles.css";
 
 React and React DOM are peer dependencies. Import `comins-table/styles.css` when the default table shell, themes, and built-in component skin are required.
 
+### Run the Playground locally
+
+The Playground is a repository development server, not a command installed into a consumer application.
+
+```bash
+git clone https://github.com/kim1124/comins-table.git
+cd comins-table
+npm ci
+npm run dev
+```
+
+Open [`http://127.0.0.1:4002/docs/getting-started`](http://127.0.0.1:4002/docs/getting-started).
+
 ## Quick Start
 
+<!-- comins-doc-example: fragment -->
 ```tsx
 import { useState } from "react";
 import { CominsTable, type CominsTableColumn } from "comins-table";
@@ -107,6 +138,7 @@ Where restoration is supported, use the supported Ref API: `setSelectedRow` and
 
 Set `multiSort` to opt into ordered multi-column sorting. Normal Header click or `Enter`/`Space` keeps single sorting; hold `Shift` while using the same input to add, update, or remove one rule without replacing the others. Active Headers display their 1-based priority.
 
+<!-- comins-doc-example: fragment -->
 ```tsx
 <CominsTable
   columns={columns}
@@ -136,16 +168,25 @@ A left-button mouse interaction activates column movement after a 6-pixel horizo
 
 Use `getColumnLayout()` and `setColumnLayout()` through the Ref API, or `serializeCominsColumnLayout()` and `applyCominsColumnLayout()` from `comins-table/core`, to persist and restore order, widths, and visibility.
 
+### Column Pinning
+
+Set `pinned: "left"` or `pinned: "right"` on a Column or Header Group to keep its atomic block visible during horizontal scrolling and lock its configured position. Direct resize of an effective pinned block stops before it would consume the 48px center budget and demote itself; independent container resize can still temporarily demote inner pinned blocks without changing the persisted layout intent. Header, Body, Skeleton, and Summary use the same offsets. Group Rows and Row Details remain full-width spanning cells; Row Group inner content stays visible at the Body viewport start while horizontally scrolling. See the [Column Pinning guide](https://github.com/kim1124/comins-table/blob/main/docs/user/22-column-pinning.md) and [`/examples/column-pinning`](http://127.0.0.1:4002/examples/column-pinning).
+
+When columns overflow horizontally, Comins Table renders one native horizontal scrollbar at the bottom of the complete Table. A configured Summary Row stays above that scrollbar, while Body trackpad or Shift-wheel input and direct scrollbar input keep Header, Body, and Summary `scrollLeft` synchronized.
+
 ## Rows, Cells, And Selection
 
 Rows expose click, double-click, keyboard, and context-menu callbacks. Cells expose the corresponding Cell callbacks plus `format`, `renderer`, and props hooks.
 
-A normal Row interaction selects one Row, `Ctrl`/`Cmd` toggles a Row, and `Shift` extends the visible Row range from the selection anchor. Cell selection supports a single Cell, `Ctrl`/`Cmd` multi-selection, and `Shift` or pointer-drag ranges. Built-in component interactions remain isolated from `onClickCell` and `onClickRow` callback payloads so component actions do not also trigger the owning Cell or Row action.
+A normal Row interaction selects one Row, `Ctrl`/`Cmd` toggles a Row, and `Shift` extends the visible Row range from the selection anchor. Cell selection supports a single Cell, visible `Ctrl`/`Cmd` discontiguous selection, and `Shift` or pointer-drag rectangular ranges. `CominsSelectionState.cell` remains the active Clipboard address while `cells` records the discontiguous set; 0.1.9 does not copy that set as a Clipboard matrix. Built-in component interactions remain isolated from `onClickCell` and `onClickRow` callback payloads so component actions do not also trigger the owning Cell or Row action.
+
+Row Drag exposes `onBeforeRowDrag`, `onRowDrag`, and `onAfterDragRow`. The before callback can cancel prior to listener registration, target updates emit only on identity or validity changes, and the after callback reports one `moved`, `cancelled`, or `rejected` result per started gesture. Data changes remain controlled through `onChangeData` or the Cross-Table Coordinator.
 
 ### Row Expand
 
 See the [Row Expand guide](https://github.com/kim1124/comins-table/blob/main/docs/user/19-row-expand.md) and run the [`/examples/row-expand`](http://127.0.0.1:4002/examples/row-expand) Playground route.
 
+<!-- comins-doc-example: fragment -->
 ```tsx
 const [expandedRowIds, setExpandedRowIds] = useState<readonly string[]>([]);
 
@@ -174,6 +215,16 @@ Each synthetic Group Row is one full-width colspan Cell with a distinct neutral-
 
 Synthetic Group Rows never masquerade as `TData`: ordinary Row/Cell callbacks, selection, Clipboard, Cell renderers, formatters, and Row Detail remain leaf-only. Row Grouping supports fixed-height virtualization and grouped leaf Row Detail, but cannot be combined with pagination, infinite/lazy loading, or Tree Grid. Multi-depth grouping remains deferred.
 
+## Cross-Table Row And Group Drag
+
+See the [Cross-Table Drag guide](https://github.com/kim1124/comins-table/blob/main/docs/user/23-cross-table-drag.md) and run the [`/examples/cross-table-drag`](http://127.0.0.1:4002/examples/cross-table-drag) Playground route.
+
+Create a `createCominsTableTransferCoordinator()` and pass the same Coordinator, `scope`, and unique `tableId` through `tableTransfer` to participating Tables. Existing Row Drag moves one Row between compatible flat or grouped Tables. Group Drag moves the Group plus every member Row; moving the last Row preserves the empty source Group, while moving a Group removes it from the source model.
+
+Duplicate IDs reject by default. A rejected duplicate displays a post-drop, pointer-adjacent `Duplicate ID` Tooltip and a restrained target Table outline without intercepting pointer events. The target can replace the Tooltip body through `rejectionFeedback.renderTooltip`, change its duration, disable default feedback, and customize its CSS variables. `Coordinator.onTransferRejected` receives the structured duplicate conflict for application Toasts or logging.
+
+The target can reject through `canTransfer` or explicitly return `"overwrite"` from `resolveConflict`; Group overwrite replaces the complete target Group bundle and never merges it. The Coordinator emits one immutable source/target result, and the application applies both controlled models atomically. Cross-Table Transfer is unavailable with Tree Grid, Column Filtering, Infinite Scroll, and Lazy Load.
+
 ## Column Filtering
 
 See the [Column Filtering guide](https://github.com/kim1124/comins-table/blob/main/docs/user/21-column-filtering.md) and run the [`/examples/column-filtering`](http://127.0.0.1:4002/examples/column-filtering) Playground route.
@@ -222,8 +273,11 @@ The package stylesheet exposes module-local `--comins-table-*` CSS variables and
 
 Use `theme.className`, `theme.style`, Row and Group Row class/style hooks, Cell props, and renderer output for application-specific presentation. Keep virtualized `rowHeight` aligned with `--comins-table-row-height` when overriding height tokens.
 
+The [Design Contract](https://github.com/kim1124/comins-table/blob/main/DESIGN.md) classifies every Table token as public stable, public experimental, or internal. The [Componentization Guide](https://github.com/kim1124/comins-table/blob/main/docs/design/componentization.md) defines when to use a formatter, renderer, built-in component, future typed slot, token, or instance override.
+
 ## Ref API
 
+<!-- comins-doc-example: fragment -->
 ```tsx
 const tableRef = useRef<CominsTableRef<UserRow>>(null);
 
@@ -250,15 +304,11 @@ tableRef.current?.fold(); // all Tree Grid branches
 
 ## Playground
 
-```bash
-npm run dev
-```
-
-The local Playground starts at [`/docs/getting-started`](http://127.0.0.1:4002/docs/getting-started). Key routes include [`/examples/selection-clipboard`](http://127.0.0.1:4002/examples/selection-clipboard), [`/examples/row-expand`](http://127.0.0.1:4002/examples/row-expand), [`/examples/row-grouping`](http://127.0.0.1:4002/examples/row-grouping), [`/examples/column-filtering`](http://127.0.0.1:4002/examples/column-filtering), [`/examples/summary-row`](http://127.0.0.1:4002/examples/summary-row), [`/examples/tree-grid`](http://127.0.0.1:4002/examples/tree-grid), [`/examples/component`](http://127.0.0.1:4002/examples/component), and [`/performance/virtualization`](http://127.0.0.1:4002/performance/virtualization).
+After the repository setup under Installation, the local Playground starts at [`/docs/getting-started`](http://127.0.0.1:4002/docs/getting-started). Key routes include [`/examples/selection-clipboard`](http://127.0.0.1:4002/examples/selection-clipboard), [`/examples/row-expand`](http://127.0.0.1:4002/examples/row-expand), [`/examples/row-grouping`](http://127.0.0.1:4002/examples/row-grouping), [`/examples/column-filtering`](http://127.0.0.1:4002/examples/column-filtering), [`/examples/column-pinning`](http://127.0.0.1:4002/examples/column-pinning), [`/examples/cross-table-drag`](http://127.0.0.1:4002/examples/cross-table-drag), [`/examples/summary-row`](http://127.0.0.1:4002/examples/summary-row), [`/examples/tree-grid`](http://127.0.0.1:4002/examples/tree-grid), [`/examples/component`](http://127.0.0.1:4002/examples/component), and [`/performance/virtualization`](http://127.0.0.1:4002/performance/virtualization).
 
 ## Documentation
 
-Start with the [English Quick Start](https://github.com/kim1124/comins-table/blob/main/docs/user/01-quick-start.md), then browse [all English feature guides](https://github.com/kim1124/comins-table/tree/main/docs/user). The detailed [Tree Grid](https://github.com/kim1124/comins-table/blob/main/docs/user/17-tree-grid.md), [Summary Row](https://github.com/kim1124/comins-table/blob/main/docs/user/18-summary-row.md), [Row Expand](https://github.com/kim1124/comins-table/blob/main/docs/user/19-row-expand.md), [Row Grouping](https://github.com/kim1124/comins-table/blob/main/docs/user/20-row-grouping.md), and [Column Filtering](https://github.com/kim1124/comins-table/blob/main/docs/user/21-column-filtering.md) contracts include runnable examples and edge cases. [Korean guides](https://github.com/kim1124/comins-table/tree/main/docs/ko) are retained as secondary documentation.
+Start with the [English Quick Start](https://github.com/kim1124/comins-table/blob/main/docs/user/01-quick-start.md), [documentation index](https://github.com/kim1124/comins-table/blob/main/docs/README.md), [English feature guides](https://github.com/kim1124/comins-table/blob/main/docs/user/README.md), or [Korean feature guides](https://github.com/kim1124/comins-table/blob/main/docs/ko/README.md). Use the [Design Contract](https://github.com/kim1124/comins-table/blob/main/DESIGN.md), [Componentization Guide](https://github.com/kim1124/comins-table/blob/main/docs/design/componentization.md), and [Canonical Feature Manifest](https://github.com/kim1124/comins-table/blob/main/docs/feature-manifest.json) for visual stability, extension ownership, complete feature status, and evidence mapping. Each category links the detailed usage contract, runnable Playground route, related features, and the matching guide in the other language.
 
 Use the [source repository](https://github.com/kim1124/comins-table) for development context, review the [changelog](https://github.com/kim1124/comins-table/blob/main/CHANGELOG.md) for version history, and follow the [security policy](https://github.com/kim1124/comins-table/blob/main/SECURITY.md) for vulnerability reporting.
 
@@ -281,7 +331,7 @@ npm run verify
 npm run docs:readme-gif
 ```
 
-`npm run docs:readme-gif` is a maintainer command that captures the real hidden Playground fixture and regenerates the checked-in README animation.
+`npm run docs:readme-gif` is a maintainer command that captures the real hidden Playground fixtures and regenerates the overview animation plus four detailed feature animations.
 
 ## Trusted Publishing
 

package/dist/clipboard.js

@@ -1,2 +1,2 @@
-import { copyCominsCell as e, copyCominsCellRange as t, copyCominsRow as n, fillCominsCellRange as r, pasteCominsCell as i, pasteCominsCellRange as a, pasteCominsRow as o } from "./core.js";
-export { e as copyCominsCell, t as copyCominsCellRange, n as copyCominsRow, r as fillCominsCellRange, i as pasteCominsCell, a as pasteCominsCellRange, o as pasteCominsRow };
+import { M as e, N as t, P as n, c as r, o as i, p as a, s as o } from "./core-D01wEe-7.js";
+export { i as copyCominsCell, o as copyCominsCellRange, r as copyCominsRow, a as fillCominsCellRange, e as pasteCominsCell, t as pasteCominsCellRange, n as pasteCominsRow };

package/dist/column-pinning.d.ts

@@ -0,0 +1,25 @@
+export type CominsColumnPinned = "left" | "right";
+export type CominsColumnPinningBlock = {
+    columnIds: readonly string[];
+    columnWidths: readonly number[];
+    id: string;
+    pinned?: CominsColumnPinned;
+};
+export type CominsResolvedPinnedColumn = {
+    boundary?: boolean;
+    offset?: number;
+    pinned?: CominsColumnPinned;
+};
+export type CominsResolvedColumnPinning = {
+    columns: ReadonlyMap<string, CominsResolvedPinnedColumn>;
+    orderedColumnIds: readonly string[];
+};
+export type CominsColumnPinningSpanFragment = CominsResolvedPinnedColumn & {
+    colSpan: number;
+    startIndex: number;
+};
+export declare function normalizeCominsColumnPinned(value: unknown): CominsColumnPinned | undefined;
+export declare function resolveCominsColumnPinning(blocks: readonly CominsColumnPinningBlock[], containerWidth: number): CominsResolvedColumnPinning;
+export declare function getCominsPinnedBlockResizeMaxWidth(blocks: readonly CominsColumnPinningBlock[], resolved: CominsResolvedColumnPinning, blockId: string, containerWidth: number, minimumCenterWidth?: number): number | undefined;
+export declare function getCominsColumnPinningSpanFragments(resolved: CominsResolvedColumnPinning, startIndex: number, colSpan: number): CominsColumnPinningSpanFragment[];
+//# sourceMappingURL=column-pinning.d.ts.map

package/dist/column-pinning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-pinning.d.ts","sourceRoot":"","sources":["../src/column-pinning.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,CAAC;AAElD,MAAM,MAAM,wBAAwB,GAAG;IACrC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,kBAAkB,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,kBAAkB,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;IACzD,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG,0BAA0B,GAAG;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CAE1F;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,wBAAwB,EAAE,EAC3C,cAAc,EAAE,MAAM,GACrB,2BAA2B,CAoF7B;AAED,wBAAgB,kCAAkC,CAChD,MAAM,EAAE,SAAS,wBAAwB,EAAE,EAC3C,QAAQ,EAAE,2BAA2B,EACrC,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,kBAAkB,SAAK,GACtB,MAAM,GAAG,SAAS,CA+BpB;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,2BAA2B,EACrC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,+BAA+B,EAAE,CA+BnC"}