@mirasen/chessboard 1.2.4 → 1.3.1

package/dist/extensions/first-party/main-renderer/pieces/suppress.js

@@ -1,6 +1,7 @@
+import { isDragSessionActiveLiftedPiece } from '../../../../state/interaction/helpers.js';
 export function calculateSuppressedSquares(_state, context, animationSuppressedSquares) {
     const dragSession = context.currentFrame.state.interaction.dragSession;
-    const dragSquare = dragSession?.type === 'lifted-piece-drag' ? dragSession.sourceSquare : null;
+    const dragSquare = dragSession && isDragSessionActiveLiftedPiece(dragSession) ? dragSession.sourceSquare : null;
     const result = new Set(animationSuppressedSquares);
     if (dragSquare !== null) {
         result.add(dragSquare);

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

@@ -0,0 +1,3 @@
+import type { MainRendererConfigPublic } from './types/public.js';
+export declare const DefaultMainRendererDesktopConfigPublic: MainRendererConfigPublic;
+export declare const DefaultMainRendererMobileConfigPublic: MainRendererConfigPublic;

package/dist/extensions/first-party/main-renderer/public-defaults.js

@@ -0,0 +1,4 @@
+import { denormalizeMainRendererConfig } from './denormalize.js';
+import { DefaultMainRendererDesktopConfig, DefaultMainRendererMobileConfig } from './types/internal.js';
+export const DefaultMainRendererDesktopConfigPublic = denormalizeMainRendererConfig(DefaultMainRendererDesktopConfig);
+export const DefaultMainRendererMobileConfigPublic = denormalizeMainRendererConfig(DefaultMainRendererMobileConfig);

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

@@ -1,11 +1,14 @@
-import { ExtensionDefinition, ExtensionInstance } from '../../../types/extension.js';
-import { MainRendererConfigInput } from './input.js';
-export type MainRendererInitOptions = Partial<MainRendererConfigInput>;
+import type { ExtensionDefinition, ExtensionInstance } from '../../../types/extension.js';
+import type { MainRendererConfigPublic, MainRendererSetConfigOptions } from './public.js';
 export declare const EXTENSION_SLOTS: readonly ["defs", "board", "coordinates", "pieces", "animation", "drag"];
 export type ExtensionSlotsType = typeof EXTENSION_SLOTS;
 export declare const EXTENSION_ID: "renderer";
-export type MainRendererDefinition = ExtensionDefinition<typeof EXTENSION_ID, typeof EXTENSION_SLOTS, never>;
-export type MainRendererInstance = ExtensionInstance<typeof EXTENSION_ID, typeof EXTENSION_SLOTS, never>;
+export interface RendererPublicAPI {
+    setConfig(options: MainRendererSetConfigOptions): void;
+    getConfig(): MainRendererConfigPublic;
+}
+export type MainRendererDefinition = ExtensionDefinition<typeof EXTENSION_ID, typeof EXTENSION_SLOTS, RendererPublicAPI>;
+export type MainRendererInstance = ExtensionInstance<typeof EXTENSION_ID, typeof EXTENSION_SLOTS, RendererPublicAPI>;
 export declare enum DirtyLayer {
     Board = 1,// 1 << 0,
     Coordinates = 2,// 1 << 1,

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

@@ -1,12 +1,13 @@
-import { ExtensionRuntimeSurface } from '../../../types/surface/main.js';
-import { ExtensionInternalBase } from '../../common/types.js';
-import { MainRendererAnimation } from '../animation/types.js';
-import { MainRendererBoard } from '../board/types.js';
-import { MainRendererCoordinates } from '../coordinates/types.js';
-import { MainRendererDrag } from '../drag/types.js';
+import type { ExtensionRuntimeSurface } from '../../../types/surface/main.js';
+import type { ExtensionInternalBase } from '../../common/types.js';
+import type { MainRendererAnimation } from '../animation/types.js';
+import type { MainRendererBoard } from '../board/types.js';
+import type { MainRendererCoordinates } from '../coordinates/types.js';
+import type { MainRendererDrag } from '../drag/types.js';
 import type { PieceSymbolResolver } from '../piece-symbols.js';
-import { MainRendererPieces } from '../pieces/types.js';
-import { ExtensionSlotsType } from './extension.js';
+import type { MainRendererPieces } from '../pieces/types.js';
+import type { ExtensionSlotsType } from './extension.js';
+import type { MainRendererConfig } from './internal.js';
 export interface MainRendererInstanceInternal extends ExtensionInternalBase<ExtensionSlotsType> {
     readonly board: MainRendererBoard;
     readonly coordinates: MainRendererCoordinates;
@@ -15,4 +16,5 @@ export interface MainRendererInstanceInternal extends ExtensionInternalBase<Exte
     readonly animation: MainRendererAnimation;
     readonly runtimeSurface: ExtensionRuntimeSurface;
     readonly pieceSymbolResolver: PieceSymbolResolver;
+    config: MainRendererConfig;
 }

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: 2,
+        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/index.d.ts

@@ -1,5 +1,15 @@
+import type { MainRendererConfigPublic } from './extensions/first-party/main-renderer/types/public.js';
+import { DefaultInteractionDesktopConfig, DefaultInteractionMobileConfig } from './state/interaction/config.js';
+import type { InteractionConfig } from './state/interaction/types/config.js';
 export type { ColorInput, MoveRequestInput, PiecePositionRecordString, PositionInput } from './state/board/types/input.js';
 export type { MoveOutput } from './state/board/types/output.js';
 export type { MovabilityInput, MoveDestinationInput } from './state/interaction/types/input.js';
 export { createBoard } from './wrapper/factory.js';
 export type { Chessboard, ChessboardExtensionInput, ChessboardInitOptions } from './wrapper/types.js';
+export interface ChessboardConfig {
+    readonly interaction: InteractionConfig;
+    readonly renderer: MainRendererConfigPublic;
+}
+export { DefaultInteractionDesktopConfig, DefaultInteractionMobileConfig };
+export declare const DefaultChessboardDesktopConfig: ChessboardConfig;
+export declare const DefaultChessboardMobileConfig: ChessboardConfig;

package/dist/index.js

@@ -1 +1,12 @@
+import { DefaultMainRendererDesktopConfig, DefaultMainRendererMobileConfig } from './extensions/index.js';
+import { DefaultInteractionDesktopConfig, DefaultInteractionMobileConfig } from './state/interaction/config.js';
 export { createBoard } from './wrapper/factory.js';
+export { DefaultInteractionDesktopConfig, DefaultInteractionMobileConfig };
+export const DefaultChessboardDesktopConfig = {
+    interaction: DefaultInteractionDesktopConfig,
+    renderer: DefaultMainRendererDesktopConfig
+};
+export const DefaultChessboardMobileConfig = {
+    interaction: DefaultInteractionMobileConfig,
+    renderer: DefaultMainRendererMobileConfig
+};

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;
+}