[DMP 2026]: Replace abandoned package CreateJS

[sum2it]

Ticket Contents

Description

Music Blocks currently depends on three abandoned CreateJS libraries — easeljs.min.js, tweenjs.min.js, and preloadjs.min.js — for all of its canvas-based graphics rendering. CreateJS was abandoned by its maintainers in 2017 and receives no security patches, bug fixes, or compatibility updates. This poses a long-term maintenance and security risk for the project.

The CreateJS suite is deeply integrated into the rendering pipeline: it manages the main Stage, all display object Containers, Bitmap images, Shape vector graphics, Text nodes, and Tween animations. It is used across at least 15 source files including js/block.js, js/activity.js, js/turtle.js, js/turtles.js, js/trash.js, js/boundary.js, js/pastebox.js, js/blocks.js, js/protoblocks.js, js/artwork.js, js/planetInterface.js, and activity/SugarAnimation.js.

The goal of this project is to research viable alternatives, plan a migration strategy, and execute the replacement.

Goals & Mid-Point Milestone

Goals

• Audit all usages of createjs.* APIs across the codebase and produce a comprehensive compatibility matrix
• Research and evaluate alternative libraries (e.g., Konva.js, PixiJS, Fabric.js, or native Canvas 2D API)
• Produce a written migration plan with a phased approach
• Goals Achieved By Mid-point Milestone: Complete the audit, select a replacement library, and migrate at least one major subsystem (e.g., block rendering in js/block.js or turtle rendering in js/turtle.js and js/turtles.js)
• Complete migration of all remaining subsystems
• Remove lib/easeljs.min.js, lib/tweenjs.min.js, and lib/preloadjs.min.js from the codebase
• Ensure all existing tests pass and add new tests for migrated rendering code

Setup/Installation

Follow the standard Music Blocks development setup:

Clone the repository: https://github.com/sugarlabs/musicblocks
Install dependencies: npm install
Run locally by serving index.html (e.g., npx http-server)
Run tests: npm test

Expected Outcome

The final product should be a fully functional Music Blocks application with CreateJS completely removed and replaced by a maintained, actively developed library (or native browser APIs). All visual features — block rendering, turtle graphics, animations, drag-and-drop interactions, the trashcan, boundary display, and the Sugar animation — should work identically to the current implementation. The replacement should not regress any existing functionality.

Acceptance Criteria

All createjs.* references are removed from the codebase
lib/easeljs.min.js, lib/tweenjs.min.js, and lib/preloadjs.min.js are deleted
Block rendering (SVG bitmaps, containers, hit areas) works correctly
Turtle sprite rendering, rotation, and image display work correctly
Tween-based animations (e.g., block highlighting) work correctly
The createjs.Stage / createjs.Ticker render loop is replaced
All existing Jest tests pass
No visual regressions in the UI

Implementation Details

Music Blocks uses three CreateJS libraries: easeljs.min.js, tweenjs.min.js, and preloadjs.min.js, all stored in the lib/ folder and loaded via index.html.

The main CreateJS APIs in use are:

createjs.Stage is used in index.html and js/activity.js to create the main canvas rendering stage that everything is drawn onto.

createjs.Container is used in js/block.js, js/turtles.js, js/turtle.js, js/trash.js, js/boundary.js, and js/activity.js to group display objects together so they can be moved and transformed as a unit.

createjs.Bitmap is used in js/block.js, js/turtle.js, js/turtles.js, and js/activity.js to display images such as block SVGs and turtle sprites.

createjs.Shape is used in js/block.js, js/turtle.js, js/activity.js, and js/trash.js to draw vector graphics like hit areas and highlight outlines.

createjs.Text is used in js/block.js and js/activity.js to render text labels on blocks.

createjs.Tween is used in js/activity.js for animations such as block highlighting. It also drives the render loop via createjs.Tween.hasActiveTweens(), so this coupling must be carefully handled during migration.

activity/SugarAnimation.js is an auto-generated Adobe Animate export that uses CreateJS extensively under the alias cjs. This file will likely need to be regenerated with a different export target or rewritten manually.

One important note: the actual turtle drawing (lines, arcs, fills) already uses the native HTML5 Canvas 2D API directly in js/turtle-painter.js. Only the sprite and container layer on top of it uses CreateJS, which makes that part of the migration somewhat simpler.

Candidate replacement libraries to evaluate:

Konva.js — closest API match to EaselJS, uses a Stage/Layer/Group/Image/Shape model
PixiJS — high performance, WebGL-first with Canvas fallback
Native Canvas 2D API — zero dependencies, already partially in use in the project
Technologies involved: JavaScript, HTML5 Canvas, and whichever replacement library is selected after the evaluation phase.

Mockups/Wireframes

No response

Product Name

Music Blocks

Organisation Name

Sugar Labs

Domain

⁠Education

Tech Skills Needed

JavaScript

Mentor(s)

@sum2it @walterbender @omsuneri

Category

Frontend

[Ady0333]

Hey @sum2it @walterbender @omsuneri

I'd like to work on this for C4GT 2026 as my second choice project. I've got pretty good merged PRs in this repo, a lot of them touching the Turtle system, canvas rendering layer, and activity.js directly, so I'm not starting from scratch on the codebase.

Here's my thinking on how I'd approach this:

1. Audit first, migrate second

Before touching anything, I'd do a full audit of every createjs.* call across the codebase and map each one to its equivalent in candidate libraries. The issue already lists the main ones (Stage, Container, Bitmap, Shape, Text, Tween) but I'd go file by file and build a compatibility matrix so nothing gets missed. js/block.js and js/turtle.js are the heaviest users so they'd get the most attention.

2. Library choice: Konva.js is my lean

My initial lean is Konva.js because its Stage/Layer/Group/Image/Shape model maps closest to what CreateJS provides. That means less rewriting and fewer surprises. PixiJS is powerful but WebGL-first adds complexity we probably don't need. The native Canvas 2D API is already partially in use in turtle-painter.js which is great, but building a full scene graph from scratch would take too long. I'd validate this during the audit phase and confirm with mentors before committing.

3. Phased migration

I wouldn't try to swap everything at once. I'd go subsystem by subsystem:

• First: replace the Stage and Ticker render loop in activity.js
• Then: Container and Bitmap in turtle.js and turtles.js (I've already been in these files a lot fixing fix: guard against null return from getTargetTurtle in _blockFindTurtle #6582, fix: guard doRight and doSetHeading against non-finite degrees #6744, fix: guard doArc against non-finite angle and radius #6661, [fix]: guard doForward against non-finite steps to prevent infinite loop #6639)
• Then: block rendering in block.js
• Last: SugarAnimation.js since that's an auto-generated Adobe Animate export and will probably need to be rewritten manually

Keeping the old CreateJS code behind a flag during transition means the app stays functional throughout.

4. SugarAnimation.js

This one needs a separate plan. It's auto-generated and uses CreateJS under the cjs alias heavily. I'd look at whether it can be re-exported from a different target or whether a manual rewrite is cleaner. Happy to dig into this specifically before the program starts.

Midpoint targets:

• Full audit and compatibility matrix done
• Library selected and confirmed with mentors
• turtle.js and turtles.js migrated (the subsystem I know best from my PRs)
• All existing tests still passing

I've already been reading through js/turtle.js and js/activity.js for bug fixes so the rendering layer isn't unfamiliar territory. Happy to start the audit and share findings even before the program officially kicks off if that's useful.

Looking forward to it 🙂

[sakshar2303]

Hi @sum2it @walterbender @omsuneri,

I'd love to work on this issue for DMP 2026! I've thoroughly studied the codebase and the ticket, and here's my detailed implementation plan:

---

🔍 Phase 1: Audit & Compatibility Matrix (Week 1–2)

Do a full grep/AST scan of all createjs.* references across the codebase and categorize every usage by API type:

createjs.Stage → main rendering surface
createjs.Container → grouping/transform units
createjs.Bitmap → SVG/image display
createjs.Shape → vector hit areas and outlines
createjs.Text → block labels
createjs.Tween → animations + render loop

Produce a compatibility matrix mapping each CreateJS API to its equivalent in Konva.js, PixiJS, and native Canvas 2D API, and document edge cases such as createjs.Tween.hasActiveTweens() driving the render loop and the SugarAnimation.js Adobe Animate export.

---

📊 Phase 2: Library Evaluation & Selection (Week 3)

Evaluate the three candidate libraries against project-specific criteria:

Criteria	Konva.js	PixiJS	Native Canvas
API similarity to EaselJS	✅ High	🟡 Medium	❌ Manual
Active maintenance	✅ Yes	✅ Yes	✅ Browser native
Bundle size	🟡 ~150KB	🟡 ~300KB	✅ Zero
WebGL support	❌ No	✅ Yes	❌ No
Learning curve	✅ Low	🟡 Medium	✅ Low
Hit detection support	✅ Built-in	✅ Built-in	🟡 Manual

My current leaning: Konva.js , its Stage/Layer/Group/Image/Shape model is the closest to EaselJS, minimizing rewrite risk. I'll finalize this after the audit and share a written recommendation for mentor review.

---

🛠️ Phase 3: Phased Migration (Week 4–10)

Sub-phase 3a , Turtle Rendering (Week 4–5)

js/turtle.js and js/turtles.js

Since js/turtle-painter.js already uses native Canvas 2D API for actual drawing (lines, arcs, fills), only the sprite/container layer needs migration. Replace createjs.Container with Konva Group and createjs.Bitmap with Konva Image, handle turtle rotation and sprite swapping, then validate visually and with existing tests.

Sub-phase 3b , Block Rendering (Week 6–7)

js/block.js and js/blocks.js

Replace createjs.Bitmap (SVG block images) with Konva Image, createjs.Shape (hit areas, highlight outlines) with Konva Rect/Path, createjs.Text (block labels) with Konva Text, and createjs.Container with Konva Group for drag-and-drop grouping. Ensure hit detection and drag interactions work correctly.

Sub-phase 3c — Stage, Activity & Animations (Week 8)

js/activity.js, index.html

Replace createjs.Stage with Konva Stage + Layer, and replace the createjs.Tween-driven render loop with Konva's built-in animation system (Konva.Animation or Konva.Tween). Migrate block highlight animations currently driven by createjs.Tween.

Sub-phase 3d — Remaining Files (Week 9)

js/trash.js, js/boundary.js, js/pastebox.js, js/protoblocks.js, js/artwork.js, js/planetInterface.js

Apply the same Container → Group, Shape → Konva Shape, Bitmap → Image patterns across the remaining files. These are expected to be straightforward after the core migration is stable.

Sub-phase 3e — SugarAnimation.js (Week 9–10)

activity/SugarAnimation.js

This is an auto-generated Adobe Animate export using CreateJS under the alias cjs and is the trickiest part. First evaluate if it can be regenerated with a Canvas 2D export target from Adobe Animate. If not, manually rewrite the animation logic using Konva Tweens or the Web Animations API.

---

🧪 Phase 4: Testing & Cleanup (Week 11–12)

Remove lib/easeljs.min.js, lib/tweenjs.min.js, and lib/preloadjs.min.js from the codebase and index.html. Run all existing Jest tests and fix any regressions, write new unit/integration tests for migrated rendering code, do a final grep to confirm zero createjs.* references remain, and perform a full visual regression pass across block rendering, turtle graphics, animations, trashcan, boundary display, and Sugar animation.

---

📅 Mid-point Milestone Target

By the midpoint, I plan to have completed the full audit and compatibility matrix, selected the replacement library with a written justification, and migrated both turtle rendering (3a) and block rendering (3b) — the two largest subsystems.

---

I'm comfortable with JavaScript and HTML5 Canvas and have looked into both Konva.js and PixiJS APIs. I'm excited about this project and happy to discuss or adjust this plan based on mentor feedback.

Could I be assigned to this issue? Thanks!

[MohitSr2005]

Hi everyone,

I’ve started working on this issue and have already made some initial progress.

So far, I have:

• Begun auditing createjs.* usages across key files
• Started analyzing possible replacement libraries and their compatibility
• Explored parts of the rendering pipeline to understand dependencies

I’ll continue working towards the defined milestones (audit, compatibility mapping, and initial migration of a subsystem).

Could you please assign this issue to me?

Thanks!

[siddhiguptas]

@sum2it hi, I’d like to work on this for DMP 2026. From a quick look, CreateJS is tightly coupled across stage management, containers, sprites, shapes, and tween-based animations, so the first step should be a full audit of all createjs.* usages and mapping them to equivalent abstractions.

For replacements, Konva.js seems like the closest API match (Stage/Layer/Group model), while PixiJS is more performant but would need more adaptation. Since turtle drawing already uses Canvas 2D, I think a hybrid approach (library + gradual native migration) could also make sense.

Plan would be:

audit and build a compatibility matrix
evaluate/select library
migrate one subsystem (likely turtle or block rendering)
replace animation loop (currently tied to createjs.Tween)
complete phased migration without regressions

Does this direction sound good? If yes, I can start with the audit and share a mapping doc as the first contribution.

[Chaitu7032]

I’m genuinely excited to take on this CreateJS migration because I’ve already spent deep time in the MusicBlocks codebase. I know the 15 files that need work inside out --from js/block.js to js/activity.js -- and I’ve spotted a key shortcut: js/turtle-painter.js already uses native Canvas, so the heavy lifting is mostly about swapping the sprite layer, not rewriting the whole engine. With my background in JavaScript, frontend UI, and refactoring, I plan to methodically replace CreateJS with Konva.js, sticking closely to the project goals to deliver clean results that match the ticket’s requirements. .. .

[Vedd-Patel]

@sum2it @walterbender @omsuneri

hello mentors,
i hope you all are having a great week!

i’m excited to contribute to the DMP 2026 program through this issue, and i’ll be submitting an application on the portal soon before that, i wanted to ask if there’s anything specific that is considered important for applicants, for ex, any prerequisite work, existing PRs/issues i should go through first, or whether i should directly proceed with the proposal submission

i also wanted to share that i’ve been involved in open-source development for the past 6+ months i’ve contributed to OneBusAway and some Bitcoin-related organizations/projects as well i feel this project aligns strongly with my interests and vision, and i’m genuinely excited about the opportunity to contribute to it as part of DMP 2026, so please reply when you get a moment