virtual-tree-canvas 0.7.0 → 0.7.2

package/src/core/view-options.js

@@ -1,37 +1,110 @@
 import { resolveTheme } from './theme-manager.js';
-/** Supported TreeView configuration options and defaults. */
+
+/**
+ * Supported TreeView configuration options and defaults.
+ */
 export const treeViewDefaults = Object.freeze({
-  mode: 'tree', presentation: 'pane', nodes: Object.freeze([]), model: null, meta: null,
-  columns: null, theme: 'dark', flatRoot: true, enforceMeta: false,
-  filter: true, filterPlacement: 'auto', markUpdated: true, editable: true,
-  rowActions: Object.freeze([]), rowDrag: null, rowReorder: false, initialExpandDepth: 1, rowHeight: undefined,
-  indentWidth: undefined, showHeader: true, headerHeight: 28, iconResolver: null, fontFamily: null,
+  mode: 'tree',
+  presentation: 'pane',
+  nodes: Object.freeze([]),
+  model: null,
+  meta: null,
+  columns: null,
+  theme: 'dark',
+  flatRoot: true,
+  enforceMeta: false,
+  filter: true,
+  filterPlacement: 'auto',
+  markUpdated: true,
+  editable: true,
+  rowActions: Object.freeze([]),
+  rowDrag: null,
+  rowReorder: false,
+  initialExpandDepth: 1,
+  rowHeight: undefined,
+  indentWidth: undefined,
+  showHeader: true,
+  headerHeight: 28,
+  iconResolver: null,
+  fontFamily: null
 });
 export const treeViewOptionNames = Object.freeze(Object.keys(treeViewDefaults));
 
 export function validateTreeViewOptions(options) {
-  if (!options || typeof options !== 'object' || Array.isArray(options)) throw new TypeError('Options must be an object');
+  if (!options || typeof options !== 'object' || Array.isArray(options))
+    throw new TypeError('Options must be an object');
   for (const [key, value] of Object.entries(options)) {
-    if (key === 'rowActions' && (!Array.isArray(value) || value.some(action => !action || typeof action.id !== 'string' || !action.id || typeof action.label !== 'string') || new Set(value.map(action => action.id)).size !== value.length)) throw new TypeError('rowActions requires unique ids and labels');
-    if (key === 'rowActions') for (const action of value) {
-      if (action.kind !== undefined && !['button','checkbox'].includes(action.kind)) throw new TypeError('row action kind must be button or checkbox');
-      for (const property of ['visible', 'disabled', 'pressed', 'checked']) if (action[property] !== undefined && !['boolean', 'function'].includes(typeof action[property])) throw new TypeError(`${property} must be boolean or a function`);
-      if (action.icon !== undefined && !['string', 'function'].includes(typeof action.icon)) throw new TypeError('action icon must be a name or a function');
-    }
-    if (key === 'rowDrag' && value !== null && typeof value !== 'function') throw new TypeError('rowDrag must be a function or null');
+    if (
+      key === 'rowActions' &&
+      (!Array.isArray(value) ||
+        value.some(
+          (action) =>
+            !action ||
+            typeof action.id !== 'string' ||
+            !action.id ||
+            typeof action.label !== 'string'
+        ) ||
+        new Set(value.map((action) => action.id)).size !== value.length)
+    )
+      throw new TypeError('rowActions requires unique ids and labels');
+    if (key === 'rowActions')
+      for (const action of value) {
+        if (action.kind !== undefined && !['button', 'checkbox'].includes(action.kind))
+          throw new TypeError('row action kind must be button or checkbox');
+        for (const property of ['visible', 'disabled', 'pressed', 'checked'])
+          if (
+            action[property] !== undefined &&
+            !['boolean', 'function'].includes(typeof action[property])
+          )
+            throw new TypeError(`${property} must be boolean or a function`);
+        if (action.icon !== undefined && !['string', 'function'].includes(typeof action.icon))
+          throw new TypeError('action icon must be a name or a function');
+      }
+    if (key === 'rowDrag' && value !== null && typeof value !== 'function')
+      throw new TypeError('rowDrag must be a function or null');
     if (key === 'theme') resolveTheme(value);
-    if (key === 'mode' && !['tree', 'inspector'].includes(value)) throw new TypeError('mode must be tree or inspector');
-    if (key === 'presentation' && !['pane', 'table'].includes(value)) throw new TypeError('presentation must be pane or table');
-    if (key === 'filterPlacement' && !['auto', 'bar', 'header'].includes(value)) throw new TypeError('filterPlacement must be auto, bar or header');
+    if (key === 'mode' && !['tree', 'inspector'].includes(value))
+      throw new TypeError('mode must be tree or inspector');
+    if (key === 'presentation' && !['pane', 'table'].includes(value))
+      throw new TypeError('presentation must be pane or table');
+    if (key === 'filterPlacement' && !['auto', 'bar', 'header'].includes(value))
+      throw new TypeError('filterPlacement must be auto, bar or header');
     if (key === 'nodes' && !Array.isArray(value)) throw new TypeError('nodes must be an array');
-    if (key === 'columns' && value !== null && !Array.isArray(value)) throw new TypeError('columns must be an array or null');
+    if (key === 'columns' && value !== null && !Array.isArray(value))
+      throw new TypeError('columns must be an array or null');
     if (key === 'model' && value === undefined) throw new TypeError('model must not be undefined');
-    if (key === 'meta' && value !== null && (!value || typeof value !== 'object' || Array.isArray(value))) throw new TypeError('meta must be an object or null');
-    if (['rowHeight', 'indentWidth'].includes(key) && value !== undefined && (!Number.isFinite(value) || value <= 0)) throw new TypeError(`${key} must be a positive number`);
-    if (key === 'headerHeight' && (!Number.isFinite(value) || value < 0)) throw new TypeError('headerHeight must be non-negative');
-    if (key === 'initialExpandDepth' && (!Number.isInteger(value) || value < 0)) throw new TypeError('initialExpandDepth must be a non-negative integer');
-    if (key === 'iconResolver' && value !== null && typeof value !== 'function') throw new TypeError('iconResolver must be a function or null');
-    if (key === 'fontFamily' && value !== null && typeof value !== 'string') throw new TypeError('fontFamily must be a string or null');
-    if (['flatRoot', 'enforceMeta', 'filter', 'markUpdated', 'editable', 'rowReorder', 'showHeader'].includes(key) && typeof value !== 'boolean') throw new TypeError(`${key} must be boolean`);
+    if (
+      key === 'meta' &&
+      value !== null &&
+      (!value || typeof value !== 'object' || Array.isArray(value))
+    )
+      throw new TypeError('meta must be an object or null');
+    if (
+      ['rowHeight', 'indentWidth'].includes(key) &&
+      value !== undefined &&
+      (!Number.isFinite(value) || value <= 0)
+    )
+      throw new TypeError(`${key} must be a positive number`);
+    if (key === 'headerHeight' && (!Number.isFinite(value) || value < 0))
+      throw new TypeError('headerHeight must be non-negative');
+    if (key === 'initialExpandDepth' && (!Number.isInteger(value) || value < 0))
+      throw new TypeError('initialExpandDepth must be a non-negative integer');
+    if (key === 'iconResolver' && value !== null && typeof value !== 'function')
+      throw new TypeError('iconResolver must be a function or null');
+    if (key === 'fontFamily' && value !== null && typeof value !== 'string')
+      throw new TypeError('fontFamily must be a string or null');
+    if (
+      [
+        'flatRoot',
+        'enforceMeta',
+        'filter',
+        'markUpdated',
+        'editable',
+        'rowReorder',
+        'showHeader'
+      ].includes(key) &&
+      typeof value !== 'boolean'
+    )
+      throw new TypeError(`${key} must be boolean`);
   }
 }

package/src/core/visible-row-model.js

@@ -12,6 +12,7 @@
  */
 
 export class VisibleRowModel extends EventTarget {
+
   /**
    * @param {{
    *   model: import('./tree-model.js').TreeModel,
@@ -26,9 +27,15 @@ export class VisibleRowModel extends EventTarget {
     this.expansion = expansion;
     this.rowHeight = rowHeight;
     this.indentWidth = indentWidth;
-    /** @type {TreeRow[]} */
+
+    /**
+     * @type {TreeRow[]}
+     */
     this.rows = [];
-    /** @type {Map<string, number>} */
+
+    /**
+     * @type {Map<string, number>}
+     */
     this.rowIndexById = new Map();
     this.contentWidth = 0;
     this.contentHeight = 0;
@@ -75,14 +82,18 @@ export class VisibleRowModel extends EventTarget {
       const node = this.model.index.getNode(id);
       const state = this.model.dynamicState.get(id) ?? {};
       const ownMatch = node ? this.filterPredicate(node, state) : false;
-      const childMatch = this.model.index.getChildren(id).some((childId) => subtreeIncluded(childId));
+      const childMatch = this.model.index
+        .getChildren(id)
+        .some((childId) => subtreeIncluded(childId));
       const included = ownMatch || childMatch;
       includeCache.set(id, included);
       return included;
     };
 
     const sortedChildren = (id) => {
-      const children = this.model.index.getChildren(id).filter((childId) => subtreeIncluded(childId));
+      const children = this.model.index
+        .getChildren(id)
+        .filter((childId) => subtreeIncluded(childId));
       if (!this.sortComparator) return children;
       return children.slice().sort((aId, bId) => {
         const a = this.model.index.getNode(aId);
@@ -98,7 +109,8 @@ export class VisibleRowModel extends EventTarget {
       const children = sortedChildren(id);
       const hasChildren = this.expansion.hasChildren(id);
       const autoExpanded = Boolean(this.filterPredicate && children.length > 0);
-      const expanded = (this.expansion.isExpanded(id) || autoExpanded) && !this.filterCollapsed.has(id);
+      const expanded =
+        (this.expansion.isExpanded(id) || autoExpanded) && !this.filterCollapsed.has(id);
       const rowIndex = this.rows.length;
       this.rows.push({
         nodeId: id,
@@ -108,7 +120,7 @@ export class VisibleRowModel extends EventTarget {
         y: rowIndex * this.rowHeight,
         height: this.rowHeight,
         expanded,
-        hasChildren,
+        hasChildren
       });
       this.rowIndexById.set(id, rowIndex);
       maxDepth = Math.max(maxDepth, depth);
@@ -118,7 +130,9 @@ export class VisibleRowModel extends EventTarget {
 
     const roots = this.model.index.roots.filter((rootId) => subtreeIncluded(rootId));
     if (this.sortComparator) {
-      roots.sort((aId, bId) => this.sortComparator(this.model.index.getNode(aId), this.model.index.getNode(bId), aId, bId));
+      roots.sort((aId, bId) =>
+        this.sortComparator(this.model.index.getNode(aId), this.model.index.getNode(bId), aId, bId)
+      );
     }
     for (const rootId of roots) visit(rootId, 0);
     this.contentHeight = this.rows.length * this.rowHeight;
@@ -126,13 +140,17 @@ export class VisibleRowModel extends EventTarget {
     this.dispatchEvent(new Event('change'));
   }
 
-  /** @param {string} id */
+  /**
+   * @param {string} id
+   */
   getRowById(id) {
     const rowIndex = this.rowIndexById.get(id);
     return rowIndex === undefined ? null : this.rows[rowIndex];
   }
 
-  /** @param {number} rowIndex */
+  /**
+   * @param {number} rowIndex
+   */
   getRow(rowIndex) {
     return this.rows[rowIndex] ?? null;
   }
@@ -144,11 +162,20 @@ export class VisibleRowModel extends EventTarget {
   getVisibleRange(viewport, overscan = 6) {
     const rowViewportHeight = viewport.rowViewportHeight ?? viewport.viewportHeight;
     const first = Math.max(0, Math.floor(viewport.scrollY / this.rowHeight) - overscan);
-    const last = Math.min(this.rows.length - 1, Math.ceil((viewport.scrollY + rowViewportHeight) / this.rowHeight) + overscan);
-    return { first, last, count: last >= first ? last - first + 1 : 0 };
+    const last = Math.min(
+      this.rows.length - 1,
+      Math.ceil((viewport.scrollY + rowViewportHeight) / this.rowHeight) + overscan
+    );
+    return {
+      first,
+      last,
+      count: last >= first ? last - first + 1 : 0
+    };
   }
 
-  /** @param {import('./tree-view-viewport.js').TreeViewViewport} viewport */
+  /**
+   * @param {import('./tree-view-viewport.js').TreeViewViewport} viewport
+   */
   getStickyRows(viewport) {
     const rowViewportHeight = viewport.rowViewportHeight ?? viewport.viewportHeight;
     if (viewport.scrollY <= 0 || rowViewportHeight < this.rowHeight * 2) return [];
@@ -169,20 +196,23 @@ export class VisibleRowModel extends EventTarget {
         sticky = [...sticky.slice(0, replaceAt), candidate];
       }
     }
-    return sticky
-      .slice(-max)
-      .map((ancestor, index) => ({
-        ...ancestor,
-        stickyY: Math.max(ancestor.y - viewport.scrollY, index * this.rowHeight),
-      }));
+    return sticky.slice(-max).map((ancestor, index) => ({
+      ...ancestor,
+      stickyY: Math.max(ancestor.y - viewport.scrollY, index * this.rowHeight)
+    }));
   }
 
-  /** @param {TreeRow} row */
+  /**
+   * @param {TreeRow} row
+   */
   #getStickyPath(row) {
-    const ancestors = this.model.index.getAncestors(row.nodeId).reverse()
+    const ancestors = this.model.index
+      .getAncestors(row.nodeId)
+      .reverse()
       .map((id) => this.getRowById(id))
       .filter((ancestor) => ancestor && ancestor.rowIndex < row.rowIndex);
     if (row.hasChildren) ancestors.push(row);
     return ancestors;
   }
+
 }

package/src/index.d.ts

@@ -183,12 +183,14 @@ export class TreeViewController {
   setModel(model: any, meta?: Record<string, MetaRule>, options?: Record<string, any>): void;
   setColumns(columns: Column[] | null): void;
   setDynamicState(patches: DynamicPatch[]): void;
+  flushDynamicState(): Set<string>;
   setTheme(theme: any): void;
   setLayoutMetrics(options?: { rowHeight?: number; indentWidth?: number; headerHeight?: number }): void;
   registerIcon(name: string, icon: IconSource): any;
   resize(width: number, height: number): void;
   render(time?: number): void;
   renderMeasured(time?: number): any;
+  getStats(): TreeViewStats;
   hitTest(clientX: number, clientY: number): any;
   getTooltipForHit(hit: any): any;
   search(query: string, options?: Record<string, any> & { caseSensitive?: boolean; wholeWord?: boolean }): any;
@@ -205,6 +207,26 @@ export class TreeViewController {
   collapseAll(): void;
 }
 
+export interface TreeViewStats {
+  totalNodes: number;
+  visibleRows: number;
+  renderedRows: number;
+  patchesFrame: number;
+  dirtyNodes: number;
+  selectedCount: number;
+  rebuildCount: number;
+  setDynamicStateCalls: number;
+  patchesReceived: number;
+  uniqueNodesReceived: number;
+  nodesChanged: number;
+  rendersRequested: number;
+  rendersExecuted: number;
+  rendersAvoidedNoChanges: number;
+  rendersAvoidedOffscreen: number;
+  rowActionsFullUpdates: number;
+  rowActionsIncrementalUpdates: number;
+}
+
 export class TreeViewInputController {
   constructor(options: { controller: TreeViewController; cellEditor?: CellEditorManager | null });
   destroy(): void;

package/src/input/row-actions.js

@@ -1,12 +1,28 @@
 import { drawCheckbox } from '../renderers/checkbox.js';
+
 /** Accessible buttons for visible rows. Actions and their meaning belong to the host. */
 export class RowActions {
   constructor(controller) {
     this.controller = controller;
     this.buttons = new Map();
+    this.buttonsByNodeId = new Map();
+    this.actionsById = new Map();
+    this.visibleRowsById = new Map();
     this.preparedIcons = new Set();
+    this.fullUpdates = 0;
+    this.incrementalUpdates = 0;
+    this.themeToken = 0;
+    this.theme = null;
+    this.stopIconListener = this.controller.iconRegistry.onChange?.(() => {
+      for (const button of this.buttons.values()) {
+        if (button._vtcKind !== 'checkbox') button.firstChild._vtcDrawKey = null;
+      }
+      this.controller.requestRender(true);
+    }) ?? null;
     this.element = controller.canvas.ownerDocument.createElement('div');
-    Object.assign(this.element.style, { position: 'absolute', overflow: 'hidden', pointerEvents: 'none', zIndex: '2' });
+    Object.assign(this.element.style, {
+      position: 'absolute', overflow: 'hidden', pointerEvents: 'none', zIndex: '2'
+    });
     const style = controller.canvas.ownerDocument.createElement('style');
     style.textContent = `
       .vtc-row-action { appearance:none; display:flex; align-items:center; justify-content:center;
@@ -16,100 +32,225 @@ export class RowActions {
     `;
     this.element.append(style);
     controller.canvas.parentElement?.append(this.element);
-    this.element.addEventListener('pointerdown', event => event.stopPropagation());
+    this.element.addEventListener('pointerdown', (event) => event.stopPropagation());
   }
 
-  render(scene) {
+  /** @param {object} scene @param {{full?: boolean, dirtyNodeIds?: Set<string>}} invalidation */
+  render(scene, invalidation = { full: true }) {
+    if (!invalidation.full && invalidation.dirtyNodeIds?.size) {
+      this.incrementalUpdates++;
+      for (const id of invalidation.dirtyNodeIds) this.#syncDynamicRow(id, scene);
+      return;
+    }
+    this.fullUpdates++;
+    this.#syncAll(scene);
+  }
+
+  #syncAll(scene) {
     const { viewport, theme, rows, visibleRange, stickyRows } = scene;
-    const ratio = Math.max(1, this.element.ownerDocument.defaultView.devicePixelRatio || 1);
-    for (const action of this.controller.rowActions) {
-      const icons = action.preloadIcons ?? (typeof action.icon === 'string' ? [action.icon] : []);
-      for (const icon of icons) for (const color of [theme.colors.text, theme.colors.textMuted]) {
-        const key = JSON.stringify([icon, color, ratio]);
-        if (this.preparedIcons.has(key)) continue;
-        this.preparedIcons.add(key);
-        void this.controller.iconRegistry.prepare({icons:[icon],size:16,color,pixelRatio:ratio});
-      }
+    if (this.theme !== theme) {
+      this.theme = theme;
+      this.themeToken++;
     }
-    const column = scene.columns.find(c => c.id === '__vtc_actions');
-    const used = new Set();
+    this.actionsById.clear();
+    for (const action of this.controller.rowActions) this.actionsById.set(action.id, action);
+    const ratio = Math.max(1, this.element.ownerDocument.defaultView.devicePixelRatio || 1);
+    this.#prepareIcons(theme, ratio);
+    const column = scene.columns.find((column) => column.id === '__vtc_actions');
     const width = column?.width ?? 0;
-    this.element.style.setProperty('--vtc-action-focus', theme.colors.focus);
-    Object.assign(this.element.style, { background:'transparent', left: `${viewport.renderInsetX + Math.max(0, viewport.contentViewportWidth - width)}px`, top: `${viewport.renderInsetY + viewport.headerHeight}px`,
-      width: `${width}px`, height: `${viewport.rowViewportHeight}px` });
+    setStyle(this.element, '--vtc-action-focus', theme.colors.focus);
+    setStyle(this.element, 'background', 'transparent');
+    setStyle(this.element, 'left', `${viewport.renderInsetX + Math.max(0, viewport.contentViewportWidth - width)}px`);
+    setStyle(this.element, 'top', `${viewport.renderInsetY + viewport.headerHeight}px`);
+    setStyle(this.element, 'width', `${width}px`);
+    setStyle(this.element, 'height', `${viewport.rowViewportHeight}px`);
+
+    const used = new Set();
+    this.visibleRowsById.clear();
     if (column) {
-      const visible = new Map();
-      const stickyBottom = stickyRows.reduce((end, row) => Math.max(end, row.stickyY + row.height), 0);
+      const stickyBottom = stickyRows.reduce(
+        (end, row) => Math.max(end, row.stickyY + row.height), 0
+      );
       for (let i = visibleRange.first; i <= visibleRange.last; i++) {
         const row = rows[i];
-        if (row && row.y + row.height - viewport.scrollY > stickyBottom) visible.set(row.nodeId, {row, y:row.y - viewport.scrollY});
+        if (!row || row.y + row.height - viewport.scrollY <= stickyBottom) continue;
+        this.#rememberVisibleRow(row, row.y - viewport.scrollY, false, stickyBottom, viewport);
       }
-      for (const row of stickyRows) visible.set(row.nodeId, {row, y:row.stickyY, sticky:true});
-      for (const {row, y, sticky} of visible.values()) {
-        if (y + row.height <= 0 || y >= viewport.rowViewportHeight) continue;
-        const node = this.controller.model.index.getNode(row.nodeId);
-        const state = this.controller.model.dynamicState.get(node.id) ?? {};
-        this.controller.rowActions.forEach((action, index) => {
-          const resolve = value => typeof value === 'function' ? value(node, state) : value;
-          if (resolve(action.visible) === false) return;
-          const key = JSON.stringify([node.id, action.id, action.kind]);
-          used.add(key);
-          let button = this.buttons.get(key);
-          if (!button) {
-            button = this.element.ownerDocument.createElement('button');
-            button.type = 'button';
-            if (action.kind === 'checkbox') button.setAttribute('role','checkbox');
-            button.className = 'vtc-row-action';
-            button.dataset.nodeId = node.id;
-            button.dataset.action = action.id;
-            Object.assign(button.style, { position:'absolute', pointerEvents:'auto', width:'26px', padding:'3px', border:'0', borderRadius:'3px', cursor:'pointer' });
-            const icon = this.element.ownerDocument.createElement('canvas');
-            Object.assign(icon.style, {width:'16px',height:'16px',display:'block'});
-            button.append(icon);
-            button.onclick = event => {
-              event.stopPropagation();
-              const current = this.controller.model.index.getNode(button.dataset.nodeId);
-              const spec = this.controller.rowActions.find(item => item.id === button.dataset.action);
-              const currentState = this.controller.model.dynamicState.get(current?.id) ?? {};
-              if (!current || !spec || (typeof spec.disabled === 'function' ? spec.disabled(current, currentState) : spec.disabled)) return;
-              this.controller.events.emit('rowaction', { actionId: spec.id, nodeId: current.id, node: current, ...(spec.kind === 'checkbox' ? {checked:!(typeof spec.checked === 'function' ? spec.checked(current,currentState) : spec.checked)} : {}), originalEvent: event });
-            };
-            this.buttons.set(key, button);
-            this.element.append(button);
-          }
-          button.title = action.label;
-          button.setAttribute('aria-label', `${action.label}: ${node.label ?? node.id}`);
-          if (action.pressed !== undefined) button.setAttribute('aria-pressed', String(Boolean(resolve(action.pressed))));
-          else button.removeAttribute('aria-pressed');
-          button.disabled = Boolean(resolve(action.disabled));
-          Object.assign(button.style, { left:`${index * 28 + 1}px`, top:`${y + 1}px`, height:`${row.height - 2}px`,
-            clipPath:sticky ? 'none' : `inset(${Math.max(0, stickyBottom - y - 1)}px 0 0)`, opacity:button.disabled ? '0.3':'1' });
-          const canvas = button.firstChild;
-          const ratio = Math.max(1, this.element.ownerDocument.defaultView.devicePixelRatio || 1);
-          const size = action.kind === 'checkbox' ? 18 : 16;
-          canvas.style.width = canvas.style.height = `${size}px`;
-          const pixels = Math.round(size * ratio);
-          if (canvas.width !== pixels || canvas.height !== pixels) canvas.width = canvas.height = pixels;
-          const ctx = canvas.getContext('2d');
-          ctx.setTransform(pixels / size, 0, 0, pixels / size, 0, 0);
-          ctx.clearRect(0,0,size,size);
-          if (action.kind === 'checkbox') {
-            const checked = Boolean(resolve(action.checked));
-            button.setAttribute('aria-checked', String(checked));
-            drawCheckbox(ctx,1,1,checked,theme);
-            return;
-          }
-          this.controller.iconRegistry.draw(ctx, resolve(action.icon) ?? 'star', 0,0,16,resolve(action.pressed) ? theme.colors.text : theme.colors.textMuted);
-        });
+      for (const row of stickyRows) {
+        this.#rememberVisibleRow(row, row.stickyY, true, stickyBottom, viewport);
       }
+      for (const info of this.visibleRowsById.values()) this.#syncRow(info, scene, used, ratio);
     }
-    let refocus = false;
-    for (const [key, button] of this.buttons) if (!used.has(key)) {
-      refocus ||= this.element.getRootNode().activeElement === button;
-      button.remove(); this.buttons.delete(key);
+    for (const [key, button] of this.buttons) {
+      if (!used.has(button)) this.#removeButton(key, button, true);
+    }
+  }
+
+  #rememberVisibleRow(row, y, sticky, stickyBottom, viewport) {
+    if (y + row.height <= 0 || y >= viewport.rowViewportHeight) return;
+    this.visibleRowsById.set(row.nodeId, { row, y, sticky, stickyBottom });
+  }
+
+  #syncDynamicRow(id, scene) {
+    const info = this.visibleRowsById.get(id);
+    if (!info) return;
+    const ratio = Math.max(1, this.element.ownerDocument.defaultView.devicePixelRatio || 1);
+    this.#syncRow(info, scene, null, ratio);
+  }
+
+  #syncRow(info, scene, used, ratio) {
+    const { row, y, sticky, stickyBottom } = info;
+    const node = this.controller.model.index.getNode(row.nodeId);
+    if (!node) return;
+    const state = this.controller.model.dynamicState.get(node.id) ?? {};
+    this.controller.rowActions.forEach((action, index) => {
+      const visible = resolve(action.visible, node, state) !== false;
+      const key = actionKey(node.id, action.id);
+      let button = this.buttons.get(key);
+      if (!visible) {
+        if (button) this.#removeButton(key, button, false);
+        return;
+      }
+      if (button?._vtcKind !== action.kind) {
+        this.#removeButton(key, button, false);
+        button = null;
+      }
+      if (!button) button = this.#createButton(key, node, action);
+      used?.add(button);
+      this.#syncButton(button, node, state, action, index, row, y, sticky, stickyBottom, scene, ratio);
+    });
+  }
+
+  #createButton(key, node, action) {
+    const button = this.element.ownerDocument.createElement('button');
+    button.type = 'button';
+    button._vtcKind = action.kind;
+    if (action.kind === 'checkbox') button.setAttribute('role', 'checkbox');
+    button.className = 'vtc-row-action';
+    button.dataset.nodeId = node.id;
+    button.dataset.action = action.id;
+    Object.assign(button.style, {
+      position: 'absolute', pointerEvents: 'auto', width: '26px', padding: '3px',
+      border: '0', borderRadius: '3px', cursor: 'pointer'
+    });
+    const icon = this.element.ownerDocument.createElement('canvas');
+    Object.assign(icon.style, { width: '16px', height: '16px', display: 'block' });
+    button.append(icon);
+    button.onclick = (event) => this.#activate(button, event);
+    this.buttons.set(key, button);
+    let nodeButtons = this.buttonsByNodeId.get(node.id);
+    if (!nodeButtons) this.buttonsByNodeId.set(node.id, (nodeButtons = new Map()));
+    nodeButtons.set(action.id, button);
+    this.element.append(button);
+    return button;
+  }
+
+  #syncButton(button, node, state, action, index, row, y, sticky, stickyBottom, scene, ratio) {
+    setProperty(button, 'title', action.label);
+    setAttribute(button, 'aria-label', `${action.label}: ${node.label ?? node.id}`);
+    const pressed = action.pressed === undefined ? null : Boolean(resolve(action.pressed, node, state));
+    setAttribute(button, 'aria-pressed', pressed === null ? null : String(pressed));
+    const disabled = Boolean(resolve(action.disabled, node, state));
+    setProperty(button, 'disabled', disabled);
+    setStyle(button, 'left', `${index * 28 + 1}px`);
+    setStyle(button, 'top', `${y + 1}px`);
+    setStyle(button, 'height', `${row.height - 2}px`);
+    setStyle(button, 'clipPath', sticky ? 'none' : `inset(${Math.max(0, stickyBottom - y - 1)}px 0 0)`);
+    setStyle(button, 'opacity', disabled ? '0.3' : '1');
+
+    const canvas = button.firstChild;
+    const size = action.kind === 'checkbox' ? 18 : 16;
+    const pixels = Math.round(size * ratio);
+    setStyle(canvas, 'width', `${size}px`);
+    setStyle(canvas, 'height', `${size}px`);
+    const checked = action.kind === 'checkbox' && Boolean(resolve(action.checked, node, state));
+    if (action.kind === 'checkbox') setAttribute(button, 'aria-checked', String(checked));
+    const icon = action.kind === 'checkbox' ? '' : resolve(action.icon, node, state) ?? 'star';
+    const color = pressed ? scene.theme.colors.text : scene.theme.colors.textMuted;
+    const drawKey = `${this.themeToken}\0${action.kind ?? ''}\0${icon}\0${color}\0${checked}\0${pixels}`;
+    if (canvas._vtcDrawKey === drawKey) return;
+    canvas._vtcDrawKey = drawKey;
+    if (canvas.width !== pixels) canvas.width = pixels;
+    if (canvas.height !== pixels) canvas.height = pixels;
+    const ctx = canvas.getContext('2d');
+    ctx.setTransform(pixels / size, 0, 0, pixels / size, 0, 0);
+    ctx.clearRect(0, 0, size, size);
+    if (action.kind === 'checkbox') drawCheckbox(ctx, 1, 1, checked, scene.theme);
+    else this.controller.iconRegistry.draw(ctx, icon, 0, 0, 16, color);
+  }
+
+  #activate(button, event) {
+    event.stopPropagation();
+    this.controller.flushDynamicState();
+    const current = this.controller.model.index.getNode(button.dataset.nodeId);
+    const spec = this.actionsById.get(button.dataset.action);
+    const state = this.controller.model.dynamicState.get(current?.id) ?? {};
+    if (!current || !spec || resolve(spec.disabled, current, state)) return;
+    this.controller.events.emit('rowaction', {
+      actionId: spec.id, nodeId: current.id, node: current,
+      ...(spec.kind === 'checkbox'
+        ? { checked: !Boolean(resolve(spec.checked, current, state)) }
+        : {}),
+      originalEvent: event
+    });
+  }
+
+  #prepareIcons(theme, ratio) {
+    for (const action of this.controller.rowActions) {
+      const icons = action.preloadIcons ?? (typeof action.icon === 'string' ? [action.icon] : []);
+      for (const icon of icons) for (const color of [theme.colors.text, theme.colors.textMuted]) {
+        const key = `${icon}\0${color}\0${ratio}`;
+        if (this.preparedIcons.has(key)) continue;
+        this.preparedIcons.add(key);
+        void this.controller.iconRegistry.prepare({ icons: [icon], size: 16, color, pixelRatio: ratio });
+      }
     }
-    if (refocus) (this.buttons.values().next().value ?? this.controller.canvas).focus({preventScroll:true});
   }
 
-  destroy() { this.element.remove(); this.buttons.clear(); }
+  #removeButton(key, button, preserveFocus) {
+    if (!button) return;
+    const focused = this.element.getRootNode().activeElement === button;
+    button.remove();
+    this.buttons.delete(key);
+    const nodeButtons = this.buttonsByNodeId.get(button.dataset.nodeId);
+    nodeButtons?.delete(button.dataset.action);
+    if (!nodeButtons?.size) this.buttonsByNodeId.delete(button.dataset.nodeId);
+    if (focused && preserveFocus) {
+      (this.buttons.values().next().value ?? this.controller.canvas).focus({ preventScroll: true });
+    } else if (focused) this.controller.canvas.focus({ preventScroll: true });
+  }
+
+  destroy() {
+    this.stopIconListener?.();
+    this.stopIconListener = null;
+    this.element.remove();
+    this.buttons.clear();
+    this.buttonsByNodeId.clear();
+    this.actionsById.clear();
+    this.visibleRowsById.clear();
+  }
+}
+
+function resolve(value, node, state) {
+  return typeof value === 'function' ? value(node, state) : value;
+}
+
+function actionKey(nodeId, actionId) {
+  return `${nodeId.length}:${nodeId}${actionId}`;
+}
+
+function setProperty(target, name, value) {
+  if (!Object.is(target[name], value)) target[name] = value;
+}
+
+function setAttribute(target, name, value) {
+  if (value === null) {
+    if (target.hasAttribute(name)) target.removeAttribute(name);
+  } else if (target.getAttribute(name) !== value) target.setAttribute(name, value);
+}
+
+function setStyle(target, name, value) {
+  if (name.startsWith('--')) {
+    if (target.style.getPropertyValue(name) !== value) target.style.setProperty(name, value);
+  } else if (target.style[name] !== value) target.style[name] = value;
 }