mumuki-puzzle-runner 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 441d4b26b7b8308cc9ed1ec7aca6de3c03905a6018af2db5d1d5e9889b72b55d
-  data.tar.gz: 5ccb1d263bc6e5c60f62d247006faa81d9a5647518939c0e9b2159092a3fdc45
+  metadata.gz: 725586c41840661a2deeb9f2cb179b0ca4181e9e7116f72d5a91cc0deaf2ac44
+  data.tar.gz: db8a8081c4f4f13e95300abce70767e2fe54649c98da2f0686c5712634fbf71f
 SHA512:
-  metadata.gz: d68ffd2617b06416d0e377a46c0bbb89f2728267d79866e31dc7afbaea88d9c22f1df2390ae0bac3a662c610ecc1f8234dec6bd9ca658d9714eea4412ef8e2fb
-  data.tar.gz: 5c83e99fc78f6f4043e65b5da66a1587a4398a3247d322985d5140976601d69feec3ebadcf9c1de0e86b1ce2208055414af1c87da08e97bf809ee256ff856877
+  metadata.gz: 98d5444f8a2ad9430ed1bb744770e522225a9295c3b1d1a478767c5bf255cb542e27ddfa1ba7ee2f625dc1536f37fe9850715b30501094649073d02caddb683a
+  data.tar.gz: a69f232d47d551d976d854856b4c40e5be94e8312e0dc2e32db2f8c16321136845fa6aca1565282ed66fe1728f0602142c05452313335fc3e8ba996936eb7016

data/lib/public/js/muzzle-editor.js

@@ -31,7 +31,6 @@ $(() => {
   // mumuki's solution processing
   const _onSubmit = Muzzle.onSubmit;
   Muzzle.onSubmit = (submission) => {
-    console.log(`submitting ${submission}`)
     mumuki.submission.processSolution(submission);
     _onSubmit(submission);
   }

data/lib/public/js/muzzle.js

@@ -73,6 +73,14 @@ class MuzzleCanvas {
      */
     this.canvasHeight = 600;
 
+    /**
+     * Wether canvas shoud **not** be resized.
+     * Default is `false`
+     *
+     * @type {boolean}
+     */
+    this.fixedDimensions = false;
+
     /**
      * Size of fill. Set null for perfect-match
      *
@@ -95,11 +103,20 @@ class MuzzleCanvas {
     this.pieceSize = 100;
 
     /**
-     * * Whether image's width should be scaled to piece
+     * The x:y aspect ratio of the piece. Set null for automatic
+     * aspectRatio
+     *
+     * @type {number}
+     */
+    this.aspectRatio = null;
+
+    /**
+     * If the images should be adjusted vertically instead of horizontally
+     * to puzzle dimensions. `false` by default
      *
      * @type {boolean}
      */
-    this.scaleImageWidthToFit = true;
+    this.fitImagesVertically = false;
 
     /**
      * Callback that will be executed
@@ -142,17 +159,27 @@ class MuzzleCanvas {
   /**
    */
   get baseConfig() {
+    const aspectRatio = this.aspectRatio || 1;
+    const pieceSize = headbreaker.vector(this.pieceSize / aspectRatio, this.pieceSize);
     return {
       width: this.canvasWidth,
       height: this.canvasHeight,
-      pieceSize: this.pieceSize,
-      proximity: this.pieceSize / 5,
-      borderFill: this.borderFill === null ? this.pieceSize / 10 : this.borderFill,
+      pieceSize: pieceSize,
+      proximity: pieceSize.x / 5,
+      borderFill: this.borderFill === null ? headbreaker.Vector.divide(pieceSize, 10) : this.borderFill,
       strokeWidth: this.strokeWidth,
       lineSoftness: 0.18
     };
   }
 
+  /**
+   * @type {Axis}
+   */
+  get imageAdjustmentAxis() {
+    console.log(this.fitImagesVertically)
+    return this.fitImagesVertically ? headbreaker.Vertical : headbreaker.Horizontal;
+  }
+
   /**
    * The currently active canvas, or null if
    * it has not yet initialized
@@ -195,15 +222,21 @@ class MuzzleCanvas {
    * @returns {Promise<Canvas>} the promise of the built canvas
    */
   async basic(x, y, imagePath) {
+    if (!this.aspectRatio) {
+      this.aspectRatio = x / y;
+    }
+
     /**
      * @todo take all container size
      **/
     const image = await this._loadImage(imagePath);
     /** @type {Canvas} */
     // @ts-ignore
-    const canvas = this._createCanvas(image);
+    const canvas = this._createCanvas({ image: image });
+    canvas.adjustImagesToPuzzle(this.imageAdjustmentAxis);
     canvas.autogenerate({ horizontalPiecesCount: x, verticalPiecesCount: y });
     this._attachBasicValidator(canvas);
+    canvas.shuffleGrid(0.8);
     this._configCanvas(canvas);
     canvas.onValid(() => {
       setTimeout(() => {
@@ -225,7 +258,7 @@ class MuzzleCanvas {
     const count = imagePaths.length;
     const images = await Promise.all(imagePaths.map(imagePath => this._loadImage(imagePath)));
 
-    const canvas = this._createCanvas(null);
+    const canvas = this._createCanvas();
     canvas.autogenerate({ horizontalPiecesCount: x, verticalPiecesCount: y * count });
 
     // todo validate
@@ -256,17 +289,20 @@ class MuzzleCanvas {
       const leftId = `l${i}`;
       const rightId = `r${i}`;
 
-      pushTemplate(leftUrls[i], {id: leftId, left: true, rightTargetId: rightId});
-      pushTemplate(rightUrls[i], {id: rightId});
+      pushTemplate(leftUrls[i], {id: leftId, targetPosition: { x: this.pieceSize, y: this.pieceSize * (i + 1) }, left: true, rightTargetId: rightId});
+      pushTemplate(rightUrls[i], {id: rightId, targetPosition: { x: 2 * this.pieceSize, y: this.pieceSize * (i + 1) }});
     }
 
-    leftOddUrls.forEach((it, i) =>  pushTemplate(it, {id: `lo${i}`, left: true, odd: true}));
-    rightOddUrls.forEach((it, i) => pushTemplate(it, {id: `ro${i}`, odd: true}));
+    leftOddUrls.forEach((it, i) =>  pushTemplate(it, {id: `lo${i}`, left: true, odd: true, targetPosition: { x: this.pieceSize, y: this.pieceSize * (i + leftUrls.length) }, }));
+    rightOddUrls.forEach((it, i) => pushTemplate(it, {id: `ro${i}`, odd: true, targetPosition: { x: 2 * this.pieceSize, y: this.pieceSize * (i + rightUrls.length) },}));
 
+    //  + Math.max(leftOddUrls.length, rightOddUrls.length)
     const templates = await Promise.all(templatePromises);
     /** @type {Canvas} */
-    const canvas = this._createCanvas();
+    const canvas = this._createCanvas({ maxPiecesCount: {x: 2, y: leftUrls.length} });
+    canvas.adjustImagesToPiece(this.imageAdjustmentAxis);
     templates.forEach(it => canvas.sketchPiece(it));
+    canvas.shuffleColumns(0.8);
     this._attachMatchValidator(canvas);
     this._configCanvas(canvas);
     return canvas;
@@ -283,19 +319,11 @@ class MuzzleCanvas {
 
   /**
    * @private
-   * @param {HTMLImageElement} image
+   * @param {any} config
    * @return {Canvas}
    */
-  _createCanvas(image = null) {
-    return new headbreaker.Canvas(this.canvasId, this._canvasConfig(image));
-  }
-
-  /**
-   * @private
-   * @param {HTMLImageElement} image
-   */
-  _canvasConfig(image) {
-    return Object.assign({ image }, this.baseConfig);
+  _createCanvas(config = {}) {
+    return new headbreaker.Canvas(this.canvasId, Object.assign(config, this.baseConfig));
   }
 
   /**
@@ -339,37 +367,17 @@ class MuzzleCanvas {
    * @param {object} options
    * @returns {Promise<object>}
    */
-  _createMatchTemplate(imagePath, {id, left = false, rightTargetId = null, odd = false}) {
+  _createMatchTemplate(imagePath, {id, left = false, targetPosition = null, rightTargetId = null, odd = false}) {
     const structure = left ? 'T-N-' : `N-S-`;
 
     return this._loadImage(imagePath).then((image) => {
-      const scale = this._imageScale(image);
-      const offset = this.baseConfig.borderFill / scale;
       return {
         structure,
-        metadata: {
-          id,
-          left,
-          odd,
-          rightTargetId,
-          image: {
-            scale,
-            content: image,
-            offset: { x: offset, y: offset }
-          }
-        }
+        metadata: { id, left, odd, rightTargetId, image, targetPosition }
       }
     });
   }
 
-  /**
-   * @private
-   * @param {HTMLImageElement} image
-   */
-  _imageScale(image) {
-    return this.scaleImageWidthToFit ? this.pieceSize / image.width  : 1;
-  }
-
   /**
    * @private
    * @param {Canvas} canvas
@@ -379,9 +387,23 @@ class MuzzleCanvas {
     this._canvas.onValid(() => {
       setTimeout(() => this.onValid(), 0);
     });
+    this._setupResponsiveness();
     this.ready();
   }
 
+  _setupResponsiveness() {
+    if (this.fixedDimensions) return;
+
+    ['resize', 'load'].forEach((event) => {
+      window.addEventListener(event, () => {
+        var container = document.getElementById(this.canvasId);
+        this.canvas.resize(container.offsetWidth, container.scrollHeight);
+        this.canvas.redraw();
+      });
+    });
+  }
+
+
   /**
    * Mark Muzzle as ready, loading previous solution
    * and drawing the canvas
@@ -426,8 +448,6 @@ class MuzzleCanvas {
       } catch (e) {
         console.warn("Ignoring unparseabe editor value");
       }
-    } else {
-      this.canvas.shuffle(0.8);
     }
   }
 

data/lib/public/vendor/headbreaker.d.ts

@@ -28,14 +28,14 @@ declare class Anchor {
     /**
      * Converts this anchor into a point
      */
-    asPoint(): Pair;
+    asPair(): Pair;
     /**
-     * Converts this anchor into a position
+     * Converts this anchor into a vector
      */
-    asPosition(): Position;
-    export(): Position;
+    asVector(): Vector;
+    export(): Vector;
     static atRandom(maxX: number, maxY: number): Anchor;
-    static import(position: Position): Anchor;
+    static import(vector: Vector): Anchor;
 }
 
 /**
@@ -43,6 +43,8 @@ declare class Anchor {
  */
 declare function anchor(x: number, y: number): Anchor;
 
+declare type Axis = Vertical | Horizontal;
+
 declare type Label = any;
 
 declare type Figure = {
@@ -76,9 +78,10 @@ declare type LabelMetadata = {
 
 declare type CanvasMetadata = {
     id?: string;
-    targetPosition?: Position;
-    currentPosition?: Position;
+    targetPosition?: Vector;
+    currentPosition?: Vector;
     color?: string;
+    fixed?: boolean;
     strokeColor?: string;
     image?: ImageLike;
     label?: LabelMetadata;
@@ -86,6 +89,7 @@ declare type CanvasMetadata = {
 
 declare type Template = {
     structure: StructureLike;
+    size?: Size;
     metadata: CanvasMetadata;
 };
 
@@ -93,25 +97,37 @@ declare type Template = {
  * An HTML graphical area where puzzles and pieces can be rendered. No assumption of the rendering backend is done - it may be
  * and be a plain HTML SVG or canvas element, or a higher-level library - and this task is fully delegated to {@link Painter}
  * @param id - the html id of the element where to place the canvas
+ * @param [options.pieceSize] - the piece size expresed as it edge-to-edge diameter
  * @param [options.borderFill] - the broder fill of the pieces, expresed in pixels. 0 means no border fill, 0.5 * pieceSize means full fill
  * @param [options.lineSoftness] - how soft the line will be
  * @param [options.image] - an optional background image for the puzzle that will be split across all pieces.
+ * @param [options.fixed] - whether the canvas can is fixed or can be dragged
  * @param [options.painter] - the Painter object used to actually draw figures in canvas
+ * @param [options.puzzleDiameter] - the puzzle diameter used to calculate the maximal width and height
+ *                                                                    You only need to specify this option when pieces are manually sketched and images must be adjusted
+ * @param [options.maxPiecesCount] - the maximal amount of pieces used to calculate the maximal width and height.
+ *                                                                    You only need to specify this option when pieces are manually sketched and images must be adjusted
  */
 declare class Canvas {
     constructor(id: string, options: {
         width: number;
         height: number;
-        pieceSize?: number;
+        pieceSize?: Vector | number;
         proximity?: number;
-        borderFill?: number;
+        borderFill?: Vector | number;
         strokeWidth?: number;
         strokeColor?: string;
         lineSoftness?: number;
         image?: ImageLike;
+        fixed?: boolean;
         painter?: Painter;
+        puzzleDiameter?: Vector | number;
+        maxPiecesCount?: Vector | number;
     });
     _painter: Painter;
+    _maxPiecesCount: Vector;
+    _puzzleDiameter: Vector;
+    _imageAdjuster: any;
     _puzzle: Puzzle;
     figures: {
         [key: string]: Figure;
@@ -133,7 +149,7 @@ declare class Canvas {
     renderPieces(pieces: Piece[]): void;
     /**
      * Renders a previously created puzzle object. This method
-     * overrides this canvas' {@link Canvas#pieceSize} and {@link Canvas#proximity}
+     * overrides this canvas' {@link Canvas#pieceDiameter} and {@link Canvas#proximity}
      */
     renderPuzzle(puzzle: Puzzle): void;
     /**
@@ -157,9 +173,17 @@ declare class Canvas {
      */
     sketchPieceUsingTemplate(id: string, templateName: string): void;
     /**
-     * @param farness - from 0 to 1, how far pieces will be placed from x = pieceSize, y = pieceSize
+     * @param farness - from 0 to 1, how far pieces will be placed from x = pieceDiameter.x, y = pieceDiameter.y
      */
     shuffle(farness?: number): void;
+    /**
+     * **Warning**: this method requires {@code maxPiecesCount} to be set.
+     */
+    shuffleColumns(farness?: number): void;
+    /**
+     * **Warning**: this method requires {@code maxPiecesCount} to be set.
+     */
+    shuffleGrid(farness?: number): void;
     /**
      * Draws this canvas for the first time
      */
@@ -222,6 +246,14 @@ declare class Canvas {
      * Answers the visual representation for the given piece id.
      */
     getFigureById(id: string): Figure;
+    /**
+     * Sets the new width and height of the canvas
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Scales the canvas contents to the given factor
+     */
+    scale(factor: Vector | number): void;
     _annotatePiecePosition(piece: Piece): void;
     /**
      * Configures updates from piece into group
@@ -231,8 +263,59 @@ declare class Canvas {
      * * Configures updates from group into piece
      */
     _bindPieceToGroup(piece: Piece, group: Group): void;
-    _imageMetadataFor(model: Piece): ImageMetadata;
-    _newPiece(structureLike: StructureLike, metadata: CanvasMetadata): void;
+    _baseImageMetadataFor(piece: Piece): ImageMetadata;
+    imageMetadataFor(piece: Piece): ImageMetadata;
+    /**
+     * Configures canvas to adjust images axis to puzzle's axis.
+     *
+     * **Warning**: this method requires {@code maxPiecesCount} or {@code puzzleDiameter} to be set.
+     */
+    adjustImagesToPuzzle(axis: Axis): void;
+    /**
+     * Configures canvas to adjust images width to puzzle's width
+     *
+     * **Warning**: this method requires {@code maxPiecesCount} or {@code puzzleDiameter} to be set.
+     */
+    adjustImagesToPuzzleWidth(): void;
+    /**
+     * Configures canvas to adjust images height to puzzle's height
+     *
+     * **Warning**: this method requires {@code maxPiecesCount} or {@code puzzleDiameter} to be set.
+     */
+    adjustImagesToPuzzleHeight(): void;
+    /**
+     * Configures canvas to adjust images axis to pieces's axis
+     *
+     * **Warning**: this method requires {@code maxPiecesCount} or {@code puzzleDiameter} to be set.
+     */
+    adjustImagesToPiece(axis: Axis): void;
+    /**
+     * Configures canvas to adjust images width to pieces's width
+     *
+     * **Warning**: this method requires {@code maxPiecesCount} or {@code puzzleDiameter} to be set.
+     */
+    adjustImagesToPieceWidth(): void;
+    /**
+     * Configures canvas to adjust images height to pieces's height
+     *
+     * **Warning**: this method requires {@code maxPiecesCount} or {@code puzzleDiameter} to be set.
+     */
+    adjustImagesToPieceHeight(): void;
+    /**
+     * @param structureLike - the piece structure
+     */
+    _newPiece(structureLike: StructureLike, size: Size, metadata: CanvasMetadata): void;
+    /**
+     * The puzzle diameter, using the
+     * configured puzzle diameter or the estimated one, if the first is not available.
+     */
+    puzzleDiameter: Vector;
+    /**
+     * The estimated puzzle diameter calculated using the the max pieces count.
+     */
+    estimatedPuzzleDiameter: Vector;
+    pieceRadio: Vector;
+    pieceDiameter: Vector;
     /**
      * The puzzle rendered by this canvas
      */
@@ -254,7 +337,7 @@ declare class DummyPainter implements Painter {
 
 declare type ImageMetadata = {
     content: HTMLImageElement;
-    offset?: Position;
+    offset?: Vector;
     scale?: number;
 };
 
@@ -284,6 +367,8 @@ declare class KonvaPainter implements Painter {
     initialize(canvas: Canvas, id: string): void;
     draw(canvas: Canvas): void;
     reinitialize(canvas: Canvas): void;
+    resize(canvas: Canvas, width: number, height: number): void;
+    scale(canvas: Canvas, factor: Vector): void;
     sketch(canvas: Canvas, piece: Piece, figure: Figure): void;
     label(_canvas: Canvas, piece: Piece, figure: Figure): void;
     physicalTranslate(_canvas: Canvas, group: Group, piece: Piece): void;
@@ -326,6 +411,8 @@ declare class Manufacturer {
 
 declare class Positioner {
     constructor(puzzle: Puzzle, headAnchor: Anchor);
+    initializeOffset(headAnchor: Anchor): void;
+    offset: Vector;
     naturalAnchor(x: number, y: number): void;
 }
 
@@ -344,7 +431,7 @@ declare module "Metadata" {
  */
 declare module "Outline" {
     function select(insert: Insert, t: number, s: number, n: number): void;
-    function draw(piece: Piece, size?: number): number[];
+    function draw(piece: Piece, size?: Vector | number, borderFill?: Vector | number): number[];
 }
 
 declare type VectorAction = (dx: number, dy: number) => void;
@@ -356,6 +443,7 @@ declare type Action = () => void;
  * order to create UI representations of a puzzle.
  */
 declare interface Painter {
+    resize(canvas: Canvas, width: number, height: number): void;
     /**
      * Creates the rendering backend, initializig all its contents.
      * After this call, painter is ready to receive any other messages
@@ -371,6 +459,10 @@ declare interface Painter {
      * Draws the canvas figures in the rendering backend
      */
     draw(canvas: Canvas): void;
+    /**
+     * Scales the canvas contents
+     */
+    scale(canvas: Canvas, factor: Vector): void;
     /**
      * Adds a piece to the rendering backend, so that it is ready to be drawn
      * @param figure - the rendering backend information for this piece. This method may mutate it if necessary
@@ -404,7 +496,10 @@ declare module "Pair" {
      * Tells whether this pair is (0, 0)
      */
     function isNull(x: number, y: number): boolean;
-    function equal(x1: number, y1: number, x2: number, y2: number): boolean;
+    /**
+     * @param [delta = 0] - tolerance in comparison
+     */
+    function equal(x1: number, y1: number, x2: number, y2: number, delta?: number): boolean;
     /**
      * Calculates the difference of two vectors
      */
@@ -415,25 +510,39 @@ declare type TranslationListener = (piece: Piece, dx: number, dy: number) => voi
 
 declare type ConnectionListener = (piece: Piece, target: Piece) => void;
 
+declare type PieceConfig = {
+    centralAnchor?: Vector;
+    size?: Size;
+    metadata?: any;
+};
+
 /**
  * A piece primitive representation that can be easily stringified, exchanged and persisted
  */
 declare type PieceDump = {
-    centralAnchor: Position;
-    structure: string;
-    connections?: Orthogonal<object>;
+    centralAnchor: Vector;
+    size?: Size;
     metadata: any;
+    connections?: Orthogonal<object>;
+    structure: string;
 };
 
 /**
  * A jigsaw piece
  */
 declare class Piece {
-    constructor(options?: Structure);
+    constructor(structure?: Structure, config?: PieceConfig);
+    metadata: any;
     centralAnchor: Anchor;
+    _size: Size;
     translateListeners: TranslationListener[];
     connectListeners: ConnectionListener[];
     disconnectListeners: ConnectionListener[];
+    /**
+     * Runs positining, sizing and metadata configurations
+     * in a single step
+     */
+    configure(config: PieceConfig): void;
     /**
      * Adds unestructured user-defined metadata on this piece.
      */
@@ -523,7 +632,16 @@ declare class Piece {
     rightAnchor: Anchor;
     upAnchor: Anchor;
     leftAnchor: Anchor;
-    size: number;
+    /**
+     * Defines this piece's own dimmension, overriding puzzle's
+     * default dimmension
+     */
+    resize(size: Size): void;
+    radio: Vector;
+    /**
+     * The double of the radio
+     */
+    diameter: Vector;
     proximity: number;
     /**
      * This piece id. It is extracted from metadata
@@ -543,37 +661,6 @@ declare class Piece {
     static import(dump: PieceDump): Piece;
 }
 
-declare type Position = {
-    x: number;
-    y: number;
-};
-
-declare function position(x: number, y: number): Position;
-
-/**
- * This module contains functions for dealing with objects with x and y
- * coordinates that represent or include point data
- */
-declare module "Position" {
-    /**
-     * Returns a new (0, 0) position
-     */
-    function origin(): Position;
-    /**
-     * Compares two points
-     */
-    function equal(one: Position, other: Position): boolean;
-    /**
-     * Creates a copy of the given point
-     */
-    function copy(one: Position): Position;
-    function update(position: Position, x: any, y: any): void;
-    /**
-     * @returns ;
-     */
-    function diff(one: Position, other: Position): Pair;
-}
-
 declare type Orthogonal = {
     up: A;
     down: A;
@@ -597,13 +684,13 @@ declare module "Prelude" {
  * A puzzle primitive representation that can be easily stringified, exchanged and persisted
  */
 declare type PuzzleDump = {
-    pieceSize: number;
+    pieceRadio: Vector;
     proximity: number;
     pieces: PieceDump[];
 };
 
 declare type Settings = {
-    pieceSize?: number;
+    pieceRadio?: Vector | number;
     proximity?: number;
 };
 
@@ -617,10 +704,11 @@ declare class Puzzle {
     validator: Validator;
     /**
      * Creates and adds to this puzzle a new piece
-     * @param [options] - the piece structure
+     * @param [structure] - the piece structure
+     * @param [config] - the piece config
      * @returns the new piece
      */
-    newPiece(options?: Structure): Piece;
+    newPiece(structure?: Structure, config?: PieceConfig): Piece;
     addPiece(piece: Piece): void;
     addPieces(pieces: Piece[]): void;
     /**
@@ -646,6 +734,7 @@ declare class Puzzle {
      */
     autoconnectWith(piece: Piece): void;
     shuffle(maxX: number, maxY: number): void;
+    shuffleWith(shuffler: Shuffler): void;
     translate(dx: number, dy: number): void;
     onTranslate(f: TranslationListener): void;
     onConnect(f: ConnectionListener): void;
@@ -701,9 +790,13 @@ declare class Puzzle {
     connected: boolean;
     /**
      * The piece width, from edge to edge.
-     * This is the double of the {@link Puzzle#pieceSize}
+     * This is the double of the {@link Puzzle#pieceRadio}
      */
-    pieceWidth: number;
+    pieceDiameter: Vector;
+    /**
+     * The piece width, from center to edge
+     */
+    pieceRadio: Vector;
     /**
      * Converts this piece into a plain, stringify-ready object.
      * Pieces should have ids
@@ -758,9 +851,30 @@ declare module "sequence" {
     }
 }
 
+declare function random(maxX: number, maxY: number): Shuffler;
+
+declare function grid(): void;
+
+declare function columns(): void;
+
+declare function padder(padding: number, width: number, height: number): Shuffler;
+
+declare function noise(maxDistance: Vector): Shuffler;
+
+declare function noop(): void;
+
+declare type Size = {
+    radio: Vector;
+    diameter: Vector;
+};
+
+declare function radio(value: Vector | number): Size;
+
+declare function diameter(value: Vector | number): Size;
+
 declare type SpatialMetadata = {
-    targetPosition?: Position;
-    currentPosition?: Position;
+    targetPosition?: Vector;
+    currentPosition?: Vector;
 };
 
 /**
@@ -768,10 +882,11 @@ declare type SpatialMetadata = {
  * and pieces and puzzles that are annotated with it
  */
 declare module "SpatialMetadata" {
+    function diffToTarget(piece: Piece): void;
     function solved(): void;
     function relativePosition(): void;
     function absolutePosition(): void;
-    function initialize(metadata: SpatialMetadata, target: Position, current?: Position): void;
+    function initialize(metadata: SpatialMetadata, target: Vector, current?: Vector): void;
 }
 
 declare type Structure = {
@@ -852,3 +967,42 @@ declare class NullValidator {
     isNull: boolean;
 }
 
+declare type Vector = {
+    x: number;
+    y: number;
+};
+
+declare function vector(x: number, y: number): Vector;
+
+declare function cast(value: Vector | number): Vector;
+
+/**
+ * This module contains functions for dealing with objects with x and y
+ * coordinates that represent or include point data
+ */
+declare module "Vector" {
+    /**
+     * Returns a new (0, 0) vector
+     */
+    function zero(): Vector;
+    /**
+     * Compares two points
+     * @param [delta = 0] - the tolance in comparison
+     */
+    function equal(one: Vector, other: Vector, delta?: number): boolean;
+    /**
+     * Creates a copy of the given point
+     */
+    function copy(one: Vector): Vector;
+    function update(vector: Vector, x: any, y: any): void;
+    /**
+     * @returns ;
+     */
+    function diff(one: Vector, other: Vector): Pair;
+    function multiply(one: Vector | number, other: Vector | number): Vector;
+    function divide(one: Vector | number, other: Vector | number): Vector;
+    function plus(one: Vector | number, other: Vector | number): Vector;
+    function minus(one: Vector | number, other: Vector | number): Vector;
+    function apply(one: Vector | number, other: Vector | number, f: any): Vector;
+}
+