@ankhorage/zora 25.11.1 → 26.0.1

package/src/features/graph-view/adapters/inbound/web-artifact/createGraphController.ts

@@ -185,7 +185,7 @@ function isUsableViewport(viewport: { readonly width: number; readonly height: n
   );
 }
 
-/*** Measure rendered node geometry for public consumers while keeping Cytoscape private. */
+/*** Measure rendered node hit geometry without exposing paint-only outlines or Cytoscape. */
 function measureRenderedNodes(cy: Core, nodeIds: readonly string[]): GraphViewMeasurement | null {
   const viewport = { width: cy.width(), height: cy.height() };
   if (viewport.width <= 0 || viewport.height <= 0 || nodeIds.length === 0) return null;
@@ -194,12 +194,11 @@ function measureRenderedNodes(cy: Core, nodeIds: readonly string[]): GraphViewMe
     const node = cy.getElementById(id);
     if (!node.isNode()) return [];
 
-    const bounds = node.renderedBoundingBox();
     return [
       {
         id,
         position: node.renderedPosition(),
-        size: { width: bounds.w, height: bounds.h },
+        size: { width: node.renderedOuterWidth(), height: node.renderedOuterHeight() },
       },
     ];
   });

package/src/features/graph-view/adapters/inbound/web-artifact/createGraphRuntime.test.ts

@@ -214,6 +214,51 @@ test('preserves selection and positions through hover presentation updates witho
   }
 });
 
+test('does not relayout when controlled selection adds a paint-only outline', async () => {
+  const ready = Promise.withResolvers<GraphViewController>();
+  const calls = { sort: 0 };
+  const runtime = createGraphRuntime(undefined, { current: { onReady: ready.resolve } });
+  const input = {
+    nodes: [
+      { id: 'src', label: 'src' },
+      { id: 'dependency', label: 'dependency' },
+    ],
+    edges: [{ source: 'src', target: 'dependency' }],
+    layout: 'grid' as const,
+    layoutOptions: {
+      sort: () => {
+        calls.sort += 1;
+        return 0;
+      },
+    },
+    richNodeRendering: false,
+    sizeNodesToLabels: true,
+    styleRules: [
+      {
+        selector: 'node',
+        style: { height: 24, label: 'data(label)', padding: '12px', width: 24 },
+      },
+      { selector: 'node:selected', style: { 'outline-width': 2 } },
+    ],
+  };
+  try {
+    runtime.update(input);
+    await ready.promise;
+    const sortCount = calls.sort;
+    runtime.setSelectedNodeIds(['src']);
+    runtime.update({
+      ...input,
+      nodes: [
+        { id: 'src', classes: 'highlight', label: 'src' },
+        { id: 'dependency', label: 'dependency' },
+      ],
+    });
+    expect(calls.sort).toBe(sortCount);
+  } finally {
+    runtime.destroy();
+  }
+});
+
 test('forwards semantic selection intent from rich-node press events', async () => {
   const ready = Promise.withResolvers<GraphViewController>();
   const events: GraphViewElementEvent[] = [];

package/src/features/graph-view/adapters/inbound/web-artifact/createGraphRuntime.ts

@@ -192,7 +192,9 @@ function updateRuntime(state: GraphRuntimeState, input: GraphRuntimeUpdate) {
   applyKnownNodeSizes(state);
   state.loopSizer.update();
   const geometry = getGraphGeometryKey(state.cy);
-  const relayout = geometry !== state.geometryRef.current || hasGraphLayoutChanged(previous, input);
+  // Keep native double-press targets stable for paint-only class changes. A class that changes
+  // measured node dimensions remains a geometry change and must relayout.
+  const relayout = hasGraphLayoutChanged(previous, input) || geometry !== state.geometryRef.current;
   state.geometryRef.current = geometry;
   if (!relayout) {
     if (

package/src/features/graph-view/adapters/inbound/web-artifact/getGraphGeometryKey.test.ts

@@ -4,13 +4,19 @@ import cytoscape from 'cytoscape';
 import { getGraphGeometryKey } from './getGraphGeometryKey';
 import { syncGraphElements } from './syncGraphElements';
 
-test('ignores styled highlight colors but detects changed layout dimensions', () => {
+test('uses body, padding, borders and labels while ignoring paint-only presentation', () => {
   const cy = cytoscape({
     headless: true,
     styleEnabled: true,
     style: [
-      { selector: 'node', style: { width: 'data(width)', height: 24 } },
+      {
+        selector: 'node',
+        style: { width: 'data(width)', height: 24, padding: 8, 'border-width': 2 },
+      },
       { selector: 'node.highlight', style: { 'background-color': '#ff0000' } },
+      { selector: 'node.hovered', style: { 'overlay-opacity': 0.4 } },
+      { selector: 'node:selected', style: { 'outline-width': 2 } },
+      { selector: 'node.expanded', style: { padding: 16, width: 160 } },
     ],
   });
   try {
@@ -19,7 +25,63 @@ test('ignores styled highlight colors but detects changed layout dimensions', ()
     syncGraphElements(cy, [{ id: 'a', classes: 'highlight', data: { width: 80 } }], []);
     expect(cy.getElementById('a').style('background-color')).toBe('rgb(255,0,0)');
     expect(getGraphGeometryKey(cy)).toBe(before);
-    syncGraphElements(cy, [{ id: 'a', classes: 'highlight', data: { width: 160 } }], []);
+    cy.getElementById('a').select();
+    expect(getGraphGeometryKey(cy)).toBe(before);
+    syncGraphElements(cy, [{ id: 'a', classes: 'hovered', data: { width: 80 } }], []);
+    expect(getGraphGeometryKey(cy)).toBe(before);
+    syncGraphElements(cy, [{ id: 'a', classes: 'expanded', data: { width: 80 } }], []);
+    expect(getGraphGeometryKey(cy)).not.toBe(before);
+  } finally {
+    cy.destroy();
+  }
+});
+
+test('includes plain and Unicode label bounds when their font metrics change', () => {
+  const cy = cytoscape({
+    headless: true,
+    styleEnabled: true,
+    elements: [{ data: { id: 'plain' } }, { data: { id: 'unicode' } }],
+  });
+  const plain = cy.getElementById('plain');
+  const unicode = cy.getElementById('unicode');
+  const labelBounds = new Map([
+    ['plain', { h: 18, w: 42 }],
+    ['unicode', { h: 18, w: 56 }],
+  ]);
+  const boundingBox = (id: string) => () => {
+    const bounds = labelBounds.get(id);
+    if (!bounds) throw new Error(`Missing label bounds for ${id}.`);
+    return { x1: 0, x2: bounds.w, y1: 0, y2: bounds.h, ...bounds };
+  };
+  plain.boundingBox = boundingBox('plain');
+  unicode.boundingBox = boundingBox('unicode');
+  try {
+    const before = getGraphGeometryKey(cy);
+    labelBounds.set('unicode', { h: 22, w: 76 });
+    expect(getGraphGeometryKey(cy)).not.toBe(before);
+  } finally {
+    cy.destroy();
+  }
+});
+
+test('excludes compound bounds and edge paint while retaining child body geometry', () => {
+  const cy = cytoscape({
+    headless: true,
+    styleEnabled: true,
+    elements: [
+      { data: { id: 'parent' } },
+      { data: { id: 'child', parent: 'parent' } },
+      { data: { id: 'loop', source: 'child', target: 'child' } },
+    ],
+    style: [{ selector: 'node', style: { height: 24, width: 'data(width)' } }],
+  });
+  try {
+    const child = cy.getElementById('child');
+    child.data('width', 80);
+    const before = getGraphGeometryKey(cy);
+    cy.getElementById('parent').position({ x: 500, y: 400 });
+    expect(getGraphGeometryKey(cy)).toBe(before);
+    child.data('width', 160);
     expect(getGraphGeometryKey(cy)).not.toBe(before);
   } finally {
     cy.destroy();

package/src/features/graph-view/adapters/inbound/web-artifact/getGraphGeometryKey.ts

@@ -1,18 +1,24 @@
 import type { Core } from 'cytoscape';
 
 /***
- * Identifies layout-relevant leaf dimensions without including positions or presentation colors.
- * Adding viewport, color or arbitrary data to this key turns interaction updates into relayouts.
- * Measure after style reconciliation; actual size changes still require layout. Compound bounds
- * follow child positions, so keying their measured bounds would feed layout output back into input.
- * Styled geometry tests and runtime interaction tests protect these distinctions.
+ * Identifies layout-relevant leaf dimensions without including positions or paint-only outlines.
+ * Cytoscape's layoutDimensions() includes selected-outline rendering even though layouts use only
+ * the node body, padding, border, and label bounds. Key those direct inputs instead. Compound
+ * bounds follow child positions, so keying their measured bounds would feed layout output back
+ * into input. Styled geometry tests and runtime interaction tests protect these distinctions.
  */
 export function getGraphGeometryKey(cy: Core): string {
   return JSON.stringify(
     cy.nodes().map((node) => {
       if (node.isParent()) return [node.id()];
-      const dimensions = node.layoutDimensions({ nodeDimensionsIncludeLabels: true });
-      return [node.id(), dimensions.w, dimensions.h];
+      const labelBounds = node.boundingBox({
+        includeEdges: false,
+        includeLabels: true,
+        includeNodes: false,
+        includeOverlays: false,
+        includeUnderlays: false,
+      });
+      return [node.id(), node.outerWidth(), node.outerHeight(), labelBounds.w, labelBounds.h];
     }),
   );
 }

package/src/features/registry/componentMeta.test.ts

@@ -382,7 +382,18 @@ describe('ZORA_COMPONENT_META invariants', () => {
     });
     expect(ZORA_COMPONENT_META.ChessBoard.bindings?.props?.legalTargets?.value).toEqual({
       type: 'array',
-      itemType: 'string',
+      itemType: 'object',
+      fields: [
+        { path: '[].column', type: 'number', label: 'Column' },
+        { path: '[].row', type: 'number', label: 'Row' },
+      ],
+    });
+    expect(ZORA_COMPONENT_META.ChessBoard.bindings?.props?.selectedCell?.value).toEqual({
+      type: 'object',
+      fields: [
+        { path: 'column', type: 'number', label: 'Column' },
+        { path: 'row', type: 'number', label: 'Row' },
+      ],
     });
     expect(ZORA_COMPONENT_META.OpeningBook.bindings?.props?.moves?.value).toEqual({
       type: 'array',

package/src/readerFree.ts

@@ -119,18 +119,17 @@ export type {
 } from './features/chat/public';
 export { ChatListItem, MessageBubble } from './features/chat/public';
 export type {
+  ChessBoardCell,
   ChessBoardColorOverrides,
   ChessBoardColorScheme,
+  ChessBoardDimensions,
   ChessBoardOrientation,
   ChessBoardProps,
   ChessMoveAttempt,
-  ChessMoveResult,
   ChessPieceCode,
   ChessPieceRenderContext,
   ChessPieceRenderer,
   ChessPieceState,
-  ChessPromotionPiece,
-  ChessSquareId,
   OpeningBookColorOverrides,
   OpeningBookColorScheme,
   OpeningBookMove,
@@ -138,18 +137,7 @@ export type {
 } from './features/chess/public';
 export type { ChessColorThemeShape } from './features/chess/public';
 export { ChessBoard, chessBoardMeta, OpeningBook, openingBookMeta } from './features/chess/public';
-export {
-  chessSquares,
-  createBoardSquares,
-  createChessBoardColorScheme,
-  createOpeningBookColorScheme,
-  getLegalTargets,
-  getSquareFile,
-  getSquareRank,
-  isLightSquare,
-  readChessPieces,
-  tryMove,
-} from './features/chess/public';
+export { createChessBoardColorScheme, createOpeningBookColorScheme } from './features/chess/public';
 export type { ChipProps } from './features/chip/public';
 export type { ChipGroupItem, ChipGroupProps } from './features/chip/public';
 export { Chip } from './features/chip/public';

package/src/types/authoring.ts

@@ -8,7 +8,8 @@ import type {
 
 export type ZoraComponentCategory = 'foundation' | 'component' | 'pattern' | 'layout';
 
-export type ZoraComponentPropType = UiComponentPropType;
+/** ZORA authoring additionally describes serializable object-shaped values. */
+export type ZoraComponentPropType = UiComponentPropType | 'object';
 
 export type ZoraComponentPropValue =
   | string

package/src/types/chess.ts

@@ -4,33 +4,36 @@ import type { ZoraBaseProps } from './base';
 
 export type ChessBoardOrientation = 'white' | 'black';
 export type ChessPieceCode = string;
-export type ChessSquareId =
-  `${'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h'}${1 | 2 | 3 | 4 | 5 | 6 | 7 | 8}`;
-export type ChessPromotionPiece = 'q' | 'r' | 'b' | 'n';
 
-export interface ChessMoveAttempt {
-  readonly from: ChessSquareId;
-  readonly to: ChessSquareId;
-  readonly promotion?: ChessPromotionPiece;
+/** A caller-owned cell location in a rectangular chess presentation board. */
+export interface ChessBoardCell {
+  readonly column: number;
+  readonly row: number;
 }
 
-export interface ChessMoveResult extends Omit<ChessMoveAttempt, 'promotion'> {
-  readonly fen: string;
-  readonly lan: string;
-  readonly promotion?: ChessPromotionPiece;
-  readonly san: string;
+/** The bounded presentation dimensions supported by ChessBoard. */
+export interface ChessBoardDimensions {
+  readonly columns: number;
+  readonly rows: number;
+}
+
+export interface ChessMoveAttempt {
+  readonly from: ChessBoardCell;
+  readonly to: ChessBoardCell;
 }
 
 export interface ChessPieceState {
   readonly color: 'black' | 'white';
   readonly piece: ChessPieceCode;
-  readonly square: ChessSquareId;
+  readonly cell: ChessBoardCell;
 }
 
 export interface ChessPieceRenderContext {
   readonly color: string;
   readonly piece: ChessPieceCode;
-  readonly square: ChessSquareId;
+  readonly cell: ChessBoardCell;
+  /** Available cell edge length in pixels. */
+  readonly size: number;
 }
 
 export type ChessPieceRenderer = (context: ChessPieceRenderContext) => React.ReactNode;
@@ -65,20 +68,24 @@ export interface OpeningBookColorScheme {
 export type OpeningBookColorOverrides = Partial<OpeningBookColorScheme>;
 
 export interface ChessBoardProps extends ZoraBaseProps {
-  readonly fen?: string;
+  /** Number of displayed columns, from 2 through 24. */
+  readonly columns?: number;
+  /** Number of displayed rows, from 2 through 24. */
+  readonly rows?: number;
   readonly pieces?: readonly ChessPieceState[];
   readonly orientation?: ChessBoardOrientation;
-  readonly selectedSquare?: ChessSquareId | null;
-  readonly legalTargets?: readonly ChessSquareId[];
+  readonly selectedCell?: ChessBoardCell | null;
+  readonly legalTargets?: readonly ChessBoardCell[];
   readonly lastMove?: ChessMoveAttempt | null;
   readonly disabled?: boolean;
   readonly showCoordinates?: boolean;
-  readonly validateMoves?: boolean;
+  /** Enables explicit editor resize controls when a dimensions callback is supplied. */
+  readonly resizable?: boolean;
   readonly colorScheme?: ChessBoardColorOverrides;
-  readonly onSquarePress?: (square: ChessSquareId) => void;
+  readonly onCellPress?: (cell: ChessBoardCell) => void;
   readonly onMoveAttempt?: (move: ChessMoveAttempt) => void;
-  readonly onLegalMove?: (move: ChessMoveResult) => void;
-  readonly onInvalidMove?: (move: ChessMoveAttempt) => void;
+  /** Receives a caller-owned resize proposal; ZORA never mutates board dimensions. */
+  readonly onDimensionsChange?: (dimensions: ChessBoardDimensions) => void;
   readonly renderPiece?: ChessPieceRenderer;
 }