Merge pull request #789 from jonobr1/claude/issue-546-20250807-1706

feat: implement strokeUniform property for zoom-invariant stroke widths

Author: jonobr1

build/two.js

@@ -1200,7 +1200,7 @@ var Two = (() => {
      * @name Two.PublishDate
      * @property {String} - The automatically generated publish date in the build process to verify version release candidates.
      */
-    PublishDate: "2025-09-30T22:09:35.343Z",
+    PublishDate: "2025-09-30T22:51:48.793Z",
     /**
      * @name Two.Identifier
      * @property {String} - String prefix for all Two.js object's ids. This trickles down to SVG ids.

build/two.min.js

@@ -1208,7 +1208,7 @@ var Constants = {
    * @name Two.PublishDate
    * @property {String} - The automatically generated publish date in the build process to verify version release candidates.
    */
-  PublishDate: "2025-09-30T22:09:35.343Z",
+  PublishDate: "2025-09-30T22:51:48.793Z",
   /**
    * @name Two.Identifier
    * @property {String} - String prefix for all Two.js object's ids. This trickles down to SVG ids.

build/two.module.js

@@ -197,6 +197,13 @@ export class Group extends Shape {
    */
   _mask = null;
 
+  /**
+   * @name Two.Group#_strokeAttenuation
+   * @private
+   * @see {@link Two.Group#strokeAttenuation}
+   */
+  _strokeAttenuation = true;
+
   constructor(children) {
     super();
 
@@ -1084,6 +1091,27 @@ const proto = {
       }
     },
   },
+
+  /**
+   * @name Two.Group#strokeAttenuation
+   * @property {Boolean} - When set to `true`, stroke width scales with transformations (default behavior). When `false`, stroke width remains constant in screen space for all child shapes.
+   * @description When `strokeAttenuation` is `false`, this property is applied to all child shapes, making their stroke widths automatically adjust to compensate for the group's world transform scale, maintaining constant visual thickness regardless of zoom level. When `true` (default), stroke widths scale normally with transformations.
+   */
+  strokeAttenuation: {
+    enumerable: true,
+    get: function () {
+      return this._strokeAttenuation;
+    },
+    set: function (v) {
+      this._strokeAttenuation = !!v;
+      for (let i = 0; i < this.children.length; i++) {
+        const child = this.children[i];
+        if (child.strokeAttenuation !== undefined) {
+          child.strokeAttenuation = v;
+        }
+      }
+    },
+  },
 };
 
 // /**

src/group.js

@@ -115,6 +115,13 @@ export class Path extends Shape {
    */
   _flagMiter = true;
 
+  /**
+   * @name Two.Path#_flagStrokeAttenuation
+   * @private
+   * @property {Boolean} - Determines whether the {@link Two.Path#strokeAttenuation} needs updating.
+   */
+  _flagStrokeAttenuation = true;
+
   /**
    * @name Two.Path#_flagMask
    * @private
@@ -250,6 +257,13 @@ export class Path extends Shape {
    */
   _dashes = null;
 
+  /**
+   * @name Two.Path#_strokeAttenuation
+   * @private
+   * @see {@link Two.Path#strokeAttenuation}
+   */
+  _strokeAttenuation = true;
+
   constructor(vertices, closed, curved, manual) {
     super();
 
@@ -407,6 +421,7 @@ export class Path extends Shape {
     'beginning',
     'ending',
     'dashes',
+    'strokeAttenuation',
   ];
 
   static Utils = {
@@ -1231,6 +1246,7 @@ export class Path extends Shape {
       this._flagJoin =
       this._flagMiter =
       this._flagClip =
+      this._flagStrokeAttenuation =
         false;
 
     Shape.prototype.flagReset.call(this);
@@ -1516,6 +1532,23 @@ const proto = {
       this._dashes = v;
     },
   },
+
+  /**
+   * @name Two.Path#strokeAttenuation
+   * @property {Boolean} - When set to `true`, stroke width scales with transformations (default behavior). When `false`, stroke width remains constant in screen space.
+   * @description When `strokeAttenuation` is `false`, the stroke width is automatically adjusted to compensate for the object's world transform scale, maintaining constant visual thickness regardless of zoom level. When `true` (default), stroke width scales normally with transformations.
+   */
+  strokeAttenuation: {
+    enumerable: true,
+    get: function () {
+      return this._strokeAttenuation;
+    },
+    set: function (v) {
+      this._strokeAttenuation = !!v;
+      this._flagStrokeAttenuation = true;
+      this._flagLinewidth = true;
+    },
+  },
 };
 
 // Utility functions

src/path.js

@@ -1,5 +1,5 @@
 import { Commands } from '../utils/path-commands.js';
-import { decomposeMatrix, mod, TWO_PI } from '../utils/math.js';
+import { decomposeMatrix, mod, TWO_PI, getEffectiveStrokeWidth } from '../utils/math.js';
 import { Curve } from '../utils/curves.js';
 import { Events } from '../events.js';
 import { getRatio } from '../utils/device-pixel-ratio.js';
@@ -232,7 +232,7 @@ const canvas = {
           ctx.strokeStyle = stroke._renderer.effect;
         }
         if (linewidth) {
-          ctx.lineWidth = linewidth;
+          ctx.lineWidth = getEffectiveStrokeWidth(this);
         }
         if (miter) {
           ctx.miterLimit = miter;
@@ -490,7 +490,7 @@ const canvas = {
           ctx.strokeStyle = stroke._renderer.effect;
         }
         if (linewidth) {
-          ctx.lineWidth = linewidth;
+          ctx.lineWidth = getEffectiveStrokeWidth(this);
         }
       }
       if (typeof opacity === 'number') {
@@ -664,7 +664,7 @@ const canvas = {
           ctx.strokeStyle = stroke._renderer.effect;
         }
         if (linewidth) {
-          ctx.lineWidth = linewidth;
+          ctx.lineWidth = getEffectiveStrokeWidth(this);
         }
       }
       if (typeof opacity === 'number') {

src/renderers/canvas.js

@@ -1,5 +1,5 @@
 import { Commands } from '../utils/path-commands.js';
-import { decomposeMatrix, mod, toFixed } from '../utils/math.js';
+import { decomposeMatrix, mod, toFixed, getEffectiveStrokeWidth } from '../utils/math.js';
 import { Events } from '../events.js';
 import { _ } from '../utils/underscore.js';
 
@@ -505,7 +505,7 @@ const svg = {
       }
 
       if (this._flagLinewidth) {
-        changed['stroke-width'] = this._linewidth;
+        changed['stroke-width'] = getEffectiveStrokeWidth(this);
       }
 
       if (this._flagOpacity) {
@@ -672,7 +672,7 @@ const svg = {
       }
 
       if (this._flagLinewidth) {
-        changed['stroke-width'] = this._linewidth;
+        changed['stroke-width'] = getEffectiveStrokeWidth(this);
       }
 
       if (this._flagOpacity) {
@@ -797,7 +797,7 @@ const svg = {
         }
       }
       if (this._flagLinewidth) {
-        changed['stroke-width'] = this._linewidth;
+        changed['stroke-width'] = getEffectiveStrokeWidth(this);
       }
       if (this._flagOpacity) {
         changed.opacity = this._opacity;

src/renderers/svg.js

@@ -1,7 +1,7 @@
 import { Commands } from '../utils/path-commands.js';
 
 import { root } from '../utils/root.js';
-import { getPoT, mod, NumArray, TWO_PI } from '../utils/math.js';
+import { getPoT, mod, NumArray, TWO_PI, getEffectiveStrokeWidth } from '../utils/math.js';
 import { shaders } from '../utils/shaders.js';
 import { Events } from '../events.js';
 import { TwoError } from '../utils/error.js';
@@ -235,7 +235,7 @@ const webgl = {
           ctx.strokeStyle = stroke._renderer.effect;
         }
         if (linewidth) {
-          ctx.lineWidth = linewidth;
+          ctx.lineWidth = getEffectiveStrokeWidth(elem);
         }
         if (miter) {
           ctx.miterLimit = miter;
@@ -731,7 +731,7 @@ const webgl = {
           ctx.strokeStyle = stroke._renderer.effect;
         }
         if (linewidth) {
-          ctx.lineWidth = linewidth / aspect;
+          ctx.lineWidth = getEffectiveStrokeWidth(elem) / aspect;
         }
       }
       if (typeof opacity === 'number') {
@@ -1039,7 +1039,7 @@ const webgl = {
           ctx.strokeStyle = stroke._renderer.effect;
         }
         if (linewidth) {
-          ctx.lineWidth = linewidth;
+          ctx.lineWidth = getEffectiveStrokeWidth(elem);
         }
       }
       if (typeof opacity === 'number') {

src/renderers/webgl.js

@@ -41,6 +41,7 @@ export class Points extends Shape {
   _flagVisible = true;
   _flagSize = true;
   _flagSizeAttenuation = true;
+  _flagStrokeAttenuation = true;
 
   _length = 0;
   _fill = '#fff';
@@ -53,6 +54,7 @@ export class Points extends Shape {
   _beginning = 0;
   _ending = 1.0;
   _dashes = null;
+  _strokeAttenuation = true;
 
   constructor(vertices) {
     super();
@@ -180,6 +182,7 @@ export class Points extends Shape {
     'beginning',
     'ending',
     'dashes',
+    'strokeAttenuation',
   ];
 
   /**
@@ -702,4 +705,21 @@ const proto = {
       this._dashes = v;
     },
   },
+
+  /**
+   * @name Two.Points#strokeAttenuation
+   * @property {Boolean} - When set to `true`, stroke width scales with transformations (default behavior). When `false`, stroke width remains constant in screen space.
+   * @description When `strokeAttenuation` is `false`, the stroke width is automatically adjusted to compensate for the object's world transform scale, maintaining constant visual thickness regardless of zoom level. When `true` (default), stroke width scales normally with transformations.
+   */
+  strokeAttenuation: {
+    enumerable: true,
+    get: function () {
+      return this._strokeAttenuation;
+    },
+    set: function (v) {
+      this._strokeAttenuation = !!v;
+      this._flagStrokeAttenuation = true;
+      this._flagLinewidth = true;
+    },
+  },
 };

src/shapes/points.js

@@ -129,9 +129,9 @@ export class Text extends Shape {
   _flagVisible = true;
 
   /**
-   * @name Two.Path#_flagMask
+   * @name Two.Text#_flagMask
    * @private
-   * @property {Boolean} - Determines whether the {@link Two.Path#mask} needs updating.
+   * @property {Boolean} - Determines whether the {@link Two.Text#mask} needs updating.
    */
   _flagMask = false;
 
@@ -149,6 +149,13 @@ export class Text extends Shape {
    */
   _flagDirection = true;
 
+  /**
+   * @name Two.Text#_flagStrokeAttenuation
+   * @private
+   * @property {Boolean} - Determines whether the {@link Two.Text#strokeAttenuation} needs updating.
+   */
+  _flagStrokeAttenuation = true;
+
   // Underlying Properties
 
   /**
@@ -267,6 +274,13 @@ export class Text extends Shape {
    */
   _dashes = null;
 
+  /**
+   * @name Two.Text#_strokeAttenuation
+   * @private
+   * @see {@link Two.Text#strokeAttenuation}
+   */
+  _strokeAttenuation = true;
+
   constructor(message, x, y, styles) {
     super();
 
@@ -340,6 +354,7 @@ export class Text extends Shape {
     'fill',
     'stroke',
     'dashes',
+    'strokeAttenuation',
   ];
 
   /**
@@ -474,28 +489,34 @@ export class Text extends Shape {
    * @function
    * @returns {Two.Text}
    * @description Release the text's renderer resources and detach all events.
-   * This method disposes fill and stroke effects (calling dispose() on 
    * Gradients and Textures for thorough cleanup) while preserving the
    * renderer type for potential re-attachment to a new renderer.
    */
   dispose() {
     // Call parent dispose to preserve renderer type and unbind events
     super.dispose();
-    
     // Dispose fill effect (more thorough than unbind)
     if (typeof this.fill === 'object' && this.fill && 'dispose' in this.fill) {
       this.fill.dispose();
     } else if (typeof this.fill === 'object' && this.fill && 'unbind' in this.fill) {
+    ) {
       this.fill.unbind();
     }
 
     // Dispose stroke effect (more thorough than unbind)
     if (typeof this.stroke === 'object' && this.stroke && 'dispose' in this.stroke) {
+    if (
+      typeof this.stroke === 'object' &&
+    ) {
       this.stroke.dispose();
-    } else if (typeof this.stroke === 'object' && this.stroke && 'unbind' in this.stroke) {
+    } else if (
+      typeof this.stroke === 'object' &&
+      this.stroke &&
+      'unbind' in this.stroke
+    ) {
       this.stroke.unbind();
     }
-    
+
     return this;
   }
 
@@ -841,6 +862,22 @@ const proto = {
       this._dashes = v;
     },
   },
+  /**
+   * @name Two.Text#strokeAttenuation
+   * @property {Boolean} - When set to `true`, stroke width scales with transformations (default behavior). When `false`, stroke width remains constant in screen space.
+   * @description When `strokeAttenuation` is `false`, the stroke width is automatically adjusted to compensate for the object's world transform scale, maintaining constant visual thickness regardless of zoom level. When `true` (default), stroke width scales normally with transformations.
+   */
+  strokeAttenuation: {
+    enumerable: true,
+    get: function () {
+      return this._strokeAttenuation;
+    },
+    set: function (v) {
+      this._strokeAttenuation = !!v;
+      this._flagStrokeAttenuation = true;
+      this._flagLinewidth = true;
+    },
+  },
 };
 
 /**