magic-canvas-yonava 1.0.0

package/README.md

@@ -0,0 +1 @@
+# magic-canvas

package/dist/MagicCanvas.vue.d.ts

@@ -0,0 +1,9 @@
+declare const __VLS_export: import("vue").DefineComponent<{
+    canvasRef: (canvas: HTMLCanvasElement) => void;
+    cleanup: (canvas: HTMLCanvasElement) => void;
+}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{
+    canvasRef: (canvas: HTMLCanvasElement) => void;
+    cleanup: (canvas: HTMLCanvasElement) => void;
+}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/MagicCanvas.vue.js

@@ -0,0 +1,36 @@
+import { twMerge } from "tailwind-merge";
+import { onBeforeUnmount, onMounted, ref } from "vue";
+const props = defineProps();
+const canvas = ref();
+onMounted(() => {
+    if (!canvas.value)
+        throw new Error("Canvas not found in DOM. Check ref link.");
+    props.canvasRef(canvas.value);
+});
+onBeforeUnmount(() => {
+    if (!canvas.value)
+        throw new Error("Canvas not found in DOM. Check ref link.");
+    props.cleanup(canvas.value);
+});
+const __VLS_ctx = {
+    ...{},
+    ...{},
+    ...{},
+    ...{},
+};
+let __VLS_components;
+let __VLS_intrinsics;
+let __VLS_directives;
+__VLS_asFunctionalElement1(__VLS_intrinsics.canvas, __VLS_intrinsics.canvas)({
+    ...({
+        ...__VLS_ctx.$attrs,
+        class: __VLS_ctx.twMerge(__VLS_ctx.$attrs.class, ['w-full', 'h-full']),
+    }),
+    ref: "canvas",
+});
+// @ts-ignore
+[$attrs, $attrs, twMerge,];
+const __VLS_export = (await import('vue')).defineComponent({
+    __typeProps: {},
+});
+export default {};

package/dist/backgroundPattern.d.ts

@@ -0,0 +1,6 @@
+import type { Camera } from './camera';
+import type { Coordinate, DrawFns } from './types';
+export type DrawPattern = (ctx: CanvasRenderingContext2D, at: Coordinate, alpha: string) => void;
+export declare const useBackgroundPattern: ({ panX, panY, zoom }: Camera["state"], drawPattern: DrawFns["backgroundPattern"]) => {
+    draw: (ctx: CanvasRenderingContext2D) => void;
+};

package/dist/backgroundPattern.js

@@ -0,0 +1,36 @@
+import { getMagicCoordinates } from './coordinates';
+const STAGGER = 100;
+const START_PATTERN_FADE_OUT = 0.6;
+const PATTERN_FULLY_FADED_OUT = 0.25;
+const computeAlpha = (z) => {
+    if (z <= PATTERN_FULLY_FADED_OUT)
+        return '00';
+    if (z >= START_PATTERN_FADE_OUT)
+        return '';
+    const strPercent = String(Math.floor(((z - PATTERN_FULLY_FADED_OUT) /
+        (START_PATTERN_FADE_OUT - PATTERN_FULLY_FADED_OUT)) *
+        100));
+    return strPercent.length === 1 ? `0${strPercent}` : strPercent;
+};
+export const useBackgroundPattern = ({ panX, panY, zoom }, drawPattern) => {
+    const draw = (ctx) => {
+        if (zoom.value <= PATTERN_FULLY_FADED_OUT)
+            return;
+        const startingCoords = getMagicCoordinates({
+            clientX: 0,
+            clientY: 0,
+        }, ctx);
+        const endingCoords = getMagicCoordinates({
+            clientX: window.innerWidth + STAGGER,
+            clientY: window.innerHeight + STAGGER,
+        }, ctx);
+        const offsetX = (panX.value / zoom.value) % STAGGER;
+        const offsetY = (panY.value / zoom.value) % STAGGER;
+        for (let x = startingCoords.x + offsetX; x < endingCoords.x; x += STAGGER) {
+            for (let y = startingCoords.y + offsetY; y < endingCoords.y; y += STAGGER) {
+                drawPattern.value(ctx, { x, y }, computeAlpha(zoom.value));
+            }
+        }
+    };
+    return { draw };
+};

package/dist/camera/index.d.ts

@@ -0,0 +1,15 @@
+import type { Ref } from 'vue';
+export declare const useCamera: (canvas: Ref<HTMLCanvasElement | undefined>, storageKey: string) => {
+    transformAndClear: (ctx: CanvasRenderingContext2D) => void;
+    actions: {
+        zoomIn: (increment?: number) => void;
+        zoomOut: (decrement?: number) => void;
+    };
+    state: {
+        panX: import("@vueuse/shared").RemovableRef<number>;
+        panY: import("@vueuse/shared").RemovableRef<number>;
+        zoom: import("@vueuse/shared").RemovableRef<number>;
+    };
+    cleanup: (ref: HTMLCanvasElement) => void;
+};
+export type Camera = ReturnType<typeof useCamera>;

package/dist/camera/index.js

@@ -0,0 +1,20 @@
+import { usePanAndZoom } from './panZoom';
+import { addTransform, getDevicePixelRatio, } from './utils';
+export const useCamera = (canvas, storageKey) => {
+    const { getTransform: getPZTransform, ...rest } = usePanAndZoom(canvas, storageKey);
+    const dpr = getDevicePixelRatio();
+    const dprTransform = {
+        scaleX: dpr,
+        scaleY: dpr,
+    };
+    return {
+        ...rest,
+        transformAndClear: (ctx) => {
+            ctx.resetTransform();
+            ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
+            const transforms = [dprTransform, getPZTransform()];
+            for (const t of transforms)
+                addTransform(ctx, t);
+        },
+    };
+};

package/dist/camera/panZoom.d.ts

@@ -0,0 +1,23 @@
+import { type Ref } from "vue";
+export declare const MIN_ZOOM = 0.2;
+export declare const MAX_ZOOM = 10;
+export declare const ZOOM_SENSITIVITY = 0.02;
+export declare const PAN_SENSITIVITY = 1;
+export declare const usePanAndZoom: (canvas: Ref<HTMLCanvasElement | undefined>, storageKey: string) => {
+    actions: {
+        zoomIn: (increment?: number) => void;
+        zoomOut: (decrement?: number) => void;
+    };
+    state: {
+        panX: import("@vueuse/shared").RemovableRef<number>;
+        panY: import("@vueuse/shared").RemovableRef<number>;
+        zoom: import("@vueuse/shared").RemovableRef<number>;
+    };
+    getTransform: () => {
+        scaleX: number;
+        scaleY: number;
+        translateX: number;
+        translateY: number;
+    };
+    cleanup: (ref: HTMLCanvasElement) => void;
+};

package/dist/camera/panZoom.js

@@ -0,0 +1,100 @@
+import { useLocalStorage } from "@vueuse/core";
+import { localKeys } from "../localStorage";
+import { onMounted } from "vue";
+import { MOUSE_BUTTONS } from "magic-utils-yonava";
+export const MIN_ZOOM = 0.2;
+export const MAX_ZOOM = 10;
+export const ZOOM_SENSITIVITY = 0.02;
+export const PAN_SENSITIVITY = 1;
+export const usePanAndZoom = (canvas, storageKey) => {
+    const panX = useLocalStorage(localKeys.cameraPanX(storageKey), 0);
+    const panY = useLocalStorage(localKeys.cameraPanY(storageKey), 0);
+    const zoom = useLocalStorage(localKeys.cameraZoom(storageKey), 1);
+    const setZoom = (ev) => {
+        const rect = canvas.value.getBoundingClientRect();
+        const cx = ev.clientX - rect.left;
+        const cy = ev.clientY - rect.top;
+        // clamp deltaY to a max range to prevent mice with large deltaY notches from feeling too sensitive
+        const normalizedDelta = Math.max(-100, Math.min(100, ev.deltaY));
+        const zoomFactor = Math.exp(-normalizedDelta * ZOOM_SENSITIVITY);
+        const clampedZoom = Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, zoom.value * zoomFactor));
+        const scale = clampedZoom / zoom.value;
+        panX.value = cx - (cx - panX.value) * scale;
+        panY.value = cy - (cy - panY.value) * scale;
+        zoom.value = clampedZoom;
+    };
+    const setPan = (ev) => {
+        panX.value -= ev.deltaX * PAN_SENSITIVITY;
+        panY.value -= ev.deltaY * PAN_SENSITIVITY;
+    };
+    const onWheel = (ev) => {
+        ev.preventDefault();
+        const isPanning = !ev.ctrlKey;
+        const maneuverCamera = isPanning ? setPan : setZoom;
+        maneuverCamera(ev);
+    };
+    let lastX = 0;
+    let lastY = 0;
+    let middleMouseDown = false;
+    const onMousedown = (ev) => {
+        middleMouseDown = ev.button === MOUSE_BUTTONS.middle;
+        if (!middleMouseDown)
+            return;
+        lastX = ev.clientX;
+        lastY = ev.clientY;
+    };
+    const onMousemove = (ev) => {
+        if (!middleMouseDown)
+            return;
+        setPan({
+            deltaX: lastX - ev.clientX,
+            deltaY: lastY - ev.clientY,
+        });
+        lastX = ev.clientX;
+        lastY = ev.clientY;
+    };
+    const onMouseup = () => {
+        lastX = 0;
+        lastY = 0;
+        middleMouseDown = false;
+    };
+    onMounted(() => {
+        if (!canvas.value)
+            throw new Error("canvas not found in DOM");
+        canvas.value.addEventListener("wheel", onWheel, { passive: false });
+        canvas.value.addEventListener("mousedown", onMousedown);
+        canvas.value.addEventListener("mousemove", onMousemove);
+        document.addEventListener("mouseup", onMouseup);
+    });
+    return {
+        actions: {
+            zoomIn: (increment = 12.5) => setZoom({
+                deltaY: -increment,
+                clientX: window.innerWidth / 2,
+                clientY: window.innerHeight / 2,
+            }),
+            zoomOut: (decrement = 12.5) => setZoom({
+                deltaY: decrement,
+                clientX: window.innerWidth / 2,
+                clientY: window.innerHeight / 2,
+            }),
+        },
+        state: {
+            panX,
+            panY,
+            zoom,
+        },
+        getTransform: () => ({
+            scaleX: zoom.value,
+            scaleY: zoom.value,
+            translateX: panX.value,
+            translateY: panY.value,
+        }),
+        cleanup: (ref) => {
+            ref.removeEventListener("wheel", onWheel);
+            ref.removeEventListener("mousedown", onMousedown);
+            ref.removeEventListener("mousemove", onMousemove);
+            document.removeEventListener("mouseup", onMouseup);
+        },
+    };
+};

package/dist/camera/utils.d.ts

@@ -0,0 +1,17 @@
+export type TransformProps = {
+    /** corresponds to `a` in {@link CanvasRenderingContext2D.setTransform} */
+    scaleX: number;
+    /** corresponds to `b` in {@link CanvasRenderingContext2D.setTransform} */
+    skewY: number;
+    /** corresponds to `c` in {@link CanvasRenderingContext2D.setTransform} */
+    skewX: number;
+    /** corresponds to `d` in {@link CanvasRenderingContext2D.setTransform} */
+    scaleY: number;
+    /** corresponds to `e` in {@link CanvasRenderingContext2D.setTransform} */
+    translateX: number;
+    /** corresponds to `f` in {@link CanvasRenderingContext2D.setTransform} */
+    translateY: number;
+};
+export type TransformOptions = Partial<TransformProps>;
+export declare const getDevicePixelRatio: () => number;
+export declare const addTransform: (ctx: CanvasRenderingContext2D, t: TransformOptions) => void;

package/dist/camera/utils.js

@@ -0,0 +1,18 @@
+export const getDevicePixelRatio = () => window.devicePixelRatio ?? 1;
+export const addTransform = (ctx, t) => {
+    const translateX = t.translateX ?? 0;
+    const translateY = t.translateY ?? 0;
+    if (translateX !== 0 || translateY !== 0) {
+        ctx.translate(translateX, translateY);
+    }
+    const scaleX = t.scaleX ?? 1;
+    const scaleY = t.scaleY ?? 1;
+    if (scaleX !== 1 || scaleY !== 1) {
+        ctx.scale(scaleX, scaleY);
+    }
+    const skewX = t.skewX ?? 0;
+    const skewY = t.skewY ?? 0;
+    if (skewX !== 0 || skewY !== 0) {
+        ctx.transform(1, skewY, skewX, 1, 0, 0);
+    }
+};

package/dist/coordinates/index.d.ts

@@ -0,0 +1,44 @@
+import { type Ref } from "vue";
+import { Coordinate } from "../types";
+export declare const getCanvasTransform: (ctx: CanvasRenderingContext2D) => {
+    panX: number;
+    panY: number;
+    zoom: number;
+};
+/**
+ * the coordinates in the real world. aka the browser
+ */
+export type ClientCoords = Pick<MouseEvent, "clientX" | "clientY">;
+/**
+ * the coordinates in the magic canvas world
+ */
+export type MagicCoords = Coordinate;
+export type WithZoom<T> = T & {
+    /**
+     * the scale factor of the canvas
+     */
+    zoom: number;
+};
+/**
+ * magic coordinates are coordinates transformed by the pan and zoom of the camera.
+ *
+ * if the user has panned their camera 10px to the left, running this function with
+ * `clientCoords` set to (0, 0) will return (-10, 0, 1)
+ */
+export declare const getMagicCoordinates: (clientCoords: ClientCoords, ctx: CanvasRenderingContext2D) => WithZoom<MagicCoords>;
+/**
+ * client coordinates are the raw coordinates corresponding to the clients physical screen.
+ *
+ * the top left corner is (0, 0) and bottom right corner is (window.innerWidth, window.innerHeight).
+ */
+export declare const getClientCoordinates: (magicCoords: MagicCoords, ctx: CanvasRenderingContext2D) => WithZoom<ClientCoords>;
+export declare const useMagicCoordinates: (canvas: Ref<HTMLCanvasElement | undefined>) => {
+    coordinates: Ref<{
+        x: number;
+        y: number;
+    }, Coordinate | {
+        x: number;
+        y: number;
+    }>;
+    cleanup: (ref: HTMLCanvasElement) => void;
+};

package/dist/coordinates/index.js

@@ -0,0 +1,58 @@
+import { getDevicePixelRatio } from "../camera/utils";
+import { onMounted, ref } from "vue";
+import { getCtx } from "magic-utils-yonava";
+export const getCanvasTransform = (ctx) => {
+    const { a, e, f } = ctx.getTransform();
+    // TODO investigate why dpr isn't already factored into ctx. Camera should add it with the PZ transform!
+    const dpr = getDevicePixelRatio();
+    const zoom = a / dpr;
+    const panX = e / dpr;
+    const panY = f / dpr;
+    return { panX, panY, zoom };
+};
+/**
+ * magic coordinates are coordinates transformed by the pan and zoom of the camera.
+ *
+ * if the user has panned their camera 10px to the left, running this function with
+ * `clientCoords` set to (0, 0) will return (-10, 0, 1)
+ */
+export const getMagicCoordinates = (clientCoords, ctx) => {
+    const rect = ctx.canvas.getBoundingClientRect();
+    const localX = clientCoords.clientX - rect.left;
+    const localY = clientCoords.clientY - rect.top;
+    const { panX, panY, zoom } = getCanvasTransform(ctx);
+    const x = (localX - panX) / zoom;
+    const y = (localY - panY) / zoom;
+    return { x, y, zoom };
+};
+/**
+ * client coordinates are the raw coordinates corresponding to the clients physical screen.
+ *
+ * the top left corner is (0, 0) and bottom right corner is (window.innerWidth, window.innerHeight).
+ */
+export const getClientCoordinates = (magicCoords, ctx) => {
+    const { panX, panY, zoom } = getCanvasTransform(ctx);
+    const { x, y } = magicCoords;
+    return {
+        clientX: x * zoom + panX,
+        clientY: y * zoom + panY,
+        zoom,
+    };
+};
+export const useMagicCoordinates = (canvas) => {
+    const coordinates = ref({ x: 0, y: 0 });
+    const captureCoords = (ev) => (coordinates.value = getMagicCoordinates(ev, getCtx(canvas)));
+    onMounted(() => {
+        if (!canvas.value)
+            throw new Error("Canvas not found in DOM. Check ref link.");
+        canvas.value.addEventListener("mousemove", captureCoords);
+        canvas.value.addEventListener("wheel", captureCoords);
+    });
+    return {
+        coordinates,
+        cleanup: (ref) => {
+            ref.removeEventListener("mousemove", captureCoords);
+            ref.removeEventListener("wheel", captureCoords);
+        },
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./useMagicCanvas";
+export * from "./MagicCanvas.vue";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./useMagicCanvas";
+export * from "./MagicCanvas.vue";

package/dist/localStorage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * a registry for all localStorage keys this application uses
+ */
+export declare const localKeys: {
+    /** camera `panX` state in magic canvas - {@link Camera.state} */
+    readonly cameraPanX: (key: string) => `camera-pan-x-${string}`;
+    /** camera `panY` state in magic canvas - {@link Camera.state} */
+    readonly cameraPanY: (key: string) => `camera-pan-y-${string}`;
+    /** camera `zoom` state in magic canvas - {@link Camera.state} */
+    readonly cameraZoom: (key: string) => `camera-zoom-${string}`;
+};
+/**
+ * all return values of localStorage are, by default, string.
+ * this type allows string to be narrowed to types such as 'true' | 'false'
+ */
+type TypeOverride = {};
+type LocalObj = typeof localKeys;
+/**
+ * @example
+ * type T = TypeOrReturnType<number> // number
+ * type TFunc = TypeOrReturnType<() => number> // number
+ */
+type TypeOrReturnType<T> = T extends (...args: any[]) => infer U ? U : T;
+type LocalKeys = TypeOrReturnType<LocalObj[keyof LocalObj]>;
+type LocalType<T extends LocalKeys> = T extends keyof TypeOverride ? TypeOverride[T] : string;
+/**
+ * perform **type safe** localStorage actions
+ */
+export declare const local: {
+    get: <T extends LocalKeys>(key: T) => string | null;
+    set: <T extends LocalKeys, K extends LocalType<T>>(key: T, value: K) => void;
+    remove: <T extends LocalKeys>(key: T) => void;
+    clear: () => void;
+};
+export {};

package/dist/localStorage.js

@@ -0,0 +1,20 @@
+/**
+ * a registry for all localStorage keys this application uses
+ */
+export const localKeys = {
+    /** camera `panX` state in magic canvas - {@link Camera.state} */
+    cameraPanX: (key) => `camera-pan-x-${key}`,
+    /** camera `panY` state in magic canvas - {@link Camera.state} */
+    cameraPanY: (key) => `camera-pan-y-${key}`,
+    /** camera `zoom` state in magic canvas - {@link Camera.state} */
+    cameraZoom: (key) => `camera-zoom-${key}`,
+};
+/**
+ * perform **type safe** localStorage actions
+ */
+export const local = {
+    get: (key) => localStorage.getItem(key),
+    set: (key, value) => localStorage.setItem(key, value),
+    remove: (key) => localStorage.removeItem(key),
+    clear: localStorage.clear,
+};

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+import type { Ref } from 'vue';
+import type { DrawPattern } from './backgroundPattern';
+import type { Camera } from './camera';
+export type Coordinate = {
+    x: number;
+    y: number;
+};
+export type DrawContent = (ctx: CanvasRenderingContext2D) => void;
+export type DrawFns = {
+    content: Ref<DrawContent>;
+    backgroundPattern: Ref<DrawPattern>;
+};
+export type MagicCanvasProps = {
+    canvas: Ref<HTMLCanvasElement | undefined>;
+    camera: Omit<Camera, 'cleanup'>;
+    cursorCoordinates: Ref<Coordinate>;
+    ref: {
+        canvasRef: (canvas: HTMLCanvasElement) => void;
+        cleanup: (canvas: HTMLCanvasElement) => void;
+    };
+    draw: DrawFns;
+};
+export type MagicCanvasOptions = {
+    /**
+     * a key that is used to track the camera state in localStorage
+     */
+    storageKey?: string;
+};
+export type UseMagicCanvas = (options?: MagicCanvasOptions) => MagicCanvasProps;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/useMagicCanvas.d.ts

@@ -0,0 +1,2 @@
+import type { UseMagicCanvas } from "./types";
+export declare const useMagicCanvas: UseMagicCanvas;

package/dist/useMagicCanvas.js

@@ -0,0 +1,54 @@
+import { useElementSize } from "@vueuse/core";
+import { onMounted, ref, watch } from "vue";
+import { useBackgroundPattern } from "./backgroundPattern";
+import { useCamera } from "./camera";
+import { getDevicePixelRatio } from "./camera/utils";
+import { useMagicCoordinates } from "./coordinates";
+import { getCtx } from "magic-utils-yonava";
+const REPAINT_FPS = 60;
+const initCanvasWidthHeight = (canvas) => {
+    if (!canvas)
+        throw new Error("Canvas not found in DOM. Check ref link.");
+    const dpr = getDevicePixelRatio();
+    const rect = canvas.getBoundingClientRect();
+    canvas.width = rect.width * dpr;
+    canvas.height = rect.height * dpr;
+};
+export const useMagicCanvas = (options = {}) => {
+    const canvas = ref();
+    const canvasBoxSize = useElementSize(canvas);
+    const drawContent = ref(() => { });
+    const drawBackgroundPattern = ref(() => { });
+    let repaintInterval;
+    onMounted(() => {
+        initCanvasWidthHeight(canvas.value);
+        repaintInterval = setInterval(repaintCanvas, 1000 / REPAINT_FPS);
+    });
+    watch([canvasBoxSize.width, canvasBoxSize.height], () => initCanvasWidthHeight(canvas.value));
+    const { cleanup: cleanupCamera, ...camera } = useCamera(canvas, options?.storageKey ?? "[default-storage-key]");
+    const { coordinates: cursorCoordinates, cleanup: cleanupCoords } = useMagicCoordinates(canvas);
+    const pattern = useBackgroundPattern(camera.state, drawBackgroundPattern);
+    const repaintCanvas = () => {
+        const ctx = getCtx(canvas);
+        camera.transformAndClear(ctx);
+        pattern.draw(ctx);
+        drawContent.value(ctx);
+    };
+    return {
+        canvas,
+        camera,
+        cursorCoordinates,
+        ref: {
+            canvasRef: (ref) => (canvas.value = ref),
+            cleanup: (ref) => {
+                cleanupCoords(ref);
+                cleanupCamera(ref);
+                clearInterval(repaintInterval);
+            },
+        },
+        draw: {
+            content: drawContent,
+            backgroundPattern: drawBackgroundPattern,
+        },
+    };
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "magic-canvas-yonava",
+  "version": "1.0.0",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.cjs.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build:types": "vue-tsc -b ."
+  },
+  "peerDependencies": {
+    "vue": "^3.5.18"
+  },
+  "dependencies": {
+    "@vueuse/core": "^13.6.0",
+    "magic-utils-yonava": "^1.0.7",
+    "tailwind-merge": "^3.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.8.1",
+    "vue-tsc": "^3.1.1"
+  }
+}

package/src/MagicCanvas.vue

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+  import { type ClassNameValue, twMerge } from "tailwind-merge";
+
+  import { onBeforeUnmount, onMounted, ref } from "vue";
+
+  import type { MagicCanvasProps } from "./types";
+
+  const props = defineProps<MagicCanvasProps["ref"]>();
+
+  const canvas = ref<HTMLCanvasElement>();
+
+  onMounted(() => {
+    if (!canvas.value)
+      throw new Error("Canvas not found in DOM. Check ref link.");
+    props.canvasRef(canvas.value);
+  });
+
+  onBeforeUnmount(() => {
+    if (!canvas.value)
+      throw new Error("Canvas not found in DOM. Check ref link.");
+    props.cleanup(canvas.value);
+  });
+</script>
+
+<template>
+  <canvas
+    v-bind="{
+      ...$attrs,
+      class: twMerge($attrs.class as ClassNameValue, ['w-full', 'h-full']),
+    }"
+    ref="canvas"
+  >
+    Sorry, your browser does not support canvas.
+  </canvas>
+</template>

package/src/backgroundPattern.ts

@@ -0,0 +1,68 @@
+import { getMagicCoordinates } from './coordinates';
+
+import type { Camera } from './camera';
+import type { Coordinate, DrawFns } from './types';
+
+const STAGGER = 100;
+
+const START_PATTERN_FADE_OUT = 0.6;
+const PATTERN_FULLY_FADED_OUT = 0.25;
+
+const computeAlpha = (z: number) => {
+  if (z <= PATTERN_FULLY_FADED_OUT) return '00';
+  if (z >= START_PATTERN_FADE_OUT) return '';
+  const strPercent = String(
+    Math.floor(
+      ((z - PATTERN_FULLY_FADED_OUT) /
+        (START_PATTERN_FADE_OUT - PATTERN_FULLY_FADED_OUT)) *
+      100,
+    ),
+  );
+  return strPercent.length === 1 ? `0${strPercent}` : strPercent;
+};
+
+export type DrawPattern = (
+  ctx: CanvasRenderingContext2D,
+  at: Coordinate,
+  alpha: string,
+) => void;
+
+export const useBackgroundPattern = (
+  { panX, panY, zoom }: Camera['state'],
+  drawPattern: DrawFns['backgroundPattern'],
+) => {
+  const draw = (ctx: CanvasRenderingContext2D) => {
+    if (zoom.value <= PATTERN_FULLY_FADED_OUT) return;
+
+    const startingCoords = getMagicCoordinates(
+      {
+        clientX: 0,
+        clientY: 0,
+      },
+      ctx,
+    );
+
+    const endingCoords = getMagicCoordinates(
+      {
+        clientX: window.innerWidth + STAGGER,
+        clientY: window.innerHeight + STAGGER,
+      },
+      ctx,
+    );
+
+    const offsetX = (panX.value / zoom.value) % STAGGER;
+    const offsetY = (panY.value / zoom.value) % STAGGER;
+
+    for (let x = startingCoords.x + offsetX; x < endingCoords.x; x += STAGGER) {
+      for (
+        let y = startingCoords.y + offsetY;
+        y < endingCoords.y;
+        y += STAGGER
+      ) {
+        drawPattern.value(ctx, { x, y }, computeAlpha(zoom.value));
+      }
+    }
+  };
+
+  return { draw };
+};

package/src/camera/index.ts

@@ -0,0 +1,36 @@
+import type { Ref } from 'vue';
+
+import { usePanAndZoom } from './panZoom';
+import {
+  type TransformOptions,
+  addTransform,
+  getDevicePixelRatio,
+} from './utils';
+
+export const useCamera = (
+  canvas: Ref<HTMLCanvasElement | undefined>,
+  storageKey: string,
+) => {
+  const { getTransform: getPZTransform, ...rest } = usePanAndZoom(
+    canvas,
+    storageKey,
+  );
+  const dpr = getDevicePixelRatio();
+
+  const dprTransform: TransformOptions = {
+    scaleX: dpr,
+    scaleY: dpr,
+  };
+
+  return {
+    ...rest,
+    transformAndClear: (ctx: CanvasRenderingContext2D) => {
+      ctx.resetTransform();
+      ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
+      const transforms = [dprTransform, getPZTransform()];
+      for (const t of transforms) addTransform(ctx, t);
+    },
+  };
+};
+
+export type Camera = ReturnType<typeof useCamera>;

package/src/camera/panZoom.ts

@@ -0,0 +1,125 @@
+import { useLocalStorage } from "@vueuse/core";
+import { localKeys } from "../localStorage";
+
+import { type Ref, onMounted } from "vue";
+import { MOUSE_BUTTONS } from "magic-utils-yonava";
+
+export const MIN_ZOOM = 0.2;
+export const MAX_ZOOM = 10;
+
+export const ZOOM_SENSITIVITY = 0.02;
+export const PAN_SENSITIVITY = 1;
+
+export const usePanAndZoom = (
+  canvas: Ref<HTMLCanvasElement | undefined>,
+  storageKey: string
+) => {
+  const panX = useLocalStorage(localKeys.cameraPanX(storageKey), 0);
+  const panY = useLocalStorage(localKeys.cameraPanY(storageKey), 0);
+  const zoom = useLocalStorage(localKeys.cameraZoom(storageKey), 1);
+
+  const setZoom = (ev: Pick<WheelEvent, "clientX" | "clientY" | "deltaY">) => {
+    const rect = canvas.value!.getBoundingClientRect();
+    const cx = ev.clientX - rect.left;
+    const cy = ev.clientY - rect.top;
+
+    // clamp deltaY to a max range to prevent mice with large deltaY notches from feeling too sensitive
+    const normalizedDelta = Math.max(-100, Math.min(100, ev.deltaY));
+    const zoomFactor = Math.exp(-normalizedDelta * ZOOM_SENSITIVITY);
+    const clampedZoom = Math.min(
+      MAX_ZOOM,
+      Math.max(MIN_ZOOM, zoom.value * zoomFactor)
+    );
+
+    const scale = clampedZoom / zoom.value;
+
+    panX.value = cx - (cx - panX.value) * scale;
+    panY.value = cy - (cy - panY.value) * scale;
+    zoom.value = clampedZoom;
+  };
+
+  const setPan = (ev: Pick<WheelEvent, "deltaX" | "deltaY">) => {
+    panX.value -= ev.deltaX * PAN_SENSITIVITY;
+    panY.value -= ev.deltaY * PAN_SENSITIVITY;
+  };
+
+  const onWheel = (ev: WheelEvent) => {
+    ev.preventDefault();
+
+    const isPanning = !ev.ctrlKey;
+    const maneuverCamera = isPanning ? setPan : setZoom;
+    maneuverCamera(ev);
+  };
+
+  let lastX = 0;
+  let lastY = 0;
+  let middleMouseDown = false;
+
+  const onMousedown = (ev: MouseEvent) => {
+    middleMouseDown = ev.button === MOUSE_BUTTONS.middle;
+    if (!middleMouseDown) return;
+
+    lastX = ev.clientX;
+    lastY = ev.clientY;
+  };
+
+  const onMousemove = (ev: MouseEvent) => {
+    if (!middleMouseDown) return;
+
+    setPan({
+      deltaX: lastX - ev.clientX,
+      deltaY: lastY - ev.clientY,
+    });
+
+    lastX = ev.clientX;
+    lastY = ev.clientY;
+  };
+
+  const onMouseup = () => {
+    lastX = 0;
+    lastY = 0;
+    middleMouseDown = false;
+  };
+
+  onMounted(() => {
+    if (!canvas.value) throw new Error("canvas not found in DOM");
+    canvas.value.addEventListener("wheel", onWheel, { passive: false });
+    canvas.value.addEventListener("mousedown", onMousedown);
+    canvas.value.addEventListener("mousemove", onMousemove);
+    document.addEventListener("mouseup", onMouseup);
+  });
+
+  return {
+    actions: {
+      zoomIn: (increment = 12.5) =>
+        setZoom({
+          deltaY: -increment,
+          clientX: window.innerWidth / 2,
+          clientY: window.innerHeight / 2,
+        }),
+      zoomOut: (decrement = 12.5) =>
+        setZoom({
+          deltaY: decrement,
+          clientX: window.innerWidth / 2,
+          clientY: window.innerHeight / 2,
+        }),
+    },
+    state: {
+      panX,
+      panY,
+      zoom,
+    },
+    getTransform: () => ({
+      scaleX: zoom.value,
+      scaleY: zoom.value,
+      translateX: panX.value,
+      translateY: panY.value,
+    }),
+    cleanup: (ref: HTMLCanvasElement) => {
+      ref.removeEventListener("wheel", onWheel);
+      ref.removeEventListener("mousedown", onMousedown);
+      ref.removeEventListener("mousemove", onMousemove);
+      document.removeEventListener("mouseup", onMouseup);
+    },
+  };
+};

package/src/camera/utils.ts

@@ -0,0 +1,41 @@
+export type TransformProps = {
+  /** corresponds to `a` in {@link CanvasRenderingContext2D.setTransform} */
+  scaleX: number;
+  /** corresponds to `b` in {@link CanvasRenderingContext2D.setTransform} */
+  skewY: number;
+  /** corresponds to `c` in {@link CanvasRenderingContext2D.setTransform} */
+  skewX: number;
+  /** corresponds to `d` in {@link CanvasRenderingContext2D.setTransform} */
+  scaleY: number;
+  /** corresponds to `e` in {@link CanvasRenderingContext2D.setTransform} */
+  translateX: number;
+  /** corresponds to `f` in {@link CanvasRenderingContext2D.setTransform} */
+  translateY: number;
+};
+
+export type TransformOptions = Partial<TransformProps>;
+
+export const getDevicePixelRatio = () => window.devicePixelRatio ?? 1;
+
+export const addTransform = (
+  ctx: CanvasRenderingContext2D,
+  t: TransformOptions,
+) => {
+  const translateX = t.translateX ?? 0;
+  const translateY = t.translateY ?? 0;
+  if (translateX !== 0 || translateY !== 0) {
+    ctx.translate(translateX, translateY);
+  }
+
+  const scaleX = t.scaleX ?? 1;
+  const scaleY = t.scaleY ?? 1;
+  if (scaleX !== 1 || scaleY !== 1) {
+    ctx.scale(scaleX, scaleY);
+  }
+
+  const skewX = t.skewX ?? 0;
+  const skewY = t.skewY ?? 0;
+  if (skewX !== 0 || skewY !== 0) {
+    ctx.transform(1, skewY, skewX, 1, 0, 0);
+  }
+};

package/src/coordinates/index.ts

@@ -0,0 +1,96 @@
+import { getDevicePixelRatio } from "../camera/utils";
+
+import { type Ref, onMounted, ref } from "vue";
+import { Coordinate } from "../types";
+import { getCtx } from "magic-utils-yonava";
+
+export const getCanvasTransform = (ctx: CanvasRenderingContext2D) => {
+  const { a, e, f } = ctx.getTransform();
+  // TODO investigate why dpr isn't already factored into ctx. Camera should add it with the PZ transform!
+  const dpr = getDevicePixelRatio();
+  const zoom = a / dpr;
+  const panX = e / dpr;
+  const panY = f / dpr;
+  return { panX, panY, zoom };
+};
+
+/**
+ * the coordinates in the real world. aka the browser
+ */
+export type ClientCoords = Pick<MouseEvent, "clientX" | "clientY">;
+
+/**
+ * the coordinates in the magic canvas world
+ */
+export type MagicCoords = Coordinate;
+
+export type WithZoom<T> = T & {
+  /**
+   * the scale factor of the canvas
+   */
+  zoom: number;
+};
+
+/**
+ * magic coordinates are coordinates transformed by the pan and zoom of the camera.
+ *
+ * if the user has panned their camera 10px to the left, running this function with
+ * `clientCoords` set to (0, 0) will return (-10, 0, 1)
+ */
+export const getMagicCoordinates = (
+  clientCoords: ClientCoords,
+  ctx: CanvasRenderingContext2D
+): WithZoom<MagicCoords> => {
+  const rect = ctx.canvas.getBoundingClientRect();
+  const localX = clientCoords.clientX - rect.left;
+  const localY = clientCoords.clientY - rect.top;
+
+  const { panX, panY, zoom } = getCanvasTransform(ctx);
+
+  const x = (localX - panX) / zoom;
+  const y = (localY - panY) / zoom;
+
+  return { x, y, zoom };
+};
+
+/**
+ * client coordinates are the raw coordinates corresponding to the clients physical screen.
+ *
+ * the top left corner is (0, 0) and bottom right corner is (window.innerWidth, window.innerHeight).
+ */
+export const getClientCoordinates = (
+  magicCoords: MagicCoords,
+  ctx: CanvasRenderingContext2D
+): WithZoom<ClientCoords> => {
+  const { panX, panY, zoom } = getCanvasTransform(ctx);
+  const { x, y } = magicCoords;
+
+  return {
+    clientX: x * zoom + panX,
+    clientY: y * zoom + panY,
+    zoom,
+  };
+};
+
+export const useMagicCoordinates = (
+  canvas: Ref<HTMLCanvasElement | undefined>
+) => {
+  const coordinates = ref<MagicCoords>({ x: 0, y: 0 });
+  const captureCoords = (ev: MouseEvent) =>
+    (coordinates.value = getMagicCoordinates(ev, getCtx(canvas)));
+
+  onMounted(() => {
+    if (!canvas.value)
+      throw new Error("Canvas not found in DOM. Check ref link.");
+    canvas.value.addEventListener("mousemove", captureCoords);
+    canvas.value.addEventListener("wheel", captureCoords);
+  });
+
+  return {
+    coordinates,
+    cleanup: (ref: HTMLCanvasElement) => {
+      ref.removeEventListener("mousemove", captureCoords);
+      ref.removeEventListener("wheel", captureCoords);
+    },
+  };
+};

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./useMagicCanvas";
+export * from "./MagicCanvas.vue";

package/src/localStorage.ts

@@ -0,0 +1,52 @@
+import type { MagicCanvasOptions } from './types';
+
+/* eslint-enable */
+
+type LocalStorageGetter = (...args: any[]) => string;
+type LocalStorageRecord = Record<string, string | LocalStorageGetter>;
+
+/**
+ * a registry for all localStorage keys this application uses
+ */
+export const localKeys = {
+  /** camera `panX` state in magic canvas - {@link Camera.state} */
+  cameraPanX: (key: string) =>
+    `camera-pan-x-${key}` as const,
+  /** camera `panY` state in magic canvas - {@link Camera.state} */
+  cameraPanY: (key: string) =>
+    `camera-pan-y-${key}` as const,
+  /** camera `zoom` state in magic canvas - {@link Camera.state} */
+  cameraZoom: (key: string) =>
+    `camera-zoom-${key}` as const,
+} as const satisfies LocalStorageRecord;
+
+/**
+ * all return values of localStorage are, by default, string.
+ * this type allows string to be narrowed to types such as 'true' | 'false'
+ */
+type TypeOverride = {};
+
+type LocalObj = typeof localKeys;
+
+/**
+ * @example
+ * type T = TypeOrReturnType<number> // number
+ * type TFunc = TypeOrReturnType<() => number> // number
+ */
+type TypeOrReturnType<T> = T extends (...args: any[]) => infer U ? U : T;
+
+type LocalKeys = TypeOrReturnType<LocalObj[keyof LocalObj]>;
+type LocalType<T extends LocalKeys> = T extends keyof TypeOverride
+  ? TypeOverride[T]
+  : string;
+
+/**
+ * perform **type safe** localStorage actions
+ */
+export const local = {
+  get: <T extends LocalKeys>(key: T) => localStorage.getItem(key),
+  set: <T extends LocalKeys, K extends LocalType<T>>(key: T, value: K) =>
+    localStorage.setItem(key, value),
+  remove: <T extends LocalKeys>(key: T) => localStorage.removeItem(key),
+  clear: localStorage.clear,
+};

package/src/types.ts

@@ -0,0 +1,37 @@
+
+import type { Ref } from 'vue';
+
+import type { DrawPattern } from './backgroundPattern';
+import type { Camera } from './camera';
+
+export type Coordinate = {
+  x: number,
+  y: number,
+}
+
+export type DrawContent = (ctx: CanvasRenderingContext2D) => void;
+
+export type DrawFns = {
+  content: Ref<DrawContent>;
+  backgroundPattern: Ref<DrawPattern>;
+};
+
+export type MagicCanvasProps = {
+  canvas: Ref<HTMLCanvasElement | undefined>;
+  camera: Omit<Camera, 'cleanup'>;
+  cursorCoordinates: Ref<Coordinate>;
+  ref: {
+    canvasRef: (canvas: HTMLCanvasElement) => void;
+    cleanup: (canvas: HTMLCanvasElement) => void;
+  };
+  draw: DrawFns;
+};
+
+export type MagicCanvasOptions = {
+  /**
+   * a key that is used to track the camera state in localStorage
+   */
+  storageKey?: string;
+};
+
+export type UseMagicCanvas = (options?: MagicCanvasOptions) => MagicCanvasProps;

package/src/useMagicCanvas.ts

@@ -0,0 +1,74 @@
+import { useElementSize } from "@vueuse/core";
+
+import { onMounted, ref, watch } from "vue";
+
+import { type DrawPattern, useBackgroundPattern } from "./backgroundPattern";
+import { useCamera } from "./camera";
+import { getDevicePixelRatio } from "./camera/utils";
+import { useMagicCoordinates } from "./coordinates";
+import type { DrawContent, UseMagicCanvas } from "./types";
+import { getCtx } from "magic-utils-yonava";
+
+const REPAINT_FPS = 60;
+
+const initCanvasWidthHeight = (canvas: HTMLCanvasElement | undefined) => {
+  if (!canvas) throw new Error("Canvas not found in DOM. Check ref link.");
+
+  const dpr = getDevicePixelRatio();
+  const rect = canvas.getBoundingClientRect();
+  canvas.width = rect.width * dpr;
+  canvas.height = rect.height * dpr;
+};
+
+export const useMagicCanvas: UseMagicCanvas = (options = {}) => {
+  const canvas = ref<HTMLCanvasElement>();
+  const canvasBoxSize = useElementSize(canvas);
+
+  const drawContent = ref<DrawContent>(() => {});
+  const drawBackgroundPattern = ref<DrawPattern>(() => {});
+
+  let repaintInterval: NodeJS.Timeout;
+
+  onMounted(() => {
+    initCanvasWidthHeight(canvas.value);
+    repaintInterval = setInterval(repaintCanvas, 1000 / REPAINT_FPS);
+  });
+
+  watch([canvasBoxSize.width, canvasBoxSize.height], () =>
+    initCanvasWidthHeight(canvas.value)
+  );
+
+  const { cleanup: cleanupCamera, ...camera } = useCamera(
+    canvas,
+    options?.storageKey ?? "[default-storage-key]"
+  );
+  const { coordinates: cursorCoordinates, cleanup: cleanupCoords } =
+    useMagicCoordinates(canvas);
+
+  const pattern = useBackgroundPattern(camera.state, drawBackgroundPattern);
+
+  const repaintCanvas = () => {
+    const ctx = getCtx(canvas);
+    camera.transformAndClear(ctx);
+    pattern.draw(ctx);
+    drawContent.value(ctx);
+  };
+
+  return {
+    canvas,
+    camera,
+    cursorCoordinates,
+    ref: {
+      canvasRef: (ref) => (canvas.value = ref),
+      cleanup: (ref) => {
+        cleanupCoords(ref);
+        cleanupCamera(ref);
+        clearInterval(repaintInterval);
+      },
+    },
+    draw: {
+      content: drawContent,
+      backgroundPattern: drawBackgroundPattern,
+    },
+  };
+};

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+
+    "target": "ES2022",
+    "module": "ESNext",
+    "lib": ["ES2023", "DOM"],
+    "types": ["node"],
+    "moduleResolution": "node",
+    "allowJs": false,
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "declaration": true,
+  },
+  "include": ["src/**/*"],
+}