From 18d5fe6b31a2ebb9fc6245f533f624f5fb3cc3bd Mon Sep 17 00:00:00 2001
From: yonava <yonavossandreae@gmail.com>
Date: Sat, 9 Aug 2025 19:50:16 -0400
Subject: [PATCH 1/6] consolidated stroke application

---
 .../src/playground/shape/ShapePlayground.vue  | 70 ++++++-------------
 .../src/shapes/animation/timeline/compile.ts  |  8 +--
 client/src/shapes/helpers.ts                  | 12 ++++
 client/src/shapes/shapes/ellipse/draw.ts      | 12 +---
 client/src/shapes/shapes/rect/draw.ts         | 13 +---
 client/src/shapes/shapes/triangle/draw.ts     | 12 +---
 6 files changed, 43 insertions(+), 84 deletions(-)

diff --git a/client/src/playground/shape/ShapePlayground.vue b/client/src/playground/shape/ShapePlayground.vue
index 947ce2cd..acc64cb6 100644
--- a/client/src/playground/shape/ShapePlayground.vue
+++ b/client/src/playground/shape/ShapePlayground.vue
@@ -3,67 +3,41 @@
   import { useMagicCanvas } from '@canvas/index';
   import colors from '@colors';
   import { useAnimatedShapes } from '@shape/animation';
-  import type { Shape } from '@shape/types';
   import { cross } from '@shapes/cross';
   import Button from '@ui/core/button/Button.vue';
 
-  import { ref } from 'vue';
-
   const { defineTimeline, shapes } = useAnimatedShapes();
 
   const { play, stop, pause, resume } = defineTimeline({
-    forShapes: ['line'],
-    durationMs: 4000,
+    forShapes: ['circle'],
+    durationMs: 3000,
     customInterpolations: {
-      fillGradient: {
-        value: (p) => [
-          {
-            color: 'red',
-            offset: 0,
-          },
-          {
-            color: 'red',
-            offset: p < 0.5 ? p * 2 : 2 - p * 2,
-          },
-          {
-            color: 'black',
-            offset: p < 0.5 ? p * 2 : 2 - p * 2,
-          },
-        ],
+      stroke: {
+        value: (p) => ({
+          lineWidth: 10 + (p < 0.5 ? p * 10 : 10 - p * 10),
+          color: 'red',
+          dash: [10, 10 + (p < 0.5 ? p * 10 : 10 - p * 10)],
+        }),
       },
     },
-    keyframes: [
-      {
-        progress: 0.5,
-        properties: {
-          end: { x: 50, y: 300 },
-          start: { x: 250, y: 0 },
-          lineWidth: 50,
-          textArea: (ta) => ({
-            textBlock: {
-              fontSize: ta.textBlock.fontSize + 12,
-            },
-          }),
-        },
-      },
-    ],
+    keyframes: [],
   });
 
-  const paintedShapes = ref<Shape[]>([]);
-
-  paintedShapes.value.push(
-    shapes.line({
-      id: 'test',
-      start: { x: 0, y: 0 },
-      end: { x: 200, y: 200 },
-      textArea: { textBlock: { content: 'real' } },
-      fillColor: 'purple',
-    }),
-  );
+  const cir = shapes.circle({
+    id: 'test',
+    at: { x: 0, y: 0 },
+    radius: 50,
+    stroke: {
+      color: 'red',
+      lineWidth: 10,
+    },
+    textArea: { textBlock: { content: 'real' } },
+  });
 
   const magic = useMagicCanvas();
-  magic.draw.content.value = (ctx) =>
-    paintedShapes.value.forEach((i) => i.draw(ctx));
+  magic.draw.content.value = (ctx) => {
+    cir.draw(ctx);
+  };
 
   magic.draw.backgroundPattern.value = (ctx, at) => {
     cross({
diff --git a/client/src/shapes/animation/timeline/compile.ts b/client/src/shapes/animation/timeline/compile.ts
index 9f51c2d0..98014b55 100644
--- a/client/src/shapes/animation/timeline/compile.ts
+++ b/client/src/shapes/animation/timeline/compile.ts
@@ -200,10 +200,10 @@ export const compileTimeline = (timeline: Timeline<any>): CompiledTimeline => {
         };
       });
 
-      // @ts-expect-error could make TS happy, but would make this verbose unfortunately
       return interpolation.fn(
         keyframes,
         getDefaultEasing(propName),
+        // @ts-expect-error could make TS happy, but would make this verbose unfortunately
         rawPropVal,
       )(progress);
     };
@@ -216,12 +216,10 @@ export const compileTimeline = (timeline: Timeline<any>): CompiledTimeline => {
       ImperativeTrack<unknown>,
     ][];
     for (const [propName, interpolationOptions] of allCustomInterpolations) {
-      if (!interpolationOptions)
-        throw 'custom path received with no options. this should never happen!';
       const { easing: easingRaw, value } = interpolationOptions;
       const easing = easingRaw ?? getDefaultEasing(propName);
-      tl.properties[propName] = (_, progress) =>
-        value(easingOptionToFunction(easing)(progress));
+      const easingFn = easingOptionToFunction(easing);
+      tl.properties[propName] = (_, progress) => value(easingFn(progress));
     }
   }
 
diff --git a/client/src/shapes/helpers.ts b/client/src/shapes/helpers.ts
index 2dd798c7..500f7aee 100644
--- a/client/src/shapes/helpers.ts
+++ b/client/src/shapes/helpers.ts
@@ -7,6 +7,7 @@ import type {
   BoundingBox,
   Coordinate,
   GradientStop,
+  Stroke,
 } from './types/utility';
 
 /**
@@ -355,3 +356,14 @@ export const toBorderRadiusArray = (
     ? [borderRadius, borderRadius, borderRadius, borderRadius]
     : borderRadius;
 };
+
+export const drawStrokeOntoShape = (ctx: CanvasRenderingContext2D, stroke: Stroke) => {
+  const { color, lineWidth: width, dash = [] } = stroke;
+  ctx.strokeStyle = color;
+  ctx.lineWidth = width;
+  // setLineDash does not support passing readonly arrays in ts!
+  // safe assertion since setLineDash does not perform mutations
+  ctx.setLineDash(dash as number[]);
+  ctx.stroke();
+  ctx.setLineDash([]);
+}
\ No newline at end of file
diff --git a/client/src/shapes/shapes/ellipse/draw.ts b/client/src/shapes/shapes/ellipse/draw.ts
index a3651ef1..f91f44a1 100644
--- a/client/src/shapes/shapes/ellipse/draw.ts
+++ b/client/src/shapes/shapes/ellipse/draw.ts
@@ -1,3 +1,4 @@
+import { drawStrokeOntoShape } from '@shape/helpers';
 import type { EllipseSchemaWithDefaults } from './defaults';
 
 export const drawEllipseWithCtx =
@@ -9,16 +10,7 @@ export const drawEllipseWithCtx =
     ctx.fillStyle = color;
     ctx.fill();
 
-    if (stroke) {
-      const { color, lineWidth: width, dash = [] } = stroke;
-      ctx.strokeStyle = color;
-      ctx.lineWidth = width;
-      // setLineDash does not support passing readonly arrays in ts!
-      // safe assertion since setLineDash does not perform mutations
-      ctx.setLineDash(dash as number[]);
-      ctx.stroke();
-      ctx.setLineDash([]);
-    }
+    if (stroke) drawStrokeOntoShape(ctx, stroke)
 
     ctx.closePath();
   };
diff --git a/client/src/shapes/shapes/rect/draw.ts b/client/src/shapes/shapes/rect/draw.ts
index b06015ff..7dbb9e15 100644
--- a/client/src/shapes/shapes/rect/draw.ts
+++ b/client/src/shapes/shapes/rect/draw.ts
@@ -1,4 +1,4 @@
-import { normalizeBoundingBox, toBorderRadiusArray } from '@shape/helpers';
+import { drawStrokeOntoShape, normalizeBoundingBox, toBorderRadiusArray } from '@shape/helpers';
 
 import type { RectSchemaWithDefaults } from './defaults';
 
@@ -113,16 +113,7 @@ export const drawRectWithCtx =
       ctx.fill();
     }
 
-    if (stroke) {
-      const { color, lineWidth, dash = [] } = stroke;
-      ctx.strokeStyle = color;
-      ctx.lineWidth = lineWidth;
-      // setLineDash does not support passing readonly arrays in ts!
-      // safe assertion since setLineDash does not perform mutations
-      ctx.setLineDash(dash as number[]);
-      ctx.stroke();
-      ctx.setLineDash([]);
-    }
+    if (stroke) drawStrokeOntoShape(ctx, stroke)
 
     ctx.restore();
   };
diff --git a/client/src/shapes/shapes/triangle/draw.ts b/client/src/shapes/shapes/triangle/draw.ts
index 0bcdfc4b..1027c619 100644
--- a/client/src/shapes/shapes/triangle/draw.ts
+++ b/client/src/shapes/shapes/triangle/draw.ts
@@ -1,3 +1,4 @@
+import { drawStrokeOntoShape } from '@shape/helpers';
 import type { TriangleSchemaWithDefaults } from './defaults';
 
 export const drawTriangleWithCtx =
@@ -31,14 +32,5 @@ export const drawTriangleWithCtx =
     ctx.fill();
     ctx.closePath();
 
-    if (stroke) {
-      ctx.lineWidth = stroke.lineWidth;
-      ctx.strokeStyle = stroke.color;
-      // setLineDash does not support passing readonly arrays in ts!
-      // safe assertion since setLineDash does not perform mutations
-      ctx.setLineDash((stroke.dash ?? []) as number[]);
-      ctx.stroke();
-
-      ctx.setLineDash([]);
-    }
+    if (stroke) drawStrokeOntoShape(ctx, stroke)
   };

From 616df2a2342bf6e1f5257b1ae8900244154d56c8 Mon Sep 17 00:00:00 2001
From: yonava <yonavossandreae@gmail.com>
Date: Sat, 9 Aug 2025 21:09:27 -0400
Subject: [PATCH 2/6] much better define timeline ts

---
 .../src/playground/shape/ShapePlayground.vue  | 32 +++++++--
 client/src/shapes/animation/index.ts          | 60 ++++++++--------
 .../src/shapes/animation/timeline/compile.ts  |  4 +-
 .../src/shapes/animation/timeline/define.ts   | 69 ++++++-------------
 client/src/shapes/defaults/shapes.ts          |  8 ++-
 client/src/shapes/helpers.ts                  | 20 ++++--
 client/src/shapes/types/utility.ts            |  8 ++-
 7 files changed, 110 insertions(+), 91 deletions(-)

diff --git a/client/src/playground/shape/ShapePlayground.vue b/client/src/playground/shape/ShapePlayground.vue
index acc64cb6..5f3cd43a 100644
--- a/client/src/playground/shape/ShapePlayground.vue
+++ b/client/src/playground/shape/ShapePlayground.vue
@@ -10,17 +10,21 @@
 
   const { play, stop, pause, resume } = defineTimeline({
     forShapes: ['circle'],
-    durationMs: 3000,
+    durationMs: 6000,
     customInterpolations: {
       stroke: {
         value: (p) => ({
           lineWidth: 10 + (p < 0.5 ? p * 10 : 10 - p * 10),
           color: 'red',
-          dash: [10, 10 + (p < 0.5 ? p * 10 : 10 - p * 10)],
+          dash: {
+            pattern: [40, 22.832],
+            // circum = 2 pi r = 2 pi 50 = 100 pi
+            offset: p * (100 * Math.PI),
+          },
         }),
       },
     },
-    keyframes: [],
+    keyframes: [{ progress: 0.5, properties: { radius: 100 } }],
   });
 
   const cir = shapes.circle({
@@ -28,15 +32,35 @@
     at: { x: 0, y: 0 },
     radius: 50,
     stroke: {
+      lineWidth: 10,
       color: 'red',
+      dash: {
+        pattern: [40, 22.832],
+        offset: 0,
+      },
+    },
+    textArea: { textBlock: { content: '1' } },
+  });
+
+  const cir2 = shapes.circle({
+    id: 'test2',
+    at: { x: 200, y: 0 },
+    radius: 50,
+    stroke: {
       lineWidth: 10,
+      color: 'red',
+      dash: {
+        pattern: [40, 22.832],
+        offset: 90,
+      },
     },
-    textArea: { textBlock: { content: 'real' } },
+    textArea: { textBlock: { content: '2' } },
   });
 
   const magic = useMagicCanvas();
   magic.draw.content.value = (ctx) => {
     cir.draw(ctx);
+    cir2.draw(ctx);
   };
 
   magic.draw.backgroundPattern.value = (ctx, at) => {
diff --git a/client/src/shapes/animation/index.ts b/client/src/shapes/animation/index.ts
index 357d5dde..ed0d36c0 100644
--- a/client/src/shapes/animation/index.ts
+++ b/client/src/shapes/animation/index.ts
@@ -1,4 +1,4 @@
-import { shapeDefaults } from '@shape/defaults/shapes';
+import { getSchemaWithDefaults } from '@shape/defaults/shapes';
 import type {
   EverySchemaPropName,
   SchemaId,
@@ -127,44 +127,44 @@ export const useAnimatedShapes = () => {
       factory: ShapeFactory<T>,
       shapeName: ShapeName,
     ): ShapeFactory<WithId<T>> =>
-    (schema) =>
-      new Proxy(factory(schema), {
-        get: (target, rawProp) => {
-          const prop = rawProp as keyof Shape;
-          if (!shapeProps.has(prop)) return target[prop];
+      (schema) =>
+        new Proxy(factory(schema), {
+          get: (target, rawProp) => {
+            const prop = rawProp as keyof Shape;
+            if (!shapeProps.has(prop)) return target[prop];
 
-          const animations = activeAnimations.get(schema.id);
+            const animations = activeAnimations.get(schema.id);
 
-          const defaultResolver:
-            | ((schema: LooseSchema) => LooseSchema)
-            | undefined = (shapeDefaults as any)?.[shapeName];
-          if (!defaultResolver)
-            throw new Error(`cant find defaults for ${shapeName}`);
-          const schemaWithDefaults = defaultResolver(schema);
+            const defaultResolver:
+              | ((schema: LooseSchema) => LooseSchema)
+              | undefined = (getSchemaWithDefaults as any)?.[shapeName];
+            if (!defaultResolver)
+              throw new Error(`cant find defaults for ${shapeName}`);
+            const schemaWithDefaults = defaultResolver(schema);
 
-          autoAnimate.captureSchemaState(schemaWithDefaults, shapeName);
+            autoAnimate.captureSchemaState(schemaWithDefaults, shapeName);
 
-          const targetMapSchema = autoAnimate.snapshotMap.get(schema.id);
-          if (targetMapSchema)
-            return factory(targetMapSchema as WithId<T>)[prop];
+            const targetMapSchema = autoAnimate.snapshotMap.get(schema.id);
+            if (targetMapSchema)
+              return factory(targetMapSchema as WithId<T>)[prop];
 
-          if (!animations || animations.length === 0) return target[prop];
-          if (!animations[0]?.schema) animations[0].schema = schemaWithDefaults;
+            if (!animations || animations.length === 0) return target[prop];
+            if (!animations[0]?.schema) animations[0].schema = schemaWithDefaults;
 
-          if (prop === 'startTextAreaEdit')
-            return console.warn(
-              'shapes with active animations cannot spawn text inputs',
-            );
+            if (prop === 'startTextAreaEdit')
+              return console.warn(
+                'shapes with active animations cannot spawn text inputs',
+              );
 
-          const hasShapeName = schemaIdToShapeName.get(schema.id);
-          if (!hasShapeName) schemaIdToShapeName.set(schema.id, shapeName);
+            const hasShapeName = schemaIdToShapeName.get(schema.id);
+            if (!hasShapeName) schemaIdToShapeName.set(schema.id, shapeName);
 
-          const animatedSchema = getAnimatedSchema(schema.id);
-          if (!animatedSchema) return target[prop];
+            const animatedSchema = getAnimatedSchema(schema.id);
+            if (!animatedSchema) return target[prop];
 
-          return factory(animatedSchema as WithId<T>)[prop];
-        },
-      });
+            return factory(animatedSchema as WithId<T>)[prop];
+          },
+        });
 
   return {
     shapes: {
diff --git a/client/src/shapes/animation/timeline/compile.ts b/client/src/shapes/animation/timeline/compile.ts
index 98014b55..860d8a25 100644
--- a/client/src/shapes/animation/timeline/compile.ts
+++ b/client/src/shapes/animation/timeline/compile.ts
@@ -213,13 +213,13 @@ export const compileTimeline = (timeline: Timeline<any>): CompiledTimeline => {
   if (customInterpolations) {
     const allCustomInterpolations = Object.entries(customInterpolations) as [
       EverySchemaPropName,
-      ImperativeTrack<unknown>,
+      ImperativeTrack<any, any>,
     ][];
     for (const [propName, interpolationOptions] of allCustomInterpolations) {
       const { easing: easingRaw, value } = interpolationOptions;
       const easing = easingRaw ?? getDefaultEasing(propName);
       const easingFn = easingOptionToFunction(easing);
-      tl.properties[propName] = (_, progress) => value(easingFn(progress));
+      tl.properties[propName] = (schemaWithDefaults, progress) => value(easingFn(progress), schemaWithDefaults);
     }
   }
 
diff --git a/client/src/shapes/animation/timeline/define.ts b/client/src/shapes/animation/timeline/define.ts
index 72d18760..a2f6a3d9 100644
--- a/client/src/shapes/animation/timeline/define.ts
+++ b/client/src/shapes/animation/timeline/define.ts
@@ -1,14 +1,14 @@
-import type { TextArea } from '@shape/text/types';
 // @typescript-eslint/no-unused-vars reports unused even if referenced in jsdoc
 // eslint-disable-next-line
 import type { EverySchemaProp, ShapeNameToSchema, WithId } from '@shape/types';
 import { generateId } from '@utils/id';
-import type { DeepPartial, DeepRequired } from 'ts-essentials';
+import type { DeepRequired } from 'ts-essentials';
 
 import type { DeepReadonly } from 'vue';
 
 import type { EasingOption } from '../easing';
 import { type CompiledTimeline, compileTimeline } from './compile';
+import type { SchemaWithDefaults } from '@shape/defaults/shapes';
 
 type ShapeTarget = {
   /**
@@ -64,62 +64,37 @@ type TimelineControls = {
   dispose: () => void;
 };
 
-type SharedSchemaProps<T extends keyof ShapeNameToSchema> =
-  keyof ShapeNameToSchema[T] &
-    {
-      [K in keyof ShapeNameToSchema[T]]: T extends any
-        ? K extends keyof ShapeNameToSchema[T]
-          ? unknown
-          : never
-        : never;
-    }[keyof ShapeNameToSchema[T]];
-
-type SchemaProps<T extends keyof ShapeNameToSchema> = Pick<
-  ShapeNameToSchema[T],
-  SharedSchemaProps<T>
->;
-
-type InterceptedSchemaProps = {
-  textArea: DeepPartial<TextArea>;
-};
-
 type CustomOption<TProp, TSchema> = (
   propValue: DeepRequired<TProp>,
   schema: TSchema,
 ) => TProp;
 
-type WithCustomOption<T> = {
-  [K in keyof T]:
-    | NonNullable<T[K]>
-    | CustomOption<NonNullable<T[K]>, DeepRequired<T>>;
-};
-
-type WithObjectOption<T> = {
-  [K in keyof T]: T[K] | { value: T[K]; easing?: EasingOption };
+type WithCustomOption<TSchema> = {
+  [TProp in keyof TSchema]:
+  | TSchema[TProp]
+  | CustomOption<TSchema[TProp], TSchema>;
 };
 
-type TimelineProps<T> = {
-  [K in keyof T]: K extends keyof InterceptedSchemaProps
-    ? InterceptedSchemaProps[K]
-    : T[K];
+type WithObjectOption<TSchema> = {
+  [TProp in keyof TSchema]: TSchema[TProp] | { value: TSchema[TProp]; easing?: EasingOption };
 };
 
-type TimelinePropsWithCustomOption<T> = WithObjectOption<
-  WithCustomOption<TimelineProps<T>>
+type TimelinePropsWithCustomOption<TSchema> = WithObjectOption<
+  WithCustomOption<TSchema>
 >;
 
 /**
  * A manually-defined animation track for a single property.
  * Used as an escape hatch when the property is too complex for standard keyframe interpolation.
  */
-export type ImperativeTrack<T> = {
+export type ImperativeTrack<TSchema, TProp extends keyof TSchema> = {
   /**
    * A function that computes the property's value at a given progress point.
    *
    * @param progress A number from 0 to 1 representing animation progress.
    * @returns The computed value for the property at the given progress.
    */
-  value: (progress: number) => T;
+  value: (progress: number, schema: TSchema) => TSchema[TProp];
   /**
    * Optional easing function to apply to the progress value before passing to `value`.
    * @default 'linear'
@@ -127,17 +102,17 @@ export type ImperativeTrack<T> = {
   easing?: EasingOption;
 };
 
-type CustomInterpolation<T> = {
-  [K in keyof T]: ImperativeTrack<T[K]>;
+type CustomInterpolation<TSchema> = {
+  [TProp in keyof TSchema]: ImperativeTrack<TSchema, TProp>;
 };
 
-export type TimelineCustomInterpolations<T> = {
-  customInterpolations?: Partial<CustomInterpolation<T>>;
+export type TimelineCustomInterpolations<TSchema> = {
+  customInterpolations?: Partial<CustomInterpolation<TSchema>>;
 };
 
-type TimelineKeyframe<T extends Partial<EverySchemaProp>> = {
+type TimelineKeyframe<TSchema> = {
   progress: number;
-  properties: Partial<TimelinePropsWithCustomOption<T>>;
+  properties: Partial<TimelinePropsWithCustomOption<TSchema>>;
 };
 
 export type TimelinePlaybackDuration = {
@@ -151,11 +126,11 @@ export type TimelinePlaybackDelay = {
 export type Timeline<T extends keyof ShapeNameToSchema> = DeepReadonly<
   {
     forShapes: T[];
-    keyframes: TimelineKeyframe<SchemaProps<NoInfer<T>>>[];
-    easing?: Partial<Record<keyof SchemaProps<NoInfer<T>>, EasingOption>>;
+    keyframes: TimelineKeyframe<SchemaWithDefaults[NoInfer<T>]>[];
+    easing?: Partial<Record<keyof SchemaWithDefaults[NoInfer<T>], EasingOption>>;
   } & TimelinePlaybackDuration &
-    TimelinePlaybackDelay &
-    TimelineCustomInterpolations<SchemaProps<NoInfer<T>>>
+  TimelinePlaybackDelay &
+  TimelineCustomInterpolations<SchemaWithDefaults[NoInfer<T>]>
 >;
 
 export const useDefineTimeline = (controls: UseDefineTimelineOptions) => {
diff --git a/client/src/shapes/defaults/shapes.ts b/client/src/shapes/defaults/shapes.ts
index 9a9f7805..19da3422 100644
--- a/client/src/shapes/defaults/shapes.ts
+++ b/client/src/shapes/defaults/shapes.ts
@@ -11,7 +11,7 @@ import { resolveStarDefaults } from '@shape/shapes/star/defaults';
 import { resolveTriangleDefaults } from '@shape/shapes/triangle/defaults';
 import { resolveUTurnDefaults } from '@shape/shapes/uturn/defaults';
 
-export const shapeDefaults = {
+export const getSchemaWithDefaults = {
   arrow: resolveArrowDefaults,
   circle: resolveCircleDefaults,
   cross: resolveCrossDefaults,
@@ -26,6 +26,8 @@ export const shapeDefaults = {
   uturn: resolveUTurnDefaults,
 } as const;
 
-export type SchemaDefaults = {
-  [K in keyof typeof shapeDefaults]: ReturnType<(typeof shapeDefaults)[K]>;
+export type SchemaWithDefaults = {
+  [K in keyof typeof getSchemaWithDefaults]: ReturnType<(typeof getSchemaWithDefaults)[K]>;
 };
+
+// type t = SchemaWithDefaults['arrow']
diff --git a/client/src/shapes/helpers.ts b/client/src/shapes/helpers.ts
index 500f7aee..fe9b4a80 100644
--- a/client/src/shapes/helpers.ts
+++ b/client/src/shapes/helpers.ts
@@ -8,6 +8,7 @@ import type {
   Coordinate,
   GradientStop,
   Stroke,
+  DashPattern,
 } from './types/utility';
 
 /**
@@ -357,13 +358,24 @@ export const toBorderRadiusArray = (
     : borderRadius;
 };
 
+const isDashArray = (dash: Stroke['dash']): dash is DashPattern => Array.isArray(dash)
+
 export const drawStrokeOntoShape = (ctx: CanvasRenderingContext2D, stroke: Stroke) => {
-  const { color, lineWidth: width, dash = [] } = stroke;
+  const { color, lineWidth: width, dash } = stroke;
   ctx.strokeStyle = color;
   ctx.lineWidth = width;
-  // setLineDash does not support passing readonly arrays in ts!
-  // safe assertion since setLineDash does not perform mutations
-  ctx.setLineDash(dash as number[]);
+
+  if (dash) {
+    // setLineDash does not support passing readonly arrays in ts!
+    // safe assertion since setLineDash does not perform mutations
+    const isArr = isDashArray(dash)
+    ctx.setLineDash((isArr ? dash : dash.pattern) as unknown as number[]);
+    ctx.lineDashOffset = isArr ? 0 : (dash.offset ?? 0)
+  }
+
   ctx.stroke();
+
+  // reset to defaults
   ctx.setLineDash([]);
+  ctx.lineDashOffset = 0;
 }
\ No newline at end of file
diff --git a/client/src/shapes/types/utility.ts b/client/src/shapes/types/utility.ts
index c57f8bb8..dc042d38 100644
--- a/client/src/shapes/types/utility.ts
+++ b/client/src/shapes/types/utility.ts
@@ -32,7 +32,13 @@ export type DashPattern = readonly [dashLength: number, gapLength: number];
 export type Stroke = {
   color: string;
   lineWidth: number;
-  dash?: DashPattern;
+  dash?: DashPattern | {
+    /**
+     * [dashLength: number, gapLength: number]
+     */
+    pattern: DashPattern,
+    offset?: number,
+  };
 };
 
 export type BorderRadiusArrayValue = [

From 7d387b38fd4418727d57d3dd51ca74c732c373b0 Mon Sep 17 00:00:00 2001
From: yonava <yonavossandreae@gmail.com>
Date: Sat, 9 Aug 2025 21:15:01 -0400
Subject: [PATCH 3/6] keyframes options

---
 client/src/shapes/animation/timeline/compile.ts | 6 ++++--
 client/src/shapes/animation/timeline/define.ts  | 2 +-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/client/src/shapes/animation/timeline/compile.ts b/client/src/shapes/animation/timeline/compile.ts
index 860d8a25..812dc643 100644
--- a/client/src/shapes/animation/timeline/compile.ts
+++ b/client/src/shapes/animation/timeline/compile.ts
@@ -95,14 +95,16 @@ export const compileTimeline = (timeline: Timeline<any>): CompiledTimeline => {
     validShapes: new Set(timeline.forShapes),
   };
 
+  const rawTimelineKeyframes = timeline?.keyframes ?? [];
+
   const propsInTimeline = [
     ...new Set(
-      timeline.keyframes.map((kf) => Object.keys(kf.properties)).flat(),
+      rawTimelineKeyframes.map((kf) => Object.keys(kf.properties)).flat(),
     ),
   ] as EverySchemaPropName[];
 
   const propToAnimationKeyframes = propsInTimeline.reduce((acc, prop) => {
-    const propInTimeline = timeline.keyframes
+    const propInTimeline = rawTimelineKeyframes
       .map((kf): AnimationKeyframe<any> => {
         const propVal = kf.properties[prop];
         const isObj = isCustomInputObject(propVal);
diff --git a/client/src/shapes/animation/timeline/define.ts b/client/src/shapes/animation/timeline/define.ts
index a2f6a3d9..de5f466d 100644
--- a/client/src/shapes/animation/timeline/define.ts
+++ b/client/src/shapes/animation/timeline/define.ts
@@ -126,7 +126,7 @@ export type TimelinePlaybackDelay = {
 export type Timeline<T extends keyof ShapeNameToSchema> = DeepReadonly<
   {
     forShapes: T[];
-    keyframes: TimelineKeyframe<SchemaWithDefaults[NoInfer<T>]>[];
+    keyframes?: TimelineKeyframe<SchemaWithDefaults[NoInfer<T>]>[];
     easing?: Partial<Record<keyof SchemaWithDefaults[NoInfer<T>], EasingOption>>;
   } & TimelinePlaybackDuration &
   TimelinePlaybackDelay &

From 5faa7648f4ec518a9c6dad2a7bcff9cb6a0d7068 Mon Sep 17 00:00:00 2001
From: yonava <yonavossandreae@gmail.com>
Date: Sat, 9 Aug 2025 22:23:07 -0400
Subject: [PATCH 4/6] specing out wip prop api

---
 .../src/playground/shape/ShapePlayground.vue  | 28 +++++----
 client/src/shapes/animation/index.ts          | 57 ++++++++++++++++++-
 client/src/shapes/animation/types.ts          |  2 +-
 3 files changed, 74 insertions(+), 13 deletions(-)

diff --git a/client/src/playground/shape/ShapePlayground.vue b/client/src/playground/shape/ShapePlayground.vue
index 5f3cd43a..ebf81bc3 100644
--- a/client/src/playground/shape/ShapePlayground.vue
+++ b/client/src/playground/shape/ShapePlayground.vue
@@ -6,22 +6,30 @@
   import { cross } from '@shapes/cross';
   import Button from '@ui/core/button/Button.vue';
 
-  const { defineTimeline, shapes } = useAnimatedShapes();
+  const { defineTimeline, shapes, getAnimatedProp } = useAnimatedShapes();
 
   const { play, stop, pause, resume } = defineTimeline({
     forShapes: ['circle'],
     durationMs: 6000,
     customInterpolations: {
       stroke: {
-        value: (p) => ({
-          lineWidth: 10 + (p < 0.5 ? p * 10 : 10 - p * 10),
-          color: 'red',
-          dash: {
-            pattern: [40, 22.832],
-            // circum = 2 pi r = 2 pi 50 = 100 pi
-            offset: p * (100 * Math.PI),
-          },
-        }),
+        value: (progress) => {
+          const r = getAnimatedProp('test', 'radius');
+          const n = 5;
+          const k = 40 / 22.832;
+          const circum = 2 * r * Math.PI;
+          const p = circum / n;
+          const L = (k / (k + 1)) * p;
+          const G = (1 / (k + 1)) * p;
+          return {
+            lineWidth: 10,
+            color: 'red',
+            dash: {
+              pattern: [L, G],
+              offset: progress * circum,
+            },
+          };
+        },
       },
     },
     keyframes: [{ progress: 0.5, properties: { radius: 100 } }],
diff --git a/client/src/shapes/animation/index.ts b/client/src/shapes/animation/index.ts
index ed0d36c0..6edd1248 100644
--- a/client/src/shapes/animation/index.ts
+++ b/client/src/shapes/animation/index.ts
@@ -1,5 +1,7 @@
+import type { UnionToIntersection } from 'ts-essentials';
 import { getSchemaWithDefaults } from '@shape/defaults/shapes';
 import type {
+  EverySchemaProp,
   EverySchemaPropName,
   SchemaId,
   Shape,
@@ -61,7 +63,7 @@ export const useAnimatedShapes = () => {
     const animations = activeAnimations.get(schemaId);
     if (!animations || animations.length === 0) return;
 
-    let outputSchema = animations[0].schema;
+    let outputSchema = animations[0].schemaWithDefaults;
 
     if (!outputSchema) {
       console.warn('animation set without a schema. this should never happen!');
@@ -120,6 +122,56 @@ export const useAnimatedShapes = () => {
     return outputSchema;
   };
 
+  const getAnimatedProp = <T extends EverySchemaPropName>(schemaId: string, inputPropName: T) => {
+    const animations = activeAnimations.get(schemaId);
+    if (!animations || animations.length === 0) {
+      throw new Error(`schema with id ${schemaId} has no running animations`)
+    };
+
+    const schemaWithDefaults = animations[0].schemaWithDefaults
+
+    if (!schemaWithDefaults) {
+      throw new Error('animation set without a schema. this should never happen!');
+    }
+
+    if (!(inputPropName in schemaWithDefaults)) {
+      throw new Error(`input prop name ${inputPropName} not a property on schema (${Object.keys(schemaWithDefaults)})`)
+    }
+
+    let propVal = schemaWithDefaults[inputPropName] as UnionToIntersection<EverySchemaProp>[T]
+
+    for (const animation of animations) {
+      const timeline = timelineIdToTimeline.get(animation.timelineId);
+      if (!timeline) throw new Error('animation activated without a timeline!');
+
+      const animationWithTimeline = {
+        ...timeline,
+        ...animation,
+      };
+
+      const shapeName = schemaIdToShapeName.get(schemaId);
+      if (!shapeName) {
+        console.warn(
+          'animation set without shape name mapping. this should never happen!',
+        );
+        continue;
+      }
+
+      if (!animationWithTimeline.validShapes.has(shapeName)) {
+        console.warn('invalid shape name!');
+        continue;
+      }
+
+      const { properties } = animationWithTimeline;
+      const progress = getAnimationProgress(animationWithTimeline);
+
+      const fn = properties[inputPropName as string]
+      propVal = fn(schemaWithDefaults, progress)
+    }
+
+    return propVal;
+  }
+
   const autoAnimate = useAutoAnimate(defineTimeline, getAnimatedSchema);
 
   const animatedFactory =
@@ -149,7 +201,7 @@ export const useAnimatedShapes = () => {
               return factory(targetMapSchema as WithId<T>)[prop];
 
             if (!animations || animations.length === 0) return target[prop];
-            if (!animations[0]?.schema) animations[0].schema = schemaWithDefaults;
+            if (!animations[0]?.schemaWithDefaults) animations[0].schemaWithDefaults = schemaWithDefaults;
 
             if (prop === 'startTextAreaEdit')
               return console.warn(
@@ -184,6 +236,7 @@ export const useAnimatedShapes = () => {
     defineTimeline,
     autoAnimate: { captureFrame: autoAnimate.captureFrame },
     getAnimatedSchema,
+    getAnimatedProp,
     activeAnimations,
   };
 };
diff --git a/client/src/shapes/animation/types.ts b/client/src/shapes/animation/types.ts
index 62ebdddb..0923d898 100644
--- a/client/src/shapes/animation/types.ts
+++ b/client/src/shapes/animation/types.ts
@@ -33,5 +33,5 @@ export type ActiveAnimation = {
   /**
    * the schema at the point the animation started
    */
-  schema?: LooseSchema;
+  schemaWithDefaults?: LooseSchema;
 };

From 560a670474a34c059f33a05ac52d28778b3095f6 Mon Sep 17 00:00:00 2001
From: yonava <yonavossandreae@gmail.com>
Date: Sat, 9 Aug 2025 23:08:46 -0400
Subject: [PATCH 5/6] fun animated prop api

---
 .../src/playground/shape/ShapePlayground.vue  |  20 +---
 client/src/shapes/animation/index.ts          | 107 +++++++++---------
 2 files changed, 62 insertions(+), 65 deletions(-)

diff --git a/client/src/playground/shape/ShapePlayground.vue b/client/src/playground/shape/ShapePlayground.vue
index ebf81bc3..bcb01423 100644
--- a/client/src/playground/shape/ShapePlayground.vue
+++ b/client/src/playground/shape/ShapePlayground.vue
@@ -15,17 +15,17 @@
       stroke: {
         value: (progress) => {
           const r = getAnimatedProp('test', 'radius');
-          const n = 5;
-          const k = 40 / 22.832;
+          const numOfDashes = 5;
+          const lengthGapRatio = 40 / 22.832;
           const circum = 2 * r * Math.PI;
-          const p = circum / n;
-          const L = (k / (k + 1)) * p;
-          const G = (1 / (k + 1)) * p;
+          const p = circum / numOfDashes;
+          const dashLength = (lengthGapRatio / (lengthGapRatio + 1)) * p;
+          const gapLength = (1 / (lengthGapRatio + 1)) * p;
           return {
             lineWidth: 10,
             color: 'red',
             dash: {
-              pattern: [L, G],
+              pattern: [dashLength, gapLength],
               offset: progress * circum,
             },
           };
@@ -39,14 +39,6 @@
     id: 'test',
     at: { x: 0, y: 0 },
     radius: 50,
-    stroke: {
-      lineWidth: 10,
-      color: 'red',
-      dash: {
-        pattern: [40, 22.832],
-        offset: 0,
-      },
-    },
     textArea: { textBlock: { content: '1' } },
   });
 
diff --git a/client/src/shapes/animation/index.ts b/client/src/shapes/animation/index.ts
index 6edd1248..dcf364d6 100644
--- a/client/src/shapes/animation/index.ts
+++ b/client/src/shapes/animation/index.ts
@@ -122,56 +122,6 @@ export const useAnimatedShapes = () => {
     return outputSchema;
   };
 
-  const getAnimatedProp = <T extends EverySchemaPropName>(schemaId: string, inputPropName: T) => {
-    const animations = activeAnimations.get(schemaId);
-    if (!animations || animations.length === 0) {
-      throw new Error(`schema with id ${schemaId} has no running animations`)
-    };
-
-    const schemaWithDefaults = animations[0].schemaWithDefaults
-
-    if (!schemaWithDefaults) {
-      throw new Error('animation set without a schema. this should never happen!');
-    }
-
-    if (!(inputPropName in schemaWithDefaults)) {
-      throw new Error(`input prop name ${inputPropName} not a property on schema (${Object.keys(schemaWithDefaults)})`)
-    }
-
-    let propVal = schemaWithDefaults[inputPropName] as UnionToIntersection<EverySchemaProp>[T]
-
-    for (const animation of animations) {
-      const timeline = timelineIdToTimeline.get(animation.timelineId);
-      if (!timeline) throw new Error('animation activated without a timeline!');
-
-      const animationWithTimeline = {
-        ...timeline,
-        ...animation,
-      };
-
-      const shapeName = schemaIdToShapeName.get(schemaId);
-      if (!shapeName) {
-        console.warn(
-          'animation set without shape name mapping. this should never happen!',
-        );
-        continue;
-      }
-
-      if (!animationWithTimeline.validShapes.has(shapeName)) {
-        console.warn('invalid shape name!');
-        continue;
-      }
-
-      const { properties } = animationWithTimeline;
-      const progress = getAnimationProgress(animationWithTimeline);
-
-      const fn = properties[inputPropName as string]
-      propVal = fn(schemaWithDefaults, progress)
-    }
-
-    return propVal;
-  }
-
   const autoAnimate = useAutoAnimate(defineTimeline, getAnimatedSchema);
 
   const animatedFactory =
@@ -236,7 +186,62 @@ export const useAnimatedShapes = () => {
     defineTimeline,
     autoAnimate: { captureFrame: autoAnimate.captureFrame },
     getAnimatedSchema,
-    getAnimatedProp,
+    /**
+     * Get the animated value of a schema property currently being animated.
+     *
+     * Intended for use in imperative timelines where resolving one property's animated value
+     * depends on the animated value of another property. In these special cases, `getAnimatedSchema`
+     * would cause a circular dependency.
+     *
+     * WARNING: Calling this on a property that the imperative track itself resolves
+     * will crash your app!
+     */
+    getAnimatedProp: <T extends EverySchemaPropName>(schemaId: string, inputPropName: T) => {
+      const animations = activeAnimations.get(schemaId);
+      if (!animations || animations.length === 0) {
+        throw new Error(`Schema with id ${schemaId} has no running animations`)
+      };
+
+      const { schemaWithDefaults } = animations[0]
+
+      if (!schemaWithDefaults) {
+        throw new Error('(Internal Error) Animation set without a schema. this should never happen!');
+      }
+
+      if (!(inputPropName in schemaWithDefaults)) {
+        throw new Error(`(User Error) Input prop name ${inputPropName} not a property on schema (${Object.keys(schemaWithDefaults)})`)
+      }
+
+      const shapeName = schemaIdToShapeName.get(schemaId);
+      if (!shapeName) {
+        throw new Error('(Internal Error) Animation set without shape name mapping. this should never happen!');
+      }
+
+      let propVal = schemaWithDefaults[inputPropName] as UnionToIntersection<EverySchemaProp>[T]
+
+      for (const animation of animations) {
+        const timeline = timelineIdToTimeline.get(animation.timelineId);
+        if (!timeline) throw new Error('(Internal Error) Animation activated without a timeline!');
+
+        const animationWithTimeline = {
+          ...timeline,
+          ...animation,
+        };
+
+        const { validShapes, timelineId } = animationWithTimeline
+        if (!validShapes.has(shapeName)) {
+          throw new Error(`(Internal Error) Attempted to apply inappropriate animation to schema! Animation timeline ${timelineId} only works for shapes ${Array.from(validShapes.keys())} but schema ${schemaId} is of shape ${shapeName}.`);
+        }
+
+        const { properties } = animationWithTimeline;
+        const progress = getAnimationProgress(animationWithTimeline);
+
+        const fn = properties[inputPropName as string]
+        propVal = fn(schemaWithDefaults, progress)
+      }
+
+      return propVal;
+    },
     activeAnimations,
   };
 };

From 239eb620dd01cf679fafa97c651becb6cb141ea1 Mon Sep 17 00:00:00 2001
From: yonava <yonavossandreae@gmail.com>
Date: Mon, 11 Aug 2025 14:56:38 +0200
Subject: [PATCH 6/6] improved errors

---
 client/src/shapes/animation/index.ts | 19 ++++++++-----------
 1 file changed, 8 insertions(+), 11 deletions(-)

diff --git a/client/src/shapes/animation/index.ts b/client/src/shapes/animation/index.ts
index dcf364d6..b5cf0de3 100644
--- a/client/src/shapes/animation/index.ts
+++ b/client/src/shapes/animation/index.ts
@@ -70,6 +70,11 @@ export const useAnimatedShapes = () => {
       return;
     }
 
+    const shapeName = schemaIdToShapeName.get(schemaId);
+    if (!shapeName) {
+      throw new Error('(Internal Error) Animation set without shape name mapping. this should never happen!');
+    }
+
     for (const animation of animations) {
       const timeline = timelineIdToTimeline.get(animation.timelineId);
       if (!timeline) throw new Error('animation activated without a timeline!');
@@ -79,17 +84,9 @@ export const useAnimatedShapes = () => {
         ...animation,
       };
 
-      const shapeName = schemaIdToShapeName.get(schemaId);
-      if (!shapeName) {
-        console.warn(
-          'animation set without shape name mapping. this should never happen!',
-        );
-        continue;
-      }
-
-      if (!animationWithTimeline.validShapes.has(shapeName)) {
-        console.warn('invalid shape name!');
-        continue;
+      const { validShapes, timelineId } = animationWithTimeline
+      if (!validShapes.has(shapeName)) {
+        throw new Error(`(Internal Error) Attempted to apply inappropriate animation to schema! Animation timeline ${timelineId} only works for shapes ${Array.from(validShapes.keys())} but schema ${schemaId} is of shape ${shapeName}.`);
       }
 
       // cleanup animation if expired