@mirasen/chessboard 1.2.4 → 1.3.0

package/dist/extensions/first-party/main-renderer/types/internal.d.ts

@@ -1,5 +1,6 @@
-import { NonEmptyPieceCode } from '../../../../state/board/types/internal.js';
-import { TMainRendererConfig } from './template.js';
+import type { ReadonlyDeep } from 'type-fest';
+import type { NonEmptyPieceCode } from '../../../../state/board/types/internal.js';
+import type { TMainRendererConfig } from './template.js';
 export interface ConfigColorPair {
     light: string;
     dark: string;
@@ -9,9 +10,7 @@ export interface ConfigColors {
     coordinates: ConfigColorPair;
 }
 export type PieceUrls = Record<NonEmptyPieceCode, string>;
-export type MainRendererConfig = TMainRendererConfig<PieceUrls>;
+export type MainRendererConfig = ReadonlyDeep<TMainRendererConfig<PieceUrls>>;
 export declare const CHESSNUT_PIECE_URLS: PieceUrls;
-/**
- * Default board renderer configuration.
- */
-export declare const DEFAULT_MAIN_RENDERER_CONFIG: MainRendererConfig;
+export declare const DefaultMainRendererDesktopConfig: MainRendererConfig;
+export declare const DefaultMainRendererMobileConfig: MainRendererConfig;

package/dist/extensions/first-party/main-renderer/types/internal.js

@@ -1,3 +1,4 @@
+import { cloneDeep } from 'es-toolkit';
 export const CHESSNUT_PIECE_URLS = {
     [6 /* PieceCode.WhiteKing */]: new URL('../../../../../assets/pieces/chessnut/wK.svg', import.meta.url).toString(),
     [5 /* PieceCode.WhiteQueen */]: new URL('../../../../../assets/pieces/chessnut/wQ.svg', import.meta.url).toString(),
@@ -15,7 +16,7 @@ export const CHESSNUT_PIECE_URLS = {
 /**
  * Default board renderer configuration.
  */
-export const DEFAULT_MAIN_RENDERER_CONFIG = {
+const DefaultMainRendererConfigPart = {
     colors: {
         board: {
             light: '#d7dde5',
@@ -28,3 +29,25 @@ export const DEFAULT_MAIN_RENDERER_CONFIG = {
     },
     pieceUrls: CHESSNUT_PIECE_URLS
 };
+export const DefaultMainRendererDesktopConfig = {
+    ...cloneDeep(DefaultMainRendererConfigPart),
+    drag: {
+        pieceScale: 1,
+        pieceAnchor: 'center',
+        pieceAnchorOffsetY: 0
+    },
+    animation: {
+        durationMs: 180
+    }
+};
+export const DefaultMainRendererMobileConfig = {
+    ...cloneDeep(DefaultMainRendererConfigPart),
+    drag: {
+        pieceScale: 1.5,
+        pieceAnchor: 'bottom',
+        pieceAnchorOffsetY: 0.14
+    },
+    animation: {
+        durationMs: 180
+    }
+};

package/dist/extensions/first-party/main-renderer/types/public.d.ts

@@ -0,0 +1,9 @@
+import type { PartialDeep, ReadonlyDeep, WritableDeep } from 'type-fest';
+import type { PieceString } from '../../../../state/board/types/input.js';
+import type { TMainRendererConfig } from './template.js';
+export type PieceUrlsPublic = Record<PieceString, string>;
+export type MainRendererConfigPublic = ReadonlyDeep<TMainRendererConfig<PieceUrlsPublic>>;
+export interface MainRendererInitOptions extends PartialDeep<WritableDeep<MainRendererConfigPublic>> {
+    pieceUrls?: PieceUrlsPublic;
+}
+export type MainRendererSetConfigOptions = Omit<MainRendererInitOptions, 'pieceUrls'>;

package/dist/extensions/first-party/main-renderer/types/template.d.ts

@@ -1,5 +1,16 @@
-import { ConfigColors } from './internal.js';
+import type { ConfigColors } from './internal.js';
+export type MainRendererConfigDragPieceAnchor = 'center' | 'bottom';
+export interface MainRendererConfigDrag {
+    pieceScale: number;
+    pieceAnchor: MainRendererConfigDragPieceAnchor;
+    pieceAnchorOffsetY: number;
+}
+export interface MainRendererConfigAnimation {
+    durationMs: number;
+}
 export interface TMainRendererConfig<TPieceUrls> {
     colors: ConfigColors;
     pieceUrls: TPieceUrls;
+    drag: MainRendererConfigDrag;
+    animation: MainRendererConfigAnimation;
 }

package/dist/extensions/first-party/promotion/types/input.d.ts

@@ -1,8 +1,8 @@
 import { ColorShort, RolePromotionShort } from '../../../../state/board/types/input.js';
 import { OpaqueColor } from '../../common/types.js';
-import { PieceUrlsInput } from '../../main-renderer/types/input.js';
+import { PieceUrlsPublic } from '../../main-renderer/types/public.js';
 export type PromotionPieceString = `${ColorShort}${RolePromotionShort}`;
-export type PromotionPieceUrlsInput = Pick<PieceUrlsInput, PromotionPieceString>;
+export type PromotionPieceUrlsInput = Pick<PieceUrlsPublic, PromotionPieceString>;
 export interface PromotionInitConfig {
     squareColor?: OpaqueColor;
     hoverColor?: OpaqueColor;

package/dist/extensions/index.d.ts

@@ -1 +1,2 @@
+export { DefaultMainRendererDesktopConfigPublic as DefaultMainRendererDesktopConfig, DefaultMainRendererMobileConfigPublic as DefaultMainRendererMobileConfig } from './first-party/main-renderer/public-defaults.js';
 export { builtInExtensionFactoryMap, type BuiltInExtensionId } from './types/wrapper.js';

package/dist/extensions/index.js

@@ -1 +1,2 @@
+export { DefaultMainRendererDesktopConfigPublic as DefaultMainRendererDesktopConfig, DefaultMainRendererMobileConfigPublic as DefaultMainRendererMobileConfig } from './first-party/main-renderer/public-defaults.js';
 export { builtInExtensionFactoryMap } from './types/wrapper.js';

package/dist/extensions/types/basic/events.d.ts

@@ -11,29 +11,43 @@ export interface ScenePointerEvent {
     readonly targetSquare: Square | null;
 }
 export type SceneEvent = ScenePointerEvent;
-export type RuntimeInteractionActionStartLiftedDrag = {
-    type: 'startLiftedDrag';
-    source: Square;
-    target: Square;
+export type RuntimeInteractionActionStartPendingLiftedDragSession = {
+    type: 'startLiftedDragSession';
+    phase: 'pending';
+    sourceSquare: Square;
+    targetSquare: Square;
     startButton: number;
+    startPoint: ScenePoint;
+    thresholdPx: number;
 };
-export type RuntimeInteractionActionStartReleaseTargetingDrag = {
-    type: 'startReleaseTargetingDrag';
-    source: Square;
-    target: Square;
+export type RuntimeInteractionActionStartActiveLiftedDragSession = {
+    type: 'startLiftedDragSession';
+    phase: 'active';
+    sourceSquare: Square;
+    targetSquare: Square;
     startButton: number;
 };
-export type RuntimeInteractionActionCompleteCoreDrag = {
-    type: 'completeCoreDragTo';
-    target: Square;
+export type RuntimeInteractionActionActivatePendingLiftedDragSession = {
+    type: 'activatePendingLiftedDragSession';
+    targetSquare: Square | null;
 };
-export type RuntimeInteractionActionCompleteExtensionDrag = {
-    type: 'completeExtensionDrag';
-    target: Square | null;
+export type RuntimeInteractionActionStartReleaseTargetingDragSession = {
+    type: 'startReleaseTargetingDragSession';
+    sourceSquare: Square;
+    targetSquare: Square;
+    startButton: number;
+};
+export type RuntimeInteractionActionCompleteCoreDragSessionTo = {
+    type: 'completeCoreDragSessionTo';
+    targetSquare: Square;
+};
+export type RuntimeInteractionActionCompleteExtensionDragSession = {
+    type: 'completeExtensionDragSession';
+    targetSquare: Square | null;
 };
 export type RuntimeInteractionActionUpdateDragSessionCurrentTarget = {
     type: 'updateDragSessionCurrentTarget';
-    target: Square | null;
+    targetSquare: Square | null;
 };
 export type RuntimeInteractionActionCancelActiveInteraction = {
     type: 'cancelActiveInteraction';
@@ -41,5 +55,5 @@ export type RuntimeInteractionActionCancelActiveInteraction = {
 export type RuntimeInteractionActionCancelInteraction = {
     type: 'cancelInteraction';
 };
-export type RuntimeInteractionAction = RuntimeInteractionActionStartLiftedDrag | RuntimeInteractionActionStartReleaseTargetingDrag | RuntimeInteractionActionCompleteCoreDrag | RuntimeInteractionActionCompleteExtensionDrag | RuntimeInteractionActionUpdateDragSessionCurrentTarget | RuntimeInteractionActionCancelActiveInteraction | RuntimeInteractionActionCancelInteraction;
+export type RuntimeInteractionAction = RuntimeInteractionActionStartPendingLiftedDragSession | RuntimeInteractionActionStartActiveLiftedDragSession | RuntimeInteractionActionActivatePendingLiftedDragSession | RuntimeInteractionActionStartReleaseTargetingDragSession | RuntimeInteractionActionCompleteCoreDragSessionTo | RuntimeInteractionActionCompleteExtensionDragSession | RuntimeInteractionActionUpdateDragSessionCurrentTarget | RuntimeInteractionActionCancelActiveInteraction | RuntimeInteractionActionCancelInteraction;
 export {};

package/dist/extensions/types/basic/interaction.d.ts

@@ -1,15 +1,25 @@
-import { ReadonlyDeep } from 'type-fest';
+import type { ReadonlyDeep } from 'type-fest';
 import type { PieceCode, Square } from '../../../state/board/types/internal.js';
+import type { ScenePoint } from './transient-visuals.js';
 export interface ExtensionDragSessionBase {
     sourceSquare: Square | null;
     sourcePieceCode: PieceCode | null;
     targetSquare: Square | null;
     startButton: number;
 }
-export interface ExtensionDragSessionLiftedPiece extends ExtensionDragSessionBase {
+export interface ExtensionDragSessionLiftedPieceBase extends ExtensionDragSessionBase {
     type: 'lifted-piece-drag';
     sourcePieceCode: PieceCode;
 }
+export interface ExtensionDragSessionPendingLiftedPiece extends ExtensionDragSessionLiftedPieceBase {
+    phase: 'pending';
+    startPoint: ScenePoint;
+    thresholdPx: number;
+}
+export interface ExtensionDragSessionActiveLiftedPiece extends ExtensionDragSessionLiftedPieceBase {
+    phase: 'active';
+}
+export type ExtensionDragSessionLiftedPiece = ExtensionDragSessionPendingLiftedPiece | ExtensionDragSessionActiveLiftedPiece;
 export interface ExtensionDragSessionReleaseTargeting extends ExtensionDragSessionBase {
     type: 'release-targeting';
 }

package/dist/extensions/types/surface/commands.d.ts

@@ -2,8 +2,8 @@ import { LayoutSnapshot } from '../../../layout/types.js';
 import { ColorInput, MoveRequestInput, PiecePositionInput, PositionInput, SquareString } from '../../../state/board/types/input.js';
 import { Move } from '../../../state/board/types/internal.js';
 import { DeferredUIMoveResolutionDetails } from '../../../state/change/types/ui-move.js';
-import { MovabilityInput } from '../../../state/interaction/types/input.js';
-import { DragSessionExtensionOwned } from '../../../state/interaction/types/internal.js';
+import { InteractionConfigInput, MovabilityInput } from '../../../state/interaction/types/input.js';
+import { DragSessionExtensionOwned, InteractionConfigSnapshot } from '../../../state/interaction/types/internal.js';
 import { RuntimeStateSnapshot } from '../../../state/types.js';
 import { ExtensionDragSession } from '../basic/interaction.js';
 export interface ExtensionRuntimeSurfaceCommandsSnapshot {
@@ -25,6 +25,8 @@ export interface ExtensionRuntimeSurfaceCommands {
     startDrag(session: ExtensionDragSession): boolean;
     clearActiveInteraction(): boolean;
     clearInteraction(): boolean;
+    setInteractionConfig(config: InteractionConfigInput): boolean;
+    getInteractionConfig(): InteractionConfigSnapshot;
     resolveDeferredUIMoveRequest(details: DeferredUIMoveResolutionDetails): Move;
     cancelDeferredUIMoveRequest(): boolean;
     requestRender(request: ExtensionRuntimeSurfaceCommandsRenderRequest): boolean;

package/dist/runtime/factory/input.js

@@ -1,6 +1,7 @@
 import assert from '@ktarmyshov/assert';
 import { isEmptyPieceCode } from '../../state/board/check.js';
-import { isDragSessionCoreOwned } from '../../state/interaction/helpers.js';
+import { isDragSessionActiveLiftedPiece, isDragSessionCoreOwned, isDragSessionReleaseTargeting } from '../../state/interaction/helpers.js';
+import { isStartPendingLiftedDragSessionInput } from '../input/controller/helpers.js';
 import { runtimeRunMutationPipeline } from '../mutation/run.js';
 import { uiMoveCompleteTo } from './helpers.js';
 export function notifyExtensionCancelDragIfOwned(internalState, dragSession) {
@@ -18,68 +19,93 @@ export function createRuntimeInteractionSurface(state) {
             const internalState = state();
             return internalState.state.board.getPieceCodeAt(square);
         },
-        startLiftedDrag(source, target, startButton) {
+        startLiftedDragSession(input) {
             const internalState = state();
             const interactionMutationSession = internalState.mutation.getSession();
             const interaction = internalState.state.interaction;
-            const pieceCode = internalState.state.board.getPieceCodeAt(source);
+            const pieceCode = internalState.state.board.getPieceCodeAt(input.sourceSquare);
             assert(!isEmptyPieceCode(pieceCode), 'Cannot start a lifted-piece-drag session from an empty square');
             const interactionSource = {
-                square: source,
+                square: input.sourceSquare,
                 pieceCode
             };
             interaction.setSelected(interactionSource, interactionMutationSession);
-            const dragSession = {
-                owner: 'core',
-                type: 'lifted-piece-drag',
-                sourceSquare: interactionSource.square,
-                sourcePieceCode: interactionSource.pieceCode,
-                targetSquare: target,
-                startButton
-            };
+            const dragSession = isStartPendingLiftedDragSessionInput(input)
+                ? {
+                    owner: 'core',
+                    type: 'lifted-piece-drag',
+                    phase: 'pending',
+                    sourceSquare: interactionSource.square,
+                    sourcePieceCode: interactionSource.pieceCode,
+                    targetSquare: input.targetSquare,
+                    startButton: input.startButton,
+                    startPoint: input.startPoint,
+                    thresholdPx: input.thresholdPx
+                }
+                : {
+                    owner: 'core',
+                    type: 'lifted-piece-drag',
+                    phase: 'active',
+                    sourceSquare: interactionSource.square,
+                    sourcePieceCode: interactionSource.pieceCode,
+                    targetSquare: input.targetSquare,
+                    startButton: input.startButton
+                };
             interaction.setDragSession(dragSession, interactionMutationSession);
             runtimeRunMutationPipeline(internalState);
         },
+        activatePendingLiftedDragSession(input) {
+            const internalState = state();
+            const mutationSession = internalState.mutation.getSession();
+            const interaction = internalState.state.interaction;
+            interaction.activatePendingLiftedDragSession(input.targetSquare, mutationSession);
+            runtimeRunMutationPipeline(internalState);
+        },
         transientInput(input) {
             const internalState = state();
             internalState.renderSystem.requestRenderVisuals(input);
         },
-        completeCoreDragTo(target) {
+        completeCoreDragSessionTo(target) {
             const internalState = state();
             const mutationSession = internalState.mutation.getSession();
             const interaction = internalState.state.interaction;
+            const currentDragSession = interaction.dragSession;
+            assert(currentDragSession !== null &&
+                isDragSessionCoreOwned(currentDragSession) &&
+                (isDragSessionActiveLiftedPiece(currentDragSession) ||
+                    isDragSessionReleaseTargeting(currentDragSession)), 'completeCoreDragSessionTo requires a core-owned active lifted-piece or release-targeting drag session');
             interaction.updateDragSessionCurrentTarget(target, mutationSession);
             const dragSession = interaction.dragSession;
-            assert(isDragSessionCoreOwned(dragSession), 'completeDragTo can only be called for core-owned drag sessions');
             uiMoveCompleteTo(internalState, target);
-            mutationSession.addMutation('runtime.interaction.completeCoreDragTo', true, dragSession);
+            mutationSession.addMutation('runtime.interaction.completeCoreDragSessionTo', true, dragSession);
             runtimeRunMutationPipeline(internalState);
         },
-        completeExtensionDrag(target) {
+        completeExtensionDragSession(target) {
             const internalState = state();
             const mutationSession = internalState.mutation.getSession();
             const interaction = internalState.state.interaction;
+            const currentDragSession = interaction.dragSession;
+            assert(currentDragSession !== null && !isDragSessionCoreOwned(currentDragSession), 'completeExtensionDragSession can only be called for extension-owned drag sessions');
             interaction.updateDragSessionCurrentTarget(target, mutationSession);
             const dragSession = interaction.dragSession;
-            assert(!isDragSessionCoreOwned(dragSession), 'completeExtensionDrag can only be called for extension-owned drag sessions');
             internalState.extensionSystem.completeDrag(dragSession);
             internalState.state.interaction.setDragSession(null, mutationSession);
-            mutationSession.addMutation('runtime.interaction.completeExtensionDragTo', true, dragSession);
+            mutationSession.addMutation('runtime.interaction.completeExtensionDragSession', true, dragSession);
             runtimeRunMutationPipeline(internalState);
         },
-        startReleaseTargetingDrag(source, target, startButton) {
+        startReleaseTargetingDragSession(input) {
             const internalState = state();
             const mutationSession = internalState.mutation.getSession();
             const interaction = internalState.state.interaction;
-            assert(interaction.selected !== null, 'startReleaseTargetingDrag requires a selected piece');
-            assert(interaction.selected.square === source, 'startReleaseTargetingDrag source must match selected square');
+            assert(interaction.selected !== null, 'startReleaseTargetingDragSession requires a selected piece');
+            assert(interaction.selected.square === input.sourceSquare, 'startReleaseTargetingDragSession source must match selected square');
             const dragSession = {
                 owner: 'core',
                 type: 'release-targeting',
-                sourceSquare: source,
+                sourceSquare: input.sourceSquare,
                 sourcePieceCode: interaction.selected.pieceCode,
-                targetSquare: target,
-                startButton
+                targetSquare: input.targetSquare,
+                startButton: input.startButton
             };
             interaction.setDragSession(dragSession, mutationSession);
             runtimeRunMutationPipeline(internalState);

package/dist/runtime/factory/main.js

@@ -91,6 +91,17 @@ function createExtensionRuntimeSurfaceCommandsInternalSurface(getInternalState)
             runtimeRunMutationPipeline(state);
             return changed;
         },
+        setInteractionConfig(config) {
+            const state = getInternalState();
+            const mutationSession = state.mutation.getSession();
+            const changed = state.state.interaction.setConfig(config, mutationSession);
+            runtimeRunMutationPipeline(state);
+            return changed;
+        },
+        getInteractionConfig() {
+            const state = getInternalState();
+            return state.state.interaction.getConfig();
+        },
         select(square) {
             const state = getInternalState();
             const mutationSession = state.mutation.getSession();

package/dist/runtime/input/adapter/types.js

@@ -3,5 +3,6 @@ export const NEED_EVENT_TYPES = new Set([
     'pointermove',
     'pointerup',
     'pointercancel',
-    'lostpointercapture'
+    'lostpointercapture',
+    'dragstart'
 ]);

package/dist/runtime/input/controller/factory.js

@@ -19,22 +19,49 @@ export function createInteractionController(options) {
                 transmitTransientInput(internalState, context);
                 return; // The event has been handled by the surface (extensions)
             }
+            else if (context.rawEvent.type === 'dragstart') {
+                // Prevent native drag-and-drop behavior to avoid conflicts with custom drag handling
+                context.rawEvent.preventDefault();
+            }
             if (action) {
                 switch (action.type) {
-                    case 'startLiftedDrag':
-                        internalState.surface.startLiftedDrag(action.source, action.target, action.startButton);
+                    case 'startLiftedDragSession':
+                        internalState.surface.startLiftedDragSession(action.phase === 'pending'
+                            ? {
+                                phase: 'pending',
+                                sourceSquare: action.sourceSquare,
+                                targetSquare: action.targetSquare,
+                                startButton: action.startButton,
+                                startPoint: action.startPoint,
+                                thresholdPx: action.thresholdPx
+                            }
+                            : {
+                                phase: 'active',
+                                sourceSquare: action.sourceSquare,
+                                targetSquare: action.targetSquare,
+                                startButton: action.startButton
+                            });
+                        break;
+                    case 'activatePendingLiftedDragSession':
+                        internalState.surface.activatePendingLiftedDragSession({
+                            targetSquare: action.targetSquare
+                        });
                         break;
-                    case 'startReleaseTargetingDrag':
-                        internalState.surface.startReleaseTargetingDrag(action.source, action.target, action.startButton);
+                    case 'startReleaseTargetingDragSession':
+                        internalState.surface.startReleaseTargetingDragSession({
+                            sourceSquare: action.sourceSquare,
+                            targetSquare: action.targetSquare,
+                            startButton: action.startButton
+                        });
                         break;
-                    case 'completeCoreDragTo':
-                        internalState.surface.completeCoreDragTo(action.target);
+                    case 'completeCoreDragSessionTo':
+                        internalState.surface.completeCoreDragSessionTo(action.targetSquare);
                         break;
-                    case 'completeExtensionDrag':
-                        internalState.surface.completeExtensionDrag(action.target);
+                    case 'completeExtensionDragSession':
+                        internalState.surface.completeExtensionDragSession(action.targetSquare);
                         break;
                     case 'updateDragSessionCurrentTarget':
-                        internalState.surface.updateDragSessionCurrentTarget(action.target);
+                        internalState.surface.updateDragSessionCurrentTarget(action.targetSquare);
                         break;
                     case 'cancelActiveInteraction':
                         internalState.surface.cancelActiveInteraction();

package/dist/runtime/input/controller/helpers.d.ts

@@ -1,4 +1,9 @@
+import type { ScenePoint } from '../../../extensions/types/basic/transient-visuals.js';
 import type { Square } from '../../../state/board/types/internal.js';
 import type { InteractionStateSnapshot } from '../../../state/interaction/types/main.js';
+import type { StartActiveLiftedDragSessionInput, StartLiftedDragSessionInput, StartPendingLiftedDragSessionInput } from './types.js';
 export declare function buttonToButtonsMask(button: number): number | null;
 export declare function canMoveTo(snapshot: InteractionStateSnapshot, target: Square): boolean;
+export declare function isStartPendingLiftedDragSessionInput(input: StartLiftedDragSessionInput): input is StartPendingLiftedDragSessionInput;
+export declare function isStartActiveLiftedDragSessionInput(input: StartLiftedDragSessionInput): input is StartActiveLiftedDragSessionInput;
+export declare function isMovementBeyondThreshold(start: ScenePoint, current: ScenePoint, thresholdPx: number): boolean;

package/dist/runtime/input/controller/helpers.js

@@ -26,3 +26,14 @@ export function canMoveTo(snapshot, target) {
     // strict: target must be in the computed active destinations
     return snapshot.activeDestinations.has(target);
 }
+export function isStartPendingLiftedDragSessionInput(input) {
+    return input.phase === 'pending';
+}
+export function isStartActiveLiftedDragSessionInput(input) {
+    return input.phase === 'active';
+}
+export function isMovementBeyondThreshold(start, current, thresholdPx) {
+    const dx = current.x - start.x;
+    const dy = current.y - start.y;
+    return dx * dx + dy * dy >= thresholdPx * thresholdPx;
+}

package/dist/runtime/input/controller/pointer.js

@@ -1,8 +1,8 @@
 import assert from '@ktarmyshov/assert';
 import { isEmptyPieceCode, isNonEmptyPieceCode } from '../../../state/board/check.js';
 import { fromPieceCode } from '../../../state/board/piece.js';
-import { isDragSessionCoreOwned } from '../../../state/interaction/helpers.js';
-import { buttonToButtonsMask, canMoveTo } from './helpers.js';
+import { isDragSessionActiveLiftedPiece, isDragSessionCoreOwned, isDragSessionPendingLiftedPiece, isDragSessionReleaseTargeting } from '../../../state/interaction/helpers.js';
+import { buttonToButtonsMask, canMoveTo, isMovementBeyondThreshold } from './helpers.js';
 export function determineActionPointerDown(state, context) {
     assert(context.rawEvent.type === 'pointerdown', 'determineActionPointerDown should only be called for pointerdown events');
     const rawEvent = context.rawEvent;
@@ -29,9 +29,9 @@ export function determineActionPointerDown(state, context) {
             const targetPieceCode = state.surface.getPieceCodeAt(sceneEvent.targetSquare);
             if (isEmptyPieceCode(targetPieceCode)) {
                 return {
-                    type: 'startReleaseTargetingDrag',
-                    source: interaction.selected.square,
-                    target: sceneEvent.targetSquare,
+                    type: 'startReleaseTargetingDragSession',
+                    sourceSquare: interaction.selected.square,
+                    targetSquare: sceneEvent.targetSquare,
                     startButton: rawEvent.button
                 };
             }
@@ -41,9 +41,9 @@ export function determineActionPointerDown(state, context) {
             if (fromPieceCode(targetPieceCode).color !== fromPieceCode(selectedPieceCode).color &&
                 isLegalMoveTarget) {
                 return {
-                    type: 'startReleaseTargetingDrag',
-                    source: interaction.selected.square,
-                    target: sceneEvent.targetSquare,
+                    type: 'startReleaseTargetingDragSession',
+                    sourceSquare: interaction.selected.square,
+                    targetSquare: sceneEvent.targetSquare,
                     startButton: rawEvent.button
                 };
             }
@@ -54,10 +54,23 @@ export function determineActionPointerDown(state, context) {
          */
         const pieceCode = state.surface.getPieceCodeAt(sceneEvent.targetSquare);
         if (!isEmptyPieceCode(pieceCode)) {
+            const thresholdPx = interaction.config.drag.liftedActivation.thresholdPx;
+            if (thresholdPx > 0) {
+                return {
+                    type: 'startLiftedDragSession',
+                    phase: 'pending',
+                    sourceSquare: sceneEvent.targetSquare,
+                    targetSquare: sceneEvent.targetSquare,
+                    startButton: rawEvent.button,
+                    startPoint: sceneEvent.point,
+                    thresholdPx
+                };
+            }
             return {
-                type: 'startLiftedDrag',
-                source: sceneEvent.targetSquare,
-                target: sceneEvent.targetSquare,
+                type: 'startLiftedDragSession',
+                phase: 'active',
+                sourceSquare: sceneEvent.targetSquare,
+                targetSquare: sceneEvent.targetSquare,
                 startButton: rawEvent.button
             };
         }
@@ -67,13 +80,25 @@ export function determineActionPointerDown(state, context) {
 export function determineActionPointerMove(state, context) {
     assert(context.rawEvent.type === 'pointermove', 'determineActionPointerMove should only be called for pointermove events');
     const interaction = state.surface.getInteractionStateSnapshot();
-    if (interaction.dragSession) {
-        return {
-            type: 'updateDragSessionCurrentTarget',
-            target: context.sceneEvent?.targetSquare ?? null
-        };
+    const dragSession = interaction.dragSession;
+    if (!dragSession) {
+        return null;
     }
-    return null;
+    const sceneEvent = context.sceneEvent;
+    assert(sceneEvent, 'pointermove requires a scene event');
+    if (isDragSessionPendingLiftedPiece(dragSession)) {
+        if (isMovementBeyondThreshold(dragSession.startPoint, sceneEvent.point, dragSession.thresholdPx)) {
+            return {
+                type: 'activatePendingLiftedDragSession',
+                targetSquare: sceneEvent.targetSquare
+            };
+        }
+        return { type: 'updateDragSessionCurrentTarget', targetSquare: sceneEvent.targetSquare };
+    }
+    return {
+        type: 'updateDragSessionCurrentTarget',
+        targetSquare: sceneEvent.targetSquare
+    };
 }
 function determineActionTerminalRelease(state, context) {
     const interaction = state.surface.getInteractionStateSnapshot();
@@ -85,15 +110,17 @@ function determineActionTerminalRelease(state, context) {
     assert(sceneEvent, 'Scene event should be present for terminal release');
     if (!isDragSessionCoreOwned(dragSession)) {
         return {
-            type: 'completeExtensionDrag',
-            target: sceneEvent.targetSquare
+            type: 'completeExtensionDragSession',
+            targetSquare: sceneEvent.targetSquare
         };
     }
     if (sceneEvent.targetSquare === dragSession.sourceSquare) {
         return { type: 'cancelActiveInteraction' };
     }
-    if (sceneEvent.targetSquare !== null && canMoveTo(interaction, sceneEvent.targetSquare)) {
-        return { type: 'completeCoreDragTo', target: sceneEvent.targetSquare };
+    if (sceneEvent.targetSquare !== null &&
+        canMoveTo(interaction, sceneEvent.targetSquare) &&
+        (isDragSessionActiveLiftedPiece(dragSession) || isDragSessionReleaseTargeting(dragSession))) {
+        return { type: 'completeCoreDragSessionTo', targetSquare: sceneEvent.targetSquare };
     }
     if (dragSession.type === 'lifted-piece-drag') {
         return { type: 'cancelActiveInteraction' };

package/dist/runtime/input/controller/types.d.ts

@@ -1,14 +1,23 @@
 import type { TransientInput } from '../../../extensions/types/basic/transient-visuals.js';
 import type { ExtensionOnEventContext } from '../../../extensions/types/context/events.js';
 import type { PieceCode, Square } from '../../../state/board/types/internal.js';
+import type { DragSessionActiveLiftedPieceCoreOwned, DragSessionPendingLiftedPieceCoreOwned, DragSessionReleaseTargetingCoreOwned } from '../../../state/interaction/types/internal.js';
 import type { InteractionStateSnapshot } from '../../../state/interaction/types/main.js';
+export type StartPendingLiftedDragSessionInput = Pick<DragSessionPendingLiftedPieceCoreOwned, 'phase' | 'sourceSquare' | 'targetSquare' | 'startButton' | 'startPoint' | 'thresholdPx'>;
+export type StartActiveLiftedDragSessionInput = Pick<DragSessionActiveLiftedPieceCoreOwned, 'phase' | 'sourceSquare' | 'targetSquare' | 'startButton'>;
+export type StartLiftedDragSessionInput = StartPendingLiftedDragSessionInput | StartActiveLiftedDragSessionInput;
+export type ActivatePendingLiftedDragSessionInput = {
+    targetSquare: Square | null;
+};
+export type StartReleaseTargetingDragSessionInput = Pick<DragSessionReleaseTargetingCoreOwned, 'sourceSquare' | 'targetSquare' | 'startButton'>;
 export interface RuntimeInteractionSurface {
     getInteractionStateSnapshot(): InteractionStateSnapshot;
     getPieceCodeAt(square: Square): PieceCode;
-    startLiftedDrag(source: Square, target: Square, startButton: number): void;
-    startReleaseTargetingDrag(source: Square, target: Square, startButton: number): void;
-    completeCoreDragTo(target: Square): void;
-    completeExtensionDrag(target: Square | null): void;
+    startLiftedDragSession(input: StartLiftedDragSessionInput): void;
+    activatePendingLiftedDragSession(input: ActivatePendingLiftedDragSessionInput): void;
+    startReleaseTargetingDragSession(input: StartReleaseTargetingDragSessionInput): void;
+    completeCoreDragSessionTo(target: Square): void;
+    completeExtensionDragSession(target: Square | null): void;
     updateDragSessionCurrentTarget(target: Square | null): void;
     cancelActiveInteraction(): void;
     cancelInteraction(): void;

package/dist/runtime/mutation/interaction.js

@@ -4,7 +4,7 @@ export const reconcileInteractionSelectionAfterBoardStateChange = (context, muta
     const { current } = context;
     if (!mutationSession.hasMutation({ prefixes: ['state.board.'] }) ||
         mutationSession.hasMutation({
-            causes: ['state.interaction.clear', 'runtime.interaction.completeCoreDragTo']
+            causes: ['state.interaction.clear', 'runtime.interaction.completeCoreDragSessionTo']
         })) {
         return;
     }