[ { "path": ".agents/skills/canvasengine/SKILL.md", "content": "---\nname: canvasengine\ndescription: Work on CanvasEngine projects and .ce components using the official documentation. Use when Codex needs to explain, create, review, or modify CanvasEngine code, especially files ending in .ce, CanvasEngine reactivity with signals, computed, and effect, template directives such as @if and @for, component script/template/style structure, or CanvasEngine-specific syntax that mixes ideas from React, Vue, and Angular.\n---\n\n# CanvasEngine Project\n\n## Documentation First\n\nBefore answering or editing CanvasEngine code, fetch and read the current documentation index:\n\n```bash\ncurl -L https://canvasengine.net/llms.txt\n```\n\nIf `curl` is unavailable, use an equivalent command or tool (`wget`, browser/web fetch, or another HTTP client). If network access is blocked, say that the current documentation could not be fetched and proceed only from local code plus any already available docs.\n\nUse `llms.txt` as a table of contents:\n\n1. Read the summary and section list.\n2. Identify the Markdown documentation URLs relevant to the user request.\n3. Fetch the relevant `.md` pages with `curl -L ` or an equivalent tool.\n4. Base implementation and explanations on those pages, not on assumptions from React, Vue, Angular, or PixiJS.\n5. Mention the specific docs or examples consulted when the answer depends on them.\n\n## Project Model\n\nTreat CanvasEngine components as `.ce` files with:\n\n- a script block for state, imports, functions, signals, `computed`, and `effect`\n- component content/template markup\n- an optional CSS style block\n\nPrefer existing project conventions for file layout, imports, naming, and component composition. Inspect nearby `.ce` files before adding new patterns.\n\n## Reactivity\n\nCanvasEngine reactivity is centered on signals plus `computed` and `effect`.\n\nUse the documentation to confirm exact APIs before writing code. Do not assume that signal usage is identical to Solid, Angular, Vue, React, or another framework.\n\nImportant template rules:\n\n- In a template, `` means bind the `x` variable from the script scope. `x` may be a signal or a plain value. Do not interpret this as a boolean-only JSX prop.\n- For reactive conditions, pass the signal/reference to the directive: use `@if (show)`, not `@if (show())`.\n- For reactive loops, pass the signal/reference to the directive in the same spirit: use `@for` with the reactive source itself rather than eagerly calling or unwrapping it, unless the official docs for the exact case say otherwise.\n- Keep signal reads/writes consistent with the documented CanvasEngine syntax for the context: script code and template code may differ.\n\n## Implementation Checklist\n\nWhen modifying a CanvasEngine project:\n\n1. Fetch `llms.txt` and the relevant Markdown docs.\n2. Inspect local examples with `rg --files -g '*.ce'` and read nearby components.\n3. Preserve `.ce` component structure: script, content/template, optional style.\n4. Use CanvasEngine primitives and directives instead of importing framework habits from React/Vue/Angular.\n5. Verify shorthand bindings, reactive `@if`, and reactive `@for` syntax before finishing.\n6. Run the project’s relevant checks or at least a focused syntax/type check when available.\n" }, { "path": ".agents/skills/canvasengine/agents/openai.yaml", "content": "interface:\n display_name: \"CanvasEngine\"\n short_description: \"Guide projets CanvasEngine et fichiers .ce\"\n default_prompt: \"Use $canvasengine to implement or explain a CanvasEngine .ce component with the official docs.\"\n" }, { "path": ".agents/skills/pixijs/SKILL.md", "content": "---\nname: pixijs\ndescription: \"Use this skill first for ANY PixiJS v8 task; it routes to the right specialized skill for the job. Covers the full PixiJS surface: Application setup, the scene graph (Container, Sprite, Graphics, Text, Mesh, ParticleContainer, DOMContainer, GifSprite), rendering (WebGL/WebGPU/Canvas, render loop, custom shaders, filters, blend modes), assets, events, color, math, ticker, accessibility, performance, environments, migration from v7, and project scaffolding. Triggers on: pixi, pixi.js, pixijs, PixiJS, v8, Application, app.init, Sprite, Container, Graphics, Text, Mesh, ParticleContainer, DOMContainer, GifSprite, Assets, Ticker, renderer, WebGL, WebGPU, scene graph, filter, shader, blend mode, texture, BitmapText, create-pixi, how do I draw, how do I render, how do I animate in pixi.\"\nlicense: MIT\n---\n\nEntry point for the PixiJS v8 skill collection. PixiJS is the fastest library available for the web, working across all devices and allowing you to create rich, interactive graphics and cross-platform applications using WebGL, WebGPU, and Canvas as a fallback.\n\n## How to use this skill\n\n1. Find the specialized skill in the router below that best matches the task.\n2. Load that skill's `SKILL.md` and follow its guidance.\n3. If no sub-skill fits (the task references a specific class, function, option, or API surface not listed below), **WebFetch `https://pixijs.download/release/docs/llms.txt`**. That file is the auto-generated, always-current index of the full PixiJS API and guides. Each entry links to a `.html.md` page you can WebFetch for the detailed content.\n\nFor the long-form description and trigger keywords of every skill, see [references/index.md](references/index.md).\n\n## Skill router\n\n### Foundations\n\n| Skill | Load when... |\n|---|---|\n| [pixijs-application](../pixijs-application/SKILL.md) | Creating or configuring a PixiJS `Application`, calling `app.init()`, accessing `app.stage`/`renderer`/`canvas`/`screen`, resize/ticker plugins, `app.destroy()`. |\n| [pixijs-core-concepts](../pixijs-core-concepts/SKILL.md) | Understanding the renderer pipeline, choosing WebGL/WebGPU/Canvas, render loop internals, systems and pipes. |\n| [pixijs-create](../pixijs-create/SKILL.md) | Scaffolding a new project with the `create-pixi` CLI (bundler-vite, creation-web, framework-react templates). |\n| [pixijs-environments](../pixijs-environments/SKILL.md) | Running PixiJS in Web Workers, Node/SSR, or strict-CSP contexts (`DOMAdapter`, `WebWorkerAdapter`, `pixi.js/unsafe-eval`). |\n| [pixijs-migration-v8](../pixijs-migration-v8/SKILL.md) | Upgrading from v7 to v8 or fixing v7 patterns (`beginFill`/`endFill`, `@pixi/*` packages, `BaseTexture`, `DisplayObject`). |\n| [pixijs-scene-core-concepts](../pixijs-scene-core-concepts/SKILL.md) | Understanding the scene graph as a whole: containers vs leaves, transforms, render order, masking, `RenderLayer`. |\n\n### Scene Objects\n\n| Skill | Load when... |\n|---|---|\n| [pixijs-scene-container](../pixijs-scene-container/SKILL.md) | Working with `Container`: `addChild`/`removeChild`, transforms, `zIndex`, bounds, `toGlobal`/`toLocal`, `destroy`. |\n| [pixijs-scene-sprite](../pixijs-scene-sprite/SKILL.md) | Drawing images: `Sprite`, `AnimatedSprite`, `NineSliceSprite`, `TilingSprite`. |\n| [pixijs-scene-graphics](../pixijs-scene-graphics/SKILL.md) | Drawing vector shapes or paths: `Graphics`, `GraphicsContext`, `fill`/`stroke`, `FillGradient`, SVG. |\n| [pixijs-scene-text](../pixijs-scene-text/SKILL.md) | Rendering text: `Text`, `BitmapText`, `HTMLText`, `SplitText`, `TextStyle`. |\n| [pixijs-scene-mesh](../pixijs-scene-mesh/SKILL.md) | Custom geometry: `Mesh`, `MeshSimple`, `MeshPlane`, `MeshRope`, `PerspectiveMesh`. |\n| [pixijs-scene-particle-container](../pixijs-scene-particle-container/SKILL.md) | Rendering thousands of lightweight sprites: `ParticleContainer`, `Particle`, `dynamicProperties`. |\n| [pixijs-scene-dom-container](../pixijs-scene-dom-container/SKILL.md) | Overlaying HTML elements on the canvas: `DOMContainer`, `pixi.js/dom`. |\n| [pixijs-scene-gif](../pixijs-scene-gif/SKILL.md) | Displaying animated GIFs: `GifSprite`, `GifSource`, `pixi.js/gif`. |\n\n### Utilities\n\n| Skill | Load when... |\n|---|---|\n| [pixijs-assets](../pixijs-assets/SKILL.md) | Loading resources: `Assets.init`, `Assets.load`, bundles, manifests, spritesheets, caching. |\n| [pixijs-color](../pixijs-color/SKILL.md) | Creating or converting colors: `Color` class, hex/rgb/hsl, `tint`, `premultiply`. |\n| [pixijs-events](../pixijs-events/SKILL.md) | Handling pointer/mouse/touch/wheel input: `eventMode`, `FederatedEvent`, `hitArea`, `cursor`, drag. |\n| [pixijs-math](../pixijs-math/SKILL.md) | Points, vectors, matrices, shapes, hit testing: `Point`, `Matrix`, `Rectangle`, `toGlobal`/`toLocal`. |\n| [pixijs-ticker](../pixijs-ticker/SKILL.md) | Per-frame logic or controlling the render loop: `Ticker`, `deltaTime`, `UPDATE_PRIORITY`, `maxFPS`. |\n\n### Advanced\n\n| Skill | Load when... |\n|---|---|\n| [pixijs-accessibility](../pixijs-accessibility/SKILL.md) | Screen reader or keyboard navigation: `AccessibilitySystem`, `accessibleTitle`, `tabIndex`. |\n| [pixijs-blend-modes](../pixijs-blend-modes/SKILL.md) | Compositing with blend modes: `add`, `multiply`, `screen`, `overlay`, `pixi.js/advanced-blend-modes`. |\n| [pixijs-custom-rendering](../pixijs-custom-rendering/SKILL.md) | Writing custom shaders, uniforms, or batchers: `Shader.from`, `GlProgram`/`GpuProgram`, `UniformGroup`, custom `Filter`. |\n| [pixijs-filters](../pixijs-filters/SKILL.md) | Applying visual effects: `BlurFilter`, `ColorMatrixFilter`, `DisplacementFilter`, `Filter.from`, `pixi-filters`. |\n| [pixijs-performance](../pixijs-performance/SKILL.md) | Profiling or optimizing FPS, draw calls, GPU memory: culling, `GCSystem`, `cacheAsTexture`, object pooling. |\n\n## Fallback: canonical PixiJS docs\n\nIf the task references a class, function, option, or API surface not covered by any sub-skill above, **WebFetch `https://pixijs.download/release/docs/llms.txt`**. It's the auto-generated index of the full PixiJS API and guides, regenerated on every release. Each entry links to a `.html.md` page you can WebFetch for the detailed content. Use this fallback whenever the router table doesn't point at an obvious match.\n" }, { "path": ".agents/skills/pixijs/references/index.md", "content": "# PixiJS Skills: Full Index\n\nDetailed routing table for the PixiJS v8 skill collection. Each entry lists the skill's full description and the trigger keywords that should match it. For a scannable short-form table, see the parent `SKILL.md`.\n\n## Foundations\n\n### pixijs-application\nCreate and configure a PixiJS v8 `Application`. Covers `new Application()` + async `app.init()` options (width, height, background, antialias, resolution, autoDensity, preference, resizeTo, autoStart, sharedTicker, canvas), `app.stage`/`renderer`/`canvas`/`screen` access, `ResizePlugin`, `TickerPlugin`, and `app.destroy()`.\n\n**Triggers:** Application, app.init, app.stage, app.renderer, app.canvas, app.screen, ApplicationOptions, resizeTo, preference, autoStart, sharedTicker, app.destroy.\n\n### pixijs-core-concepts\nHow PixiJS v8 renders frames: the systems-and-pipes renderer, the render loop, and how the library adapts to different environments. Covers `WebGLRenderer`/`WebGPURenderer`/`CanvasRenderer` selection, `renderer.render()` pipeline, environment detection, and pointers to per-topic deep dives.\n\n**Triggers:** renderer, WebGL, WebGPU, Canvas, render loop, render pipeline, systems, environments, autoDetectRenderer.\n\n### pixijs-create\nScaffold a new PixiJS v8 project with the `create-pixi` CLI. Covers npm/yarn/pnpm/bun create commands, interactive vs non-interactive flows, available template presets (bundler-vite, bundler-webpack, bundler-esbuild, bundler-import-map, creation-web, framework-react, extension-default), Node version requirements, and post-scaffold dev flow.\n\n**Triggers:** create pixi.js, npm create, scaffold, template, bundler-vite, bundler-webpack, creation-web, framework-react, new project, getting started.\n\n### pixijs-environments\nRun PixiJS v8 outside a standard browser: Web Workers, `OffscreenCanvas`, Node/SSR, or CSP-restricted contexts. Covers `DOMAdapter.set`, `BrowserAdapter`, `WebWorkerAdapter`, custom `Adapter` interface, `pixi.js/unsafe-eval` for strict CSP.\n\n**Triggers:** DOMAdapter, BrowserAdapter, WebWorkerAdapter, Web Worker, OffscreenCanvas, Node, headless, SSR, CSP, unsafe-eval, Adapter.\n\n### pixijs-migration-v8\nUpgrade a PixiJS project from v7 to v8 or diagnose broken v7 code after an upgrade. Covers async `app.init`, single `pixi.js` package (deprecated `@pixi/*` sub-packages), `Graphics` shape-then-fill, `BaseTexture` -> `TextureSource`, shader/uniform rework, `ParticleContainer`+`Particle`, constructor options objects, `DisplayObject` removal, `settings`/`utils` removal, `Ticker` signature, events rewrite.\n\n**Triggers:** migrate v7, v8 breaking changes, @pixi/ import, DisplayObject, beginFill, endFill, cacheAsBitmap, BaseTexture, deprecated.\n\n### pixijs-scene-core-concepts\nThe PixiJS v8 scene graph as a whole: how containers, leaves, transforms, and render order fit together. Covers leaf vs container distinction, local/world coordinates, culling, render groups, sortable children, masking, `RenderLayer`, and which leaf skill covers which display object.\n\n**Triggers:** scene graph, display list, Container, Sprite, Graphics, Text, Mesh, ParticleContainer, DOMContainer, GifSprite, masking, render group, RenderLayer, world transform.\n\n## Scene Objects\n\n### pixijs-scene-container\nGroup, position, or transform display objects. Covers `Container` constructor options (`isRenderGroup`, `sortableChildren`, `boundsArea`), `addChild`/`removeChild`/`addChildAt`/`swapChildren`/`setChildIndex`, `position`/`scale`/`rotation`/`pivot`/`skew`/`alpha`/`tint`, `getBounds`/`getGlobalPosition`/`toLocal`/`toGlobal`, `zIndex` sorting, `cullable`, `destroy`.\n\n**Triggers:** Container, addChild, removeChild, addChildAt, swapChildren, sortableChildren, zIndex, position, scale, rotation, pivot, getBounds, toGlobal, toLocal, destroy.\n\n### pixijs-scene-dom-container\nOverlay HTML elements on the PixiJS v8 canvas. Covers `DOMContainer` with `element`, `anchor`, and scene-graph-driven CSS transforms, the `pixi.js/dom` side-effect import, `DOMPipe` registration, visibility sync, pointer-events handling.\n\n**Triggers:** DOMContainer, pixi.js/dom, DOMPipe, HTML overlay, input on canvas, iframe overlay, DOMContainerOptions, element, anchor.\n\n### pixijs-scene-gif\nDisplay animated GIFs. Covers the `pixi.js/gif` side-effect import, `Assets.load` returning a `GifSource`, `GifSprite` playback (`play`/`stop`/`currentFrame`/`animationSpeed`), `autoPlay`/`loop` options, `onComplete`/`onLoop`/`onFrameChange` callbacks, `GifSource` sharing, `clone`, `destroy`.\n\n**Triggers:** GifSprite, GifSource, pixi.js/gif, animationSpeed, currentFrame, autoPlay, onComplete, onFrameChange.\n\n### pixijs-scene-graphics\nDraw vector shapes and paths. Covers the `Graphics` shape-then-fill API (`rect`/`circle`/`ellipse`/`poly`/`roundRect`/`star`), path methods (`moveTo`/`lineTo`/`bezierCurveTo`/`arc`), `fill`/`stroke`/`cut`, `FillGradient`, `FillPattern`, `GraphicsContext` sharing, SVG markup.\n\n**Triggers:** Graphics, GraphicsContext, rect, circle, poly, roundRect, fill, stroke, cut, FillGradient, FillPattern, moveTo, bezierCurveTo, svg.\n\n### pixijs-scene-mesh\nRender custom geometry. Covers `Mesh` with `MeshGeometry` (positions, uvs, indices, topology), `MeshSimple` for per-frame vertex animation, `MeshPlane` for subdivided deformation, `MeshRope` for path-following textures, `PerspectiveMesh` for 2.5D corners.\n\n**Triggers:** Mesh, MeshGeometry, MeshSimple, MeshPlane, MeshRope, PerspectiveMesh, positions, uvs, indices, topology, setCorners.\n\n### pixijs-scene-particle-container\nRender thousands of lightweight sprites. Covers `ParticleContainer` with `Particle` instances, `addParticle`/`removeParticle`, `particleChildren` array, `dynamicProperties` (vertex, position, rotation, uvs, color), `boundsArea`, `roundPixels`, `update`.\n\n**Triggers:** ParticleContainer, Particle, IParticle, addParticle, particleChildren, dynamicProperties, boundsArea, particle effects.\n\n### pixijs-scene-sprite\nDraw images. Covers `Sprite` with `anchor`/`tint`/`texture`, `AnimatedSprite` for frame animation, `NineSliceSprite` for resizable UI panels, `TilingSprite` for scrolling/repeating backgrounds.\n\n**Triggers:** Sprite, AnimatedSprite, NineSliceSprite, TilingSprite, Sprite.from, anchor, tint, tilePosition, animationSpeed, gotoAndPlay, leftWidth, topHeight.\n\n### pixijs-scene-text\nRender text. Covers `Text` for canvas-quality styled labels, `BitmapText` for cheap per-frame updates via glyph atlas, `HTMLText` for HTML/CSS markup via SVG, `SplitText` and `SplitBitmapText` for per-character animation, `TextStyle`, `tagStyles`.\n\n**Triggers:** Text, BitmapText, HTMLText, SplitText, SplitBitmapText, TextStyle, HTMLTextStyle, BitmapFont.install, tagStyles, fontFamily, wordWrap.\n\n## Utilities\n\n### pixijs-assets\nLoad and manage resources. Covers `Assets.init`, `Assets.load`/`add`/`unload`, bundles, manifests, background loading, `onProgress`, caching, spritesheets, compressed textures, SVG as texture or Graphics, resolution detection.\n\n**Triggers:** Assets, Assets.load, Assets.init, loadBundle, manifest, backgroundLoad, Spritesheet, Cache, LoadOptions, unload.\n\n### pixijs-color\nCreate, convert, or manipulate colors. Covers `Color` class input formats (hex, CSS names, RGB/HSL objects, arrays, `Uint8Array`), conversion methods (`toHex`, `toNumber`, `toArray`, `toRgba`), component access, `setAlpha`/`multiply`/`premultiply`, `Color.shared` singleton.\n\n**Triggers:** Color, ColorSource, hex, rgb, hsl, tint, premultiply, Color.shared, color conversion.\n\n### pixijs-events\nHandle pointer, mouse, touch, or wheel input. Covers `eventMode` (none, passive, auto, static, dynamic), `FederatedEvent` types, propagation and capture phase, `hitArea`, `interactiveChildren`, `cursor` and `cursorStyles`, global move events for drag, `eventFeatures` config.\n\n**Triggers:** eventMode, FederatedPointerEvent, pointerdown, click, tap, globalpointermove, drag, hitArea, cursor, stopPropagation.\n\n### pixijs-math\nCoordinates, vectors, matrices, shapes, and hit testing. Covers `Point`/`ObservablePoint`, `Matrix` (2D affine, decompose, apply), shapes (`Rectangle`, `Circle`, `Ellipse`, `Polygon`, `RoundedRectangle`, `Triangle`), `toGlobal`/`toLocal`, `PointData` types, `DEG_TO_RAD`, and `pixi.js/math-extras` vector helpers.\n\n**Triggers:** Point, ObservablePoint, Matrix, Rectangle, Circle, Polygon, toGlobal, toLocal, hitArea, math-extras, DEG_TO_RAD, PointData.\n\n### pixijs-ticker\nRun per-frame logic or control the render loop. Covers `Ticker.add`/`addOnce`/`remove`, `deltaTime` vs `deltaMS` vs `elapsedMS`, `UPDATE_PRIORITY` ordering, `maxFPS`/`minFPS` capping, speed scaling, `Ticker.shared` vs new instances, per-object `onRender` hook, manual rendering.\n\n**Triggers:** Ticker, UPDATE_PRIORITY, deltaTime, deltaMS, elapsedMS, onRender, app.ticker, maxFPS, minFPS, Ticker.shared.\n\n## Advanced\n\n### pixijs-accessibility\nAdd screen reader and keyboard navigation to PixiJS v8 apps. Covers `AccessibilitySystem` options (`enabledByDefault`, `debug`, `activateOnTab`, `deactivateOnMouseMove`), per-container accessibility properties, shadow DOM overlay, mobile touch-hook activation.\n\n**Triggers:** accessibility, a11y, screen reader, ARIA, keyboard navigation, tab order, AccessibilitySystem, accessibleTitle, accessibleHint, tabIndex, accessibleChildren.\n\n### pixijs-blend-modes\nComposite display objects with blend modes. Covers standard modes (`normal`, `add`, `multiply`, `screen`, `erase`, `min`, `max`), advanced modes via `pixi.js/advanced-blend-modes` (`color-burn`, `overlay`, `hard-light`, etc.), batch-friendly ordering.\n\n**Triggers:** blendMode, additive, multiply, screen, overlay, color-burn, color-dodge, advanced-blend-modes, glow, erase.\n\n### pixijs-custom-rendering\nWrite custom shaders, uniforms, or batchers. Covers `Shader.from({gl, gpu, resources})`, `GlProgram`/`GpuProgram`, `UniformGroup` with typed uniforms (`f32`, `vec2`, `mat4x4`), UBO mode, textures as resources, custom `Filter`, custom `Batcher` via extensions.\n\n**Triggers:** Shader, GlProgram, GpuProgram, UniformGroup, Batcher, Filter, GLSL, WGSL, UBO, uniform, custom shader.\n\n### pixijs-filters\nApply visual effects to containers via the filter pipeline. Covers built-in filters (`AlphaFilter`, `BlurFilter`, `ColorMatrixFilter`, `DisplacementFilter`, `NoiseFilter`), custom `Filter.from()` with GLSL/WGSL, options (`resolution`, `padding`, `antialias`, `blendRequired`), `filterArea` optimization, `pixi-filters` community package.\n\n**Triggers:** filters, BlurFilter, ColorMatrixFilter, DisplacementFilter, NoiseFilter, Filter.from, GLSL filter, pixi-filters, filterArea.\n\n### pixijs-performance\nProfile or optimize a PixiJS v8 app for FPS, draw calls, or GPU memory. Covers destroy patterns (`cacheAsTexture(false)`, `releaseGlobalResources`), `GCSystem` and `TextureGCSystem`, `PrepareSystem`, object pooling, batching rules, `BitmapText` for dynamic text, culling (`Culler`, `CullerPlugin`, `cullable`, `cullArea`), resolution/antialias tradeoffs.\n\n**Triggers:** FPS, jank, draw calls, batching, object pool, GCSystem, PrepareSystem, Culler, cacheAsTexture, memory leak, destroy patterns.\n" }, { "path": ".changeset/config.json", "content": "{\n \"$schema\": \"https://unpkg.com/@changesets/config@3.0.1/schema.json\",\n \"changelog\": \"@changesets/cli/changelog\",\n \"commit\": false,\n \"fixed\": [],\n \"linked\": [],\n \"access\": \"restricted\",\n \"baseBranch\": \"v2\",\n \"updateInternalDependencies\": \"patch\",\n \"ignore\": []\n }" }, { "path": ".codex", "content": "" }, { "path": ".github/workflows/ci.yml", "content": "name: CI\n\non:\n push:\n branches:\n - \"*\"\n paths-ignore:\n - \"docs/**\"\n pull_request:\n branches:\n - \"*\"\n paths-ignore:\n - \"docs/**\"\n\njobs:\n tests:\n runs-on: ubuntu-22.04\n strategy:\n matrix:\n node-version: [20]\n steps:\n - uses: actions/checkout@v4\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n with:\n version: 9\n - name: Use Node.js ${{ matrix.node-version }}\n uses: actions/setup-node@v4\n with:\n node-version: ${{ matrix.node-version }}\n cache: \"pnpm\"\n - name: Install dependencies\n run: pnpm install --no-frozen-lockfile\n - name: Build\n run: pnpm build\n - name: Run Tests\n run: pnpm test\n\n deploy:\n needs: tests\n runs-on: ubuntu-22.04\n if: github.ref == 'refs/heads/v2'\n steps:\n - uses: actions/checkout@v4\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n with:\n version: 9\n - name: Use Node.js\n uses: actions/setup-node@v4\n with:\n node-version: 20\n cache: \"pnpm\"\n - name: Install dependencies\n run: pnpm install --no-frozen-lockfile\n - name: Build\n run: pnpm build\n - name: 📣 Create Release Pull Request or Publish to npm\n id: changesets\n uses: changesets/action@v1\n with:\n title: \"chore(release): version packages 🦋\"\n publish: pnpm publish:packages\n version: pnpm version:packages\n commit: \"chore(release): version packages 🦋 [skip ci]\"\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n NPM_TOKEN: ${{ secrets.NPM_TOKEN }}\n - name: Update Starter Package Versions\n run: |\n CORE_VERSION=$(jq -r '.version' packages/core/package.json)\n jq --arg version \"$CORE_VERSION\" '.dependencies.canvasengine = $version | .devDependencies[\"@canvasengine/compiler\"] = $version' starter/package.json > starter/package.tmp.json\n mv starter/package.tmp.json starter/package.json\n shell: bash\n - name: Commit Changes\n run: |\n git add starter/package.json\n git commit -m \"chore(release): update starter package version to $CORE_VERSION\"\n git push\n shell: bash\n" }, { "path": ".gitignore", "content": "# Logs\nlogs\n*.log\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\npnpm-debug.log*\nlerna-debug.log*\n\nnode_modules\ndist\ndist-ssr\n*.local\n\n# Editor directories and files\n.vscode/*\n!.vscode/extensions.json\n.idea\n.DS_Store\n*.suo\n*.ntvs*\n*.njsproj\n*.sln\n*.sw?\n\nlib\ncache\n.vitepress/dist\n.vitepress/cache\ncoverage\nsample/public" }, { "path": ".npmignore", "content": "tests\ntemplate\nsample\npublic\ndocs\n.vitepress\nnode_modules\nstarter\n.github\n.cursorrules\nlogo.png\ncompiler" }, { "path": "README.md", "content": "# CanvasEngine - A reactive HTML5 Canvas management library built on top of PixiJS and Vite\n\n![CanvasEngine](docs/public/logo.png)\n\nCanvasEngine is a reactive HTML5 Canvas management library built on top of PixiJS and Vite. It provides a component-oriented approach to canvas rendering, similar to modern frontend frameworks.\n\nFeatures:\n- Reactive components\n- Use flex in Canvas !\n- Easy Animation system \n- Keyboard, Gamepad et Virtual Joystick\n- Tiled Map Editor integration\n- Particle Emitter\n- Audio System\n\n## Installation\n\n```bash\nnpx degit RSamaium/CanvasEngine/starter my-project\ncd my-project\nnpm install\nnpm run dev # and go to localhost:5173\n```\n\n## Documentation\n\nhttps://canvasengine.net\n\n## Example:\n\n```html\n\n \n \n\n\n\n```\n\n## Contributing\n\nBefore, install `pnpm` and run the following command:\n\n```bash\ngit clone https://github.com/RSamaium/CanvasEngine.git\ncd CanvasEngine\npnpm install\npnpm run dev # to build the libraries\n```\n\nTo run the sample project:\n\n```bash\npnpm run dev:sample\n```\n\n### Build Documentation/Website\n\n```\ncd docs\npnpm install\npnpm run dev\n```\n\n### Release\n\n```bash\npnpm run release\n```\n\n> Choose the version you want to release\n\nPush the release branch to the remote repository\n\n```bash\ngit push origin v2\n```\n\n" }, { "path": "__mocks__/pixi-viewport.ts", "content": "import { vi } from \"vitest\";\nimport { Viewport as PixiViewport } from 'pixi-viewport';\n\nexport class Viewport extends PixiViewport {\n drag = vi.fn().mockReturnThis();\n wheel = vi.fn().mockReturnThis();\n clamp = vi.fn().mockReturnThis();\n decelerate = vi.fn().mockReturnThis();\n pinch = vi.fn().mockReturnThis();\n on = vi.fn().mockReturnThis();\n update = vi.fn().mockReturnThis();\n\n screenWidth = 0;\n screenHeight = 0;\n worldWidth = 0;\n worldHeight = 0;\n options: any = { events: {} }; // Initialize options\n input: any = { wheelFunction: vi.fn() }; // Mock input property\n}\n" }, { "path": "docs/.vitepress/config.ts", "content": "import { defineConfig } from 'vitepress';\nimport llmstxt from 'vitepress-plugin-llms'\n\nconst guideMenu = [\n {\n text: \"Quick Start\",\n collapsed: false,\n items: [\n {\n text: \"Installation\",\n link: \"/get_started/installation\",\n },\n {\n text: \"Start\",\n link: \"/get_started/start\",\n }\n ],\n },\n {\n text: \"Concepts\",\n collapsed: false,\n items: [\n {\n text: \"Template Syntax\",\n link: \"/concepts/template-syntax\",\n },\n {\n text: \"Reactivity\",\n link: \"/concepts/reactive\",\n },\n {\n text: \"Child Component\",\n link: \"/concepts/child-component\",\n },\n {\n text: \"Trigger\",\n link: \"/concepts/trigger\",\n },\n {\n text: \"Lifecycle\",\n link: \"/concepts/lifecycle\",\n },\n {\n text: \"Dependencies\",\n link: \"/concepts/dependencies\",\n },\n {\n text: \"Slot\",\n link: \"/concepts/slot\",\n },\n {\n text: \"Dynamic Components\",\n link: \"/concepts/dynamic-components\",\n },\n {\n text: \"Primitive Animation\",\n link: \"/concepts/animation\",\n },\n {\n text: \"Styling\",\n link: \"/concepts/styling\",\n }\n ],\n },\n {\n text: \"Components\",\n collapsed: false,\n items: [\n {\n text: \"Canvas\",\n link: \"/components/canvas\",\n },\n {\n text: \"Container\",\n link: \"/components/container\",\n },\n {\n text: \"Graphics\",\n link: \"/components/graphic\",\n },\n {\n text: \"Svg\",\n link: \"/components/svg\",\n },\n {\n text: \"Text\",\n link: \"/components/text\",\n },\n {\n text: \"Button\",\n link: \"/components/button\",\n },\n {\n text: \"Sprite\",\n link: \"/components/sprite\",\n },\n {\n text: \"NineSliceSprite\",\n link: \"/components/nine-slice-sprite\",\n },\n {\n text: \"Viewport\",\n link: \"/components/viewport\",\n },\n {\n text: \"TilingSprite\",\n link: \"/components/tiling-sprite\",\n },\n {\n text: \"Video\",\n link: \"/components/video\",\n },\n {\n text: \"Mesh\",\n link: \"/components/mesh\",\n },\n {\n text: \"DOMContainer\",\n link: \"/components/dom-container\",\n },\n {\n text: \"Navigation\",\n link: \"/components/navigation\",\n },\n {\n text: \"Joystick\",\n link: \"/components/joystick\",\n }\n ],\n },\n {\n text: \"Directives\",\n collapsed: false,\n items: [\n {\n text: \"Controls\",\n link: \"/directives/controls\",\n },\n {\n text: \"Drag\",\n link: \"/directives/drag\",\n },\n {\n text: \"Sound\",\n link: \"/directives/sound\",\n },\n {\n text: \"Flash\",\n link: \"/directives/flash\",\n },\n {\n text: \"Shake\",\n link: \"/directives/shake\",\n }\n ],\n },\n {\n text: \"Presets Components\",\n collapsed: false,\n items: [\n {\n text: \"Bar\",\n link: \"/presets/bar\",\n },\n {\n text: \"Loading\",\n link: \"/presets/loading\",\n },\n {\n text: \"Tilemap\",\n link: \"/presets/tilemap\",\n },\n {\n text: \"Weather\",\n link: \"/presets/weather\",\n },\n {\n text: \"NightAmbiant\",\n link: \"/presets/night-ambiant\",\n },\n {\n text: \"Footprints\",\n link: \"/presets/footprints\",\n },\n {\n text: \"Fx\",\n link: \"/presets/fx\",\n }\n ],\n },\n {\n text: \"API\",\n collapsed: false,\n items: [\n {\n text: \"Element Object\",\n link: \"/api/element\",\n },\n {\n text: \"Context\",\n link: \"/api/context\",\n },\n {\n text: \"Testing\",\n link: \"/api/testing\",\n },\n {\n text: \"Use without Compiler\",\n link: \"/advanced/without-compiler\",\n }\n ],\n },\n];\n\nexport default defineConfig({\n title: \"Canvas Engine Documentation\",\n description: \"Reactive Canvas Framework\",\n ignoreDeadLinks: true,\n themeConfig: {\n search: {\n provider: \"local\",\n },\n repo: \"https://github.com/RSamaium/CanvasEngine\",\n nav: [\n {\n text: \"Home\",\n link: \"https://canvasengine.net\",\n },\n {\n text: \"Guide\",\n link: \"/guide/get-started\",\n },\n ],\n sidebar: {\n \"/\": guideMenu,\n \"/guide/\": guideMenu,\n \"/components/\": guideMenu,\n \"/directives/\": guideMenu,\n },\n },\n vite: {\n plugins: [llmstxt()]\n },\n})\n" }, { "path": "docs/.vitepress/theme/Layout.vue", "content": "\n\n " }, { "path": "docs/.vitepress/theme/components/CustomHome.vue", "content": "\n\n\n\n " }, { "path": "docs/.vitepress/theme/components/Playground.vue", "content": "\n\n\n\n " }, { "path": "docs/.vitepress/theme/components/config.ts", "content": "const isDev = typeof window !== 'undefined' && window.location.hostname === 'localhost'\n\n/**\n * Configuration map for external dependencies\n * Ensures all CanvasEngine exports from the compiler are always available\n */\nexport const dependencyConfig = {\n 'canvasengine': {\n globalName: 'CanvasEngine',\n url: isDev ? 'http://localhost:3000/packages/core/dist/index.global.js' : 'https://cdn.jsdelivr.net/npm/canvasengine@latest/dist/index.global.js'\n },\n '@canvasengine/presets': {\n globalName: 'CanvasEnginePresets',\n url: isDev ? 'http://localhost:3000/packages/presets/dist/index.global.js' : 'https://cdn.jsdelivr.net/npm/@canvasengine/presets@latest/dist/index.global.js'\n },\n 'pixi.js': {\n globalName: 'PIXI',\n url: 'https://cdn.jsdelivr.net/npm/pixi.js@latest/dist/pixi.min.js'\n }\n }\n \n /**\n * List of primitive components that should always be available\n * Matches the PRIMITIVE_COMPONENTS from the compiler\n */\n export const PRIMITIVE_COMPONENTS = [\n \"Canvas\",\n \"Sprite\", \n \"Text\",\n \"Viewport\",\n \"Graphics\",\n \"Container\",\n \"ImageMap\",\n \"NineSliceSprite\",\n \"Rect\",\n \"Circle\",\n \"Ellipse\",\n \"Triangle\",\n \"TilingSprite\",\n \"svg\",\n \"Video\",\n \"Mesh\",\n \"Svg\",\n \"DOMContainer\",\n \"DOMElement\",\n \"Button\",\n \"Joystick\",\n \"FocusContainer\"\n ]\n \n /**\n * Core functions that should always be available\n * Matches the required imports from the compiler\n */\n export const CORE_FUNCTIONS = [\n \"h\",\n \"computed\", \n \"cond\",\n \"loop\",\n \"useProps\",\n \"useDefineProps\",\n \"bootstrapCanvas\"\n ]\n " }, { "path": "docs/.vitepress/theme/components/example.ts", "content": "interface Example {\n title: string;\n description: string;\n files: Record;\n}\n\nconst examples: Example[] = [{\n title: 'Hello World',\n description: 'A simple example of how to use CanvasEngine',\n files: {\n \"app.ce\": `\n\n \n \n \n\n\n\n `,\n \"hello.ce\": ``,\n },\n}, \n{\n title: 'Reactivity',\n description: 'Example of using reactivity in CanvasEngine',\n files: {\n \"app.ce\": `\n\n \n \n \n \n \n\n\n\n\n `,\n },\n},\n{\n title: 'With loop and condition syntax',\n description: 'Example of using loop and condition syntax in CanvasEngine',\n files: {\n \"app.ce\": `\n\n \n @if (show) {\n \n @for ((color,index) of colors) {\n \n \n }\n \n }\n \n \n \n \n \n\n\n\n\n `,\n },\n},\n {\n title: 'Drag and Drop',\n description: 'Example of using drag and drop in CanvasEngine',\n files: {\n \"app.ce\": `\n\n \n \n \n\n\n\n\n `,\n },\n},\n{\n title: 'Sprite Animation',\n description: 'Example of using sprite animation in CanvasEngine',\n files: {\n \"app.ce\": `\n\n \n \n \n\n\n\n\n `,\n },\n},\n\n// {\n// title: 'Joystick',\n// description: 'Example of using joystick in CanvasEngine',\n// files: {\n// \"app.ce\": `\n// \n// \n// \n// \n// \n\n// \n// `,\n// },\n// },\n{\n title: 'Sprite Animation and controls',\n description: 'Example of using sprite animation and controls in CanvasEngine. Use the arrow keys to move the sprite.',\n files: {\n \"app.ce\": `\n\n \n \n \n\n\n\n\n `,\n \"spritesheet.js\": `\nexport const spritesheet = (framesWidth, framesHeight, frameStand = 1) => {\n\n if (framesWidth <= frameStand) {\n frameStand = framesWidth - 1\n }\n\n const frameY = direction => {\n const gap = Math.max(4 - framesHeight, 0)\n return {\n 'down': 0,\n 'left': Math.max(0, 1 - gap),\n 'right': Math.max(0, 2 - gap),\n 'up': Math.max(0, 3 - gap)\n }[direction]\n }\n\n const stand = (direction) => [{ time: 0, frameX: frameStand, frameY: frameY(direction) }]\n const walk = direction => {\n const array = []\n const durationFrame = 10\n for (let i = 0; i < framesWidth; i++) {\n array.push({ time: i * durationFrame, frameX: i, frameY: frameY(direction) })\n }\n array.push({ time: array[array.length - 1].time + durationFrame })\n return array\n }\n\n return {\n textures: {\n 'stand': {\n animations: ({direction}) => [stand(direction)]\n },\n 'walk': {\n animations: ({direction}) => [walk(direction)]\n }\n },\n framesHeight,\n framesWidth\n }\n}\n `\n },\n},\n{\n title: 'Tiled Map',\n description: 'Example of using a Tiled map in CanvasEngine',\n files: {\n \"app.ce\": `\n\n } \n />\n\n\n\n `,\n },\n},\n{\n title: 'DOM with form',\n description: 'Example of using a Tiled map in CanvasEngine',\n files: {\n \"app.ce\": `\n\n \n
\n \n \n

{text}

\n
\n \n\n\n\n\n\n `,\n },\n},\n{\n title: 'Animated signal',\n description: 'Example of using an animated signal in CanvasEngine. Click the rect to move it.',\n files: {\n \"app.ce\": `\n\n \n \n \n\n\n\n\n\n `,\n },\n},\n{\n title: 'Joystick',\n description: 'Example of using a joystick in CanvasEngine. Use the joystick to move the rect.',\n files: {\n \"app.ce\": `\n\n \n \n \n \n \n \n \n \n\n\n\n\n\n `,\n },\n},\n{\n title: 'Flash Effect',\n description: 'Example of using flash effects in CanvasEngine. Click the rectangles to see different flash types.',\n files: {\n \"app.ce\": `\n\n \n \n \n \n \n \n alphaFlashTrigger.start()}\n />\n \n \n \n \n tintFlashTrigger.start()}\n />\n \n \n \n \n bothFlashTrigger.start()}\n />\n \n \n \n \n multiCycleFlashTrigger.start()}\n />\n \n \n \n\n\n\n\n `,\n },\n},\n{\n title: 'Shake Effect',\n description: 'Example of using shake effects in CanvasEngine. Click the rectangles to see different shake configurations.',\n files: {\n \"app.ce\": `\n\n \n \n \n \n \n \n basicShakeTrigger.start()}\n />\n \n \n \n \n horizontalShakeTrigger.start()}\n />\n \n \n \n \n verticalShakeTrigger.start()}\n />\n \n \n \n \n intenseShakeTrigger.start()}\n />\n \n \n \n\n\n\n\n `,\n },\n},\n];\n\nexport default examples;" }, { "path": "docs/.vitepress/theme/index.ts", "content": "import DefaultTheme from \"vitepress/theme\";\nimport CustomHome from \"./components/CustomHome.vue\";\nimport Playground from \"./components/Playground.vue\";\nimport Layout from \"./Layout.vue\";\nimport \"./style.css\";\n\nexport default {\n ...DefaultTheme,\n Layout,\n enhanceApp(ctx) {\n DefaultTheme.enhanceApp(ctx);\n ctx.app.component('CustomHome', CustomHome);\n ctx.app.component('Playground', Playground);\n },\n};\n" }, { "path": "docs/.vitepress/theme/style.css", "content": "/* Custom theme styles */\n:root {\n --vp-c-brand: #646cff;\n --vp-c-brand-light: #747bff;\n --vp-c-brand-lighter: #9499ff;\n --vp-c-brand-lightest: #bcc0ff;\n --vp-c-brand-dark: #535bf2;\n --vp-c-brand-darker: #454ce1;\n --vp-c-brand-dimm: rgba(100, 108, 255, 0.08);\n}\n\n/* Hide default layout for custom home */\n.custom-layout .VPContent {\n padding: 0 !important;\n}\n\n/* Smooth scrolling */\nhtml {\n scroll-behavior: smooth;\n}\n\n/* Custom scrollbar */\n::-webkit-scrollbar {\n width: 8px;\n}\n\n::-webkit-scrollbar-track {\n background: var(--vp-c-bg-soft);\n}\n\n::-webkit-scrollbar-thumb {\n background: var(--vp-c-brand);\n border-radius: 4px;\n}\n\n::-webkit-scrollbar-thumb:hover {\n background: var(--vp-c-brand-dark);\n} " }, { "path": "docs/advanced/conditional-rendering.md", "content": "# Conditional Rendering\n\nThe `cond()` function allows you to conditionally render elements based on reactive signals or static boolean values. It supports if/else if/else patterns for complex conditional logic.\n\n## Basic Usage\n\n### Simple Condition\n\n```typescript\nimport { cond, signal, h, Text } from 'canvasengine';\n\nconst isVisible = signal(true);\n\nconst conditionalText = cond(\n isVisible,\n () => h(Text, { text: 'I am visible!' })\n);\n```\n\n### With Else\n\n```typescript\nconst conditionalText = cond(\n isVisible,\n () => h(Text, { text: 'Visible' }),\n () => h(Text, { text: 'Hidden' }) // else case\n);\n```\n\n## Advanced Usage\n\n### Multiple Conditions (else if)\n\n```typescript\nconst status = signal('loading');\n\nconst statusDisplay = cond(\n () => status() === 'loading',\n () => h(Text, { text: 'Loading...', color: 'yellow' }),\n [() => status() === 'error', () => h(Text, { text: 'Error!', color: 'red' })], // else if\n [() => status() === 'success', () => h(Text, { text: 'Success!', color: 'green' })], // else if\n () => h(Text, { text: 'Unknown status', color: 'gray' }) // else\n);\n```\n\n### Grade System Example\n\n```typescript\nconst score = signal(85);\n\nconst gradeDisplay = cond(\n () => score() >= 90,\n () => h(Text, { text: 'A+', color: 'gold' }),\n [() => score() >= 80, () => h(Text, { text: 'A', color: 'green' })],\n [() => score() >= 70, () => h(Text, { text: 'B', color: 'blue' })],\n [() => score() >= 60, () => h(Text, { text: 'C', color: 'orange' })],\n () => h(Text, { text: 'F', color: 'red' }) // else\n);\n```\n\n## Condition Types\n\nThe `cond()` function accepts three types of conditions:\n\n1. **Signals**: Reactive values that trigger re-evaluation when changed\n2. **Static booleans**: Simple true/false values\n3. **Functions**: Functions that return boolean values (automatically converted to computed signals)\n\n### Examples\n\n```typescript\n// Signal condition\nconst showElement = signal(true);\ncond(showElement, () => h(Text, { text: 'Signal condition' }));\n\n// Static boolean condition\ncond(true, () => h(Text, { text: 'Static condition' }));\n\n// Function condition (reactive)\nconst user = signal({ role: 'admin' });\ncond(\n () => user().role === 'admin',\n () => h(Text, { text: 'Admin panel' })\n);\n```\n\n## Reactivity\n\nAll conditions are reactive. When any signal used in the conditions changes, the `cond()` function automatically re-evaluates and updates the rendered element:\n\n```typescript\nconst userRole = signal('guest');\n\nconst navigation = cond(\n () => userRole() === 'admin',\n () => h(Container, { children: [\n h(Text, { text: 'Admin Dashboard' }),\n h(Text, { text: 'User Management' }),\n h(Text, { text: 'Settings' })\n ]}),\n [() => userRole() === 'user', () => h(Container, { children: [\n h(Text, { text: 'Dashboard' }),\n h(Text, { text: 'Profile' })\n ]})],\n () => h(Text, { text: 'Please log in' }) // guest\n);\n\n// Changing the role will automatically update the UI\nuserRole.set('admin'); // Shows admin navigation\nuserRole.set('user'); // Shows user navigation\nuserRole.set('guest'); // Shows login message\n```\n\n## Performance\n\n- **Lazy evaluation**: Only the matching condition's element is created\n- **Automatic cleanup**: Previous elements are properly destroyed when conditions change\n- **Optimized updates**: Elements are only updated when the matching condition actually changes\n\n## Best Practices\n\n1. **Order matters**: Conditions are evaluated in order, the first `true` condition wins\n2. **Use functions for complex logic**: Convert complex boolean expressions to functions for better reactivity\n3. **Provide fallbacks**: Always consider adding an `else` case for unexpected states\n4. **Keep conditions simple**: Complex logic should be extracted to computed signals or functions\n\n```typescript\n// Good: Simple, readable conditions\nconst theme = signal('dark');\ncond(\n () => theme() === 'dark',\n () => h(Text, { text: 'Dark mode', color: 'white' }),\n () => h(Text, { text: 'Light mode', color: 'black' })\n);\n\n// Better: Extract complex logic\nconst isDarkMode = computed(() => {\n const currentTheme = theme();\n const userPreference = getUserPreference();\n const systemPreference = getSystemPreference();\n \n return currentTheme === 'dark' || \n (currentTheme === 'auto' && (userPreference === 'dark' || systemPreference === 'dark'));\n});\n\ncond(\n isDarkMode,\n () => h(Text, { text: 'Dark mode', color: 'white' }),\n () => h(Text, { text: 'Light mode', color: 'black' })\n);\n``` " }, { "path": "docs/advanced/performance.md", "content": "# Performance Optimization Guide\n\nWhen building games or visualizations with many elements (1000+), performance becomes critical. This guide covers best practices for optimizing CanvasEngine applications.\n\n## Understanding the Reactive System Cost\n\nCanvasEngine uses a reactive system based on signals. Each signal creates:\n- An RxJS subscription\n- Change detection overhead\n- Component update callbacks\n\n**Rule of thumb**: Minimize the number of signals, especially for properties that change frequently.\n\n### Signal Count Impact\n\n| Elements | Signals/Element | Total Signals | Estimated Cost |\n|----------|-----------------|---------------|----------------|\n| 100 | 5 | 500 | Low |\n| 1000 | 5 | 5,000 | Medium |\n| 5000 | 5 | 25,000 | High |\n| 5000 | 2 | 10,000 | Medium |\n\n## Optimization Strategies\n\n### 1. Reduce Signal Granularity\n\nInstead of creating signals for every property, only use signals for properties that need reactive updates from external sources.\n\n**Before (expensive)**:\n```javascript\n// 5 signals per element = 25,000 signals for 5000 elements\nfunction generateItems(count) {\n return Array.from({ length: count }, (_, i) => ({\n x: signal(i * 10),\n y: signal(i * 10),\n rotation: signal(0), // Animated - DON'T use signal!\n alpha: signal(1), // Animated - DON'T use signal!\n scale: signal(1), // Animated - DON'T use signal!\n }));\n}\n```\n\n**After (optimized)**:\n```javascript\n// 2 signals per element = 10,000 signals for 5000 elements\nfunction generateItems(count) {\n return Array.from({ length: count }, (_, i) => ({\n x: signal(i * 10), // Position needs signals for loop\n y: signal(i * 10),\n rotationSpeed: Math.random() * 0.1, // Plain value\n alphaBase: 0.5 + Math.random() * 0.5, // Plain value\n scaleBase: 0.8 + Math.random() * 0.4, // Plain value\n }));\n}\n```\n\n### 2. Imperative Animation in tick()\n\nFor animations, update Pixi objects directly instead of going through signals:\n\n```html\n\n```\n\n### 3. Incremental Collection Updates\n\nWhen adding/removing elements, avoid resetting the entire collection:\n\n**Before (expensive)**:\n```javascript\n// This triggers a full reset - destroys and recreates ALL elements\nitems.set(generateItems(newCount));\n```\n\n**After (optimized)**:\n```javascript\neffect(() => {\n const targetCount = elementCount();\n const currentItems = items();\n const currentCount = currentItems.length;\n \n if (targetCount > currentCount) {\n // Add only new elements\n const newItems = [...currentItems];\n for (let i = currentCount; i < targetCount; i++) {\n newItems.push(createItem(i));\n }\n items.set(newItems);\n } else if (targetCount < currentCount) {\n // Remove from end - avoids full recreation\n items.set(currentItems.slice(0, targetCount));\n }\n});\n```\n\n### 4. Frame Throttling\n\nFor non-critical updates, skip frames:\n\n```javascript\ntick((tickValue) => {\n // Update every 2nd frame (30 FPS effective)\n if (tickValue.frame % 2 !== 0) return;\n \n // Or every 3rd frame (20 FPS effective)\n if (tickValue.frame % 3 !== 0) return;\n \n // Animation logic\n});\n```\n\n### 5. Level of Detail (LOD)\n\nReduce visual complexity based on element count:\n\n```javascript\ntick((tickValue, element) => {\n const count = items().length;\n const sprites = getSprites(element);\n \n sprites.forEach((sprite, i) => {\n // Always animate rotation (cheap)\n sprite.rotation += items()[i].rotationSpeed;\n \n // Animate alpha only below 5000 elements\n if (count < 5000) {\n sprite.alpha = 0.5 + Math.sin(tickValue.frame * 0.02) * 0.5;\n }\n \n // Animate scale only below 2000 elements\n if (count < 2000) {\n const scale = 1 + Math.sin(tickValue.frame * 0.01) * 0.2;\n sprite.scale.set(scale);\n }\n });\n});\n```\n\n### 6. Viewport Culling\n\nUse the `viewportCull` directive to hide off-screen elements:\n\n```html\n\n \n @for (item of items) {\n \n }\n \n\n```\n\n## Complete Optimized Example\n\n```html\n\n \n \n @for (item of items) {\n \n }\n \n \n\n\n\n```\n\n## Performance Checklist\n\n- [ ] Minimize signals per element (2-3 max for large collections)\n- [ ] Use imperative updates in `tick()` for animations\n- [ ] Implement incremental add/remove for collections\n- [ ] Add frame throttling for non-critical updates\n- [ ] Implement LOD for very large element counts\n- [ ] Enable viewport culling for scrollable worlds\n- [ ] Profile with browser DevTools to identify bottlenecks\n\n## Benchmark\n\nRun the benchmark in `sample/src/benchmark.ce` to test different optimization modes:\n\n```bash\ncd sample\nnpm run dev\n```\n\nPress `1-4` to switch between optimization modes and observe FPS differences.\n" }, { "path": "docs/advanced/without-compiler.md", "content": "# Using CanvasEngine Without the Compiler\n\nCanvasEngine provides a powerful template syntax that gets compiled to JavaScript functions. However, you can also use CanvasEngine directly without the compiler by using the core functions: `h`, `loop`, and `cond` from the `canvasengine` package.\n\nThis approach gives you more control and can be useful for:\n- Dynamic template generation\n- Integration with existing build systems\n- Learning how the compiler works under the hood\n- Performance-critical applications where you want to avoid compilation overhead\n\n## Core Functions\n\n### `h(component, props?, children?)`\nCreates a component instance. This is the equivalent of JSX elements.\n\n### `loop(iterable, callback)`\nRenders a list of items. This is the equivalent of `@for` loops.\n\n### `cond(condition, callback)`\nConditionally renders content. This is the equivalent of `@if` statements.\n\n## Components\n\n### Basic Component\nInstead of writing:\n```html\n\n```\n\nUse:\n```javascript\nh('Canvas')\n```\n\n### Component with Properties\nInstead of writing:\n```html\n\n```\n\nUse:\n```javascript\nh('Canvas', { width: '800', height: '600' })\n```\n\n### Dynamic Properties\nInstead of writing:\n```html\n\n```\n\nUse:\n```javascript\nh('Canvas', { width: screenWidth, height: screenHeight })\n```\n\n### Computed Properties\nFor reactive expressions, instead of writing:\n```html\n\n```\n\nUse:\n```javascript\nh('Canvas', { width: computed(() => x() * 2) })\n```\n\n### Complex Computed Properties\nFor multiple reactive variables:\n```html\n\n```\n\nUse:\n```javascript\nh('Canvas', { width: computed(() => x() * 2 * y()) })\n```\n\n### Object Properties\nInstead of writing:\n```html\n\n```\n\nUse:\n```javascript\nh('Sprite', { \n sheet: { \n definition, \n playing: \"stand\", \n params: { \n direction: \"right\" \n }, \n onFinish \n } \n})\n```\n\n### Array Properties\nInstead of writing:\n```html\n\n```\n\nUse:\n```javascript\nh('Canvas', { positions: computed(() => [x(), 20]) })\n```\n\n### Event Handlers\nInstead of writing:\n```html\n\n```\n\nUse:\n```javascript\nh('Sprite', { click: handleClick })\n```\n\n### Inline Event Handlers\nInstead of writing:\n```html\n console.log('clicked')} />\n```\n\nUse:\n```javascript\nh('Sprite', { click: () => console.log('clicked') })\n```\n\n### Spread Operator\nInstead of writing:\n```html\n\n```\n\nUse:\n```javascript\nh('Canvas', props)\n```\n\n### Component as Property\nInstead of writing:\n```html\n} />\n```\n\nUse:\n```javascript\nh('Canvas', { child: h('Sprite') })\n```\n\n### Function Returning Component\nInstead of writing:\n```html\n } />\n```\n\nUse:\n```javascript\nh('Canvas', { child: () => h('Sprite') })\n```\n\n## Children\n\n### Single Child\nInstead of writing:\n```html\n\n \n\n```\n\nUse:\n```javascript\nh('Canvas', null, h('Sprite'))\n```\n\n### Multiple Children\nInstead of writing:\n```html\n\n \n \n\n```\n\nUse:\n```javascript\nh('Canvas', null, [\n h('Sprite'),\n h('Text')\n])\n```\n\n## Loops\n\n### Basic Loop\nInstead of writing:\n```html\n@for (sprite of sprites) {\n \n}\n```\n\nUse:\n```javascript\nloop(sprites, sprite => h('Sprite'))\n```\n\n### Loop with Properties\nInstead of writing:\n```html\n@for (sprite of sprites) {\n \n}\n```\n\nUse:\n```javascript\nloop(sprites, sprite => h('Sprite', { x: sprite.x, y: sprite.y }))\n```\n\n### Loop with Index\nInstead of writing:\n```html\n@for ((sprite, index) of sprites) {\n \n}\n```\n\nUse:\n```javascript\nloop(sprites, (sprite, index) => h('Sprite', { key: index }))\n```\n\n### Loop with Object Property\nInstead of writing:\n```html\n@for (sprite of sprites.items) {\n \n}\n```\n\nUse:\n```javascript\nloop(sprites.items, sprite => h('Sprite'))\n```\n\n### Loop with Function Call\nInstead of writing:\n```html\n@for (sprite of getSprites()) {\n \n}\n```\n\nUse:\n```javascript\nloop(getSprites(), sprite => h('Sprite'))\n```\n\n### Nested Loops\nInstead of writing:\n```html\n@for (sprite of sprites) {\n @for (other of others) {\n \n }\n}\n```\n\nUse:\n```javascript\nloop(sprites, sprite => \n loop(others, other => h('Sprite'))\n)\n```\n\n### Loop in Component\nInstead of writing:\n```html\n\n @for (sprite of sprites) {\n \n }\n\n```\n\nUse:\n```javascript\nh('Canvas', null, loop(sprites, sprite => h('Sprite')))\n```\n\n## Conditions\n\n### Basic Condition\nInstead of writing:\n```html\n@if (sprite) {\n \n}\n```\n\nUse:\n```javascript\ncond(sprite, () => h('Sprite'))\n```\n\n### Property-based Condition\nInstead of writing:\n```html\n@if (sprite.visible) {\n \n}\n```\n\nUse:\n```javascript\ncond(sprite.visible, () => h('Sprite'))\n```\n\n### Function-based Condition\nInstead of writing:\n```html\n@if (isVisible()) {\n \n}\n```\n\nUse:\n```javascript\ncond(isVisible(), () => h('Sprite'))\n```\n\n### Complex Conditions\nInstead of writing:\n```html\n@if (!sprite && other) {\n \n}\n```\n\nUse:\n```javascript\ncond(computed(() => !sprite() && other()), () => h('Sprite'))\n```\n\n### Multiple Conditions\nInstead of writing:\n```html\n@if (sprite) {\n \n}\n@if (other) {\n \n}\n```\n\nUse:\n```javascript\n[\n cond(sprite, () => h('Sprite')),\n cond(other, () => h('Text'))\n]\n```\n\n### Nested Conditions\nInstead of writing:\n```html\n@if (sprite.visible) {\n @if (deep) {\n \n }\n}\n```\n\nUse:\n```javascript\ncond(sprite.visible, () => \n cond(deep, () => h('Sprite'))\n)\n```\n\n### Condition with Multiple Elements\nInstead of writing:\n```html\n@if (sprite.visible) {\n \n \n}\n```\n\nUse:\n```javascript\ncond(sprite.visible, () => [\n h('Sprite'),\n h('Text')\n])\n```\n\n## Combining Loops and Conditions\n\n### Condition in Loop\nInstead of writing:\n```html\n\n @for (sprite of sprites) {\n @if (sprite.visible) {\n \n }\n }\n\n```\n\nUse:\n```javascript\nh('Canvas', null, \n loop(sprites, sprite => \n cond(sprite.visible, () => h('Sprite'))\n )\n)\n```\n\n### Multiple Loops\nInstead of writing:\n```html\n\n @for (sprite of sprites) {\n \n }\n @for (other of others) {\n \n }\n\n```\n\nUse:\n```javascript\nh('Canvas', null, [\n loop(sprites, sprite => h('Sprite')),\n loop(others, other => h('Text'))\n])\n```\n\n## Complete Example\n\nHere's a complete example showing how to build a complex component without the compiler:\n\n```javascript\nimport { h, loop, cond, computed } from 'canvasengine';\n\nfunction GameScene({ sprites, enemies, showUI }) {\n return h('Canvas', { width: 800, height: 600 }, [\n // Background\n h('Sprite', { texture: 'background' }),\n \n // Player sprites\n loop(sprites, sprite => \n cond(sprite.visible, () => \n h('Sprite', {\n x: sprite.x,\n y: sprite.y,\n texture: sprite.texture,\n click: () => sprite.onClick()\n })\n )\n ),\n \n // Enemies\n loop(enemies, (enemy, index) => \n h('Sprite', {\n key: index,\n x: computed(() => enemy.x() + 10),\n y: computed(() => enemy.y() + 10),\n texture: enemy.texture,\n tint: enemy.isHit ? 0xff0000 : 0xffffff\n })\n ),\n \n // UI overlay\n cond(showUI, () => \n h('Container', null, [\n h('Text', { text: 'Score: 100', x: 10, y: 10 }),\n h('Text', { text: 'Lives: 3', x: 10, y: 30 })\n ])\n )\n ]);\n}\n```\n\nThis approach gives you the full power of CanvasEngine while maintaining complete control over your component structure and logic." }, { "path": "docs/api/context.md", "content": "# Context\n\nThe context is an object that is automatically provided to all components in the component tree. It contains shared resources and utilities that are available throughout your application.\n\n## Available Properties\n\nThe context object contains the following properties:\n\n| Name | Type | Description |\n|------|------|-------------|\n| `app` | `() => Application \\| null` | Function that returns the PixiJS Application instance. Returns `null` until the canvas is rendered. |\n| `canvasSize` | `Signal<{ width: number, height: number }>` | Signal containing the current width and height of the canvas. Updates automatically when the canvas is resized. |\n| `globalLoader` | `GlobalAssetLoader` | Global asset loader instance that tracks loading progress of all assets across the component tree. See [GlobalAssetLoader documentation](/components/sprite.html#global-asset-loader) for more details. |\n| `tick` | `Signal` | Signal containing the ticker information. Updates on each frame with timing and frame data. See [Tick interface](#tick-interface) below. |\n| `rootElement` | `Element` | The root Canvas element. See [Element documentation](./element.md) for more details. |\n\n## Tick Interface\n\nThe `tick` signal contains the following properties:\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `timestamp` | `number` | Current timestamp in milliseconds |\n| `deltaTime` | `number` | Time elapsed since the last frame in milliseconds |\n| `frame` | `number` | Current frame number |\n| `deltaRatio` | `number` | Ratio of deltaTime to the target frame time (useful for frame-independent animations) |\n\n## Accessing Context\n\nYou can access the context through the `element.props.context` property in any component:\n\n```html\n\n```\n\n## Examples\n\n### Using Canvas Size for Responsive Layouts\n\n```html\n\n \n\n\n\n```\n\n### Tracking Asset Loading Progress\n\n```html\n\n \n \n \n\n\n\n```\n\n### Using Tick for Frame-Independent Animations\n\n```html\n\n\n\n```\n\n### Accessing PixiJS Application\n\n```html\n\n \n\n\n\n```\n" }, { "path": "docs/api/element.md", "content": "# Element Interface\n\nThe Element interface represents a component in the framework. It contains all the necessary properties and methods to manage a component's lifecycle, props, effects, and relationships.\n\n## Properties and Methods\n\n| Name | Type | Description |\n|------|------|-------------|\n| `tag` | `string` | The HTML tag name or component name |\n| `props` | `Props` | The component's properties/attributes |\n| `componentInstance` | `T` | The instance of the component. It is the PixiJS instance |\n| `propObservables` | `NestedSignalObjects \\| undefined` | Observable objects for reactive properties |\n| `parent` | `Element \\| null` | Reference to the parent element. Null if it's a root element |\n| `context` | `{ [key: string]: any }` | Optional context object for sharing data between components |\n| `directives` | `{ [key: string]: Directive }` | Map of directives applied to the element |\n| `destroy` | `() => void` | Cleanup method called when the element is being destroyed |\n| `isFrozen` | `boolean` | Indicates whether the element is currently frozen (read-only)\n\n## Examples\n\n### Get the tag name\n\n```html\n\n\n\n```\n\n### Get the children components:\n\n```html\n\n \n\n\n\n```\n\n### Get context\n```html\n\n```\n\n### Get the reactive props\n\n```html\n\n\n\n\n```\n\n### Get directives\n\nYou can access directive instances through the `directives` property. Each directive is stored with its attribute name as the key.\n\n```html\n\n\n\n```\n\n## Freeze System\n\nThe `freeze` prop allows you to completely freeze an element, preventing all updates, controls, and events. When an element is frozen:\n\n- **Reactive updates are blocked**: No `onUpdate` calls are made when signal values change\n- **Controls are blocked**: All input controls (keyboard, gamepad, joystick) are stopped\n- **Events are blocked**: Event handlers (click, mousedown, etc.) are not executed\n\nThe `freeze` prop accepts either a `boolean` or `Signal`, allowing you to toggle the freeze state dynamically.\n\n### Basic Usage\n\n```html\n\n\n\n\n\n```\n\n### Example: Dynamic Freeze\n\n```html\n\n \n \n y.set(y() - 10)\n }\n }}\n click={() => {\n console.log('Sprite clicked!')\n }}\n />\n \n\n\n\n```\n\n### Example: Blocking Updates\n\nWhen frozen, reactive property updates are completely blocked:\n\n```html\n\n\n\n```\n\n### Example: Blocking Controls\n\nWhen frozen, all controls are automatically stopped:\n\n```html\n {\n console.log('Moving...'); // Won't execute when frozen\n }\n }\n }}\n/>\n```\n\n### Example: Blocking Events\n\nWhen frozen, event handlers are not executed:\n\n```html\n {\n console.log('Clicked!'); // Won't execute when frozen\n }}\n mousedown={() => {\n console.log('Mouse down!'); // Won't execute when frozen\n }}\n/>\n```\n\n### Checking Freeze State\n\nYou can check if an element is frozen using the `isElementFrozen` helper function:\n\n```html\n\n```\n\nOr access the `isFrozen` property directly:\n\n```html\n\n```" }, { "path": "docs/api/testing.md", "content": "# Testing Package\n\nThe `@canvasengine/testing` package provides comprehensive testing utilities and mocks for CanvasEngine. It allows you to test your CanvasEngine components without requiring a full PixiJS environment or jsdom setup.\n\n## Installation\n\n```bash\nnpm install @canvasengine/testing --save-dev\n```\n\nor with pnpm:\n\n```bash\npnpm add @canvasengine/testing --save-dev\n```\n\n## Overview\n\nThe testing package includes:\n\n- **PixiJS Mocks**: Complete mocks for all PixiJS classes used in CanvasEngine (Container, Sprite, Text, Application, etc.)\n- **Element Helpers**: Utilities to create mock elements with spyable `componentInstance`\n- **Spy Utilities**: Helpers to easily spy on element properties and methods\n\n## PixiJS Mocks\n\nThe package provides mocks for all major PixiJS classes:\n\n- `MockContainer` - Mock for PixiJS Container\n- `MockSprite` - Mock for PixiJS Sprite\n- `MockText` - Mock for PixiJS Text\n- `MockGraphics` - Mock for PixiJS Graphics\n- `MockMesh` - Mock for PixiJS Mesh\n- `MockTilingSprite` - Mock for PixiJS TilingSprite\n- `MockNineSlicePlane` - Mock for PixiJS NineSlicePlane\n- `MockDOMElement` - Mock for PixiJS DOMElement\n- `MockDOMContainer` - Mock for PixiJS DOMContainer\n- `MockApplication` - Mock for PixiJS Application\n- `MockTexture` - Mock for PixiJS Texture\n- `MockRectangle` - Mock for PixiJS Rectangle\n- `MockObservablePoint` - Mock for PixiJS ObservablePoint\n- `MockVideoResource` - Mock for PixiJS VideoResource\n\nAll mocks include:\n- Essential properties (x, y, width, height, alpha, visible, rotation, etc.)\n- Methods mocked with `vi.fn()` for easy spying\n- Event support (on, off, emit)\n- Child management for Container-based mocks\n\n### Using PixiJS Mocks\n\n```typescript\nimport { MockContainer, MockSprite } from '@canvasengine/testing';\n\n// Create a mock container\nconst container = new MockContainer();\ncontainer.x = 100;\ncontainer.y = 50;\ncontainer.width = 200;\ncontainer.height = 150;\n\n// Create a mock sprite\nconst sprite = new MockSprite();\nsprite.x = 10;\nsprite.y = 10;\n\n// Add sprite to container\ncontainer.addChild(sprite);\n\n// Spy on methods\nimport { vi } from 'vitest';\nconst addChildSpy = vi.spyOn(container, 'addChild');\ncontainer.addChild(new MockContainer());\nexpect(addChildSpy).toHaveBeenCalled();\n```\n\n## Creating Mock Elements\n\nThe `createMockElement` helper creates a complete mock Element with all required properties.\n\n### Basic Usage\n\n```typescript\nimport { createMockElement } from '@canvasengine/testing';\n\n// Create a basic element with default mock\nconst element = createMockElement('Container', { x: 100, y: 50 });\n\nexpect(element.tag).toBe('Container');\nexpect(element.props.x).toBe(100);\nexpect(element.componentInstance.x).toBe(100);\n```\n\n### With Custom ComponentInstance\n\n```typescript\nimport { createMockElement, MockSprite } from '@canvasengine/testing';\n\n// Create an element with custom componentInstance\nconst customInstance = new MockSprite();\nconst spriteElement = createMockElement('Sprite', { \n image: 'hero.png',\n x: 200,\n y: 100\n}, customInstance);\n\nexpect(spriteElement.componentInstance).toBe(customInstance);\nexpect(spriteElement.componentInstance.x).toBe(200);\n```\n\n### Accessing componentInstance\n\nThe `componentInstance` property contains the mock PixiJS instance, which you can spy upon:\n\n```typescript\nimport { createMockElement } from '@canvasengine/testing';\nimport { vi } from 'vitest';\n\nconst element = createMockElement('Container', { x: 100 });\n\n// Access the componentInstance\nconst instance = element.componentInstance;\nexpect(instance.x).toBe(100);\n\n// Spy on properties or methods\nconst xSpy = vi.spyOn(instance, 'x', 'get');\nconst addChildSpy = vi.spyOn(instance, 'addChild');\n```\n\n## Spying on Elements\n\nThe `spyOnElement` helper makes it easy to spy on element properties and methods.\n\n### Spying on a Single Property\n\n```typescript\nimport { createMockElement, spyOnElement } from '@canvasengine/testing';\n\nconst element = createMockElement('Container', { x: 100 });\n\n// Spy on a property\nconst spy = spyOnElement(element, 'x');\nelement.componentInstance.x = 200;\n\n// Note: For property setters, you may need to use vi.spyOn directly\n// depending on your testing needs\n```\n\n### Spying on Methods\n\n```typescript\nimport { createMockElement, spyOnElement } from '@canvasengine/testing';\n\nconst element = createMockElement('Container');\n\n// Spy on a method\nconst addChildSpy = spyOnElement(element, 'addChild');\n\nelement.componentInstance.addChild(new MockContainer());\n\nexpect(addChildSpy).toHaveBeenCalled();\n```\n\n### Spying on Multiple Properties\n\n```typescript\nimport { createMockElement, spyOnElementMultiple } from '@canvasengine/testing';\n\nconst element = createMockElement('Container');\n\n// Spy on multiple methods at once\nconst spies = spyOnElementMultiple(element, ['addChild', 'removeChild', 'destroy']);\n\nelement.componentInstance.addChild(new MockContainer());\nelement.componentInstance.removeChild(element.componentInstance.children[0]);\nelement.componentInstance.destroy();\n\nexpect(spies.addChild).toHaveBeenCalled();\nexpect(spies.removeChild).toHaveBeenCalled();\nexpect(spies.destroy).toHaveBeenCalled();\n```\n\n## Creating Mock Component Instances\n\nThe `createMockComponentInstance` helper creates appropriate mock instances based on component type:\n\n```typescript\nimport { createMockComponentInstance } from '@canvasengine/testing';\n\nconst containerInstance = createMockComponentInstance('Container');\nconst spriteInstance = createMockComponentInstance('Sprite');\nconst textInstance = createMockComponentInstance('Text');\n```\n\n## Common Use Cases\n\n### Testing Component Logic\n\n```typescript\nimport { describe, test, expect, vi } from 'vitest';\nimport { createMockElement, spyOnElement } from '@canvasengine/testing';\n\ndescribe('MyComponent', () => {\n test('should update position', () => {\n const element = createMockElement('Container', { x: 0, y: 0 });\n \n // Your component logic that updates position\n element.componentInstance.x = 100;\n element.componentInstance.y = 50;\n \n expect(element.componentInstance.x).toBe(100);\n expect(element.componentInstance.y).toBe(50);\n });\n\n test('should add children', () => {\n const parent = createMockElement('Container');\n const child = createMockElement('Sprite');\n \n const addChildSpy = spyOnElement(parent, 'addChild');\n parent.componentInstance.addChild(child.componentInstance);\n \n expect(addChildSpy).toHaveBeenCalledWith(child.componentInstance);\n expect(parent.componentInstance.children).toContain(child.componentInstance);\n });\n});\n```\n\n### Testing Directives\n\n```typescript\nimport { describe, test, expect } from 'vitest';\nimport { createMockElement } from '@canvasengine/testing';\n\ndescribe('MyDirective', () => {\n test('should apply directive to element', () => {\n const element = createMockElement('Sprite', { x: 100, y: 100 });\n \n // Apply your directive\n // directive.onInit(element);\n \n // Test directive behavior\n // expect(element.directives.myDirective).toBeDefined();\n });\n});\n```\n\n### Testing Event Handlers\n\n```typescript\nimport { describe, test, expect } from 'vitest';\nimport { createMockElement } from '@canvasengine/testing';\n\ndescribe('Event Handling', () => {\n test('should handle click events', () => {\n const element = createMockElement('Sprite');\n const clickHandler = vi.fn();\n \n element.componentInstance.on('click', clickHandler);\n element.componentInstance.emit('click', { x: 100, y: 100 });\n \n expect(clickHandler).toHaveBeenCalledWith({ x: 100, y: 100 });\n });\n});\n```\n\n## Migration from Manual Mocks\n\nIf you're currently creating manual mocks in your tests, you can migrate to use `@canvasengine/testing`:\n\n### Before\n\n```typescript\n// Manual mock\nclass MockContainer {\n x = 0;\n y = 0;\n children = [];\n addChild() {}\n}\n\nconst element = {\n tag: 'Container',\n props: { x: 100 },\n componentInstance: new MockContainer(),\n // ... other properties\n};\n```\n\n### After\n\n```typescript\nimport { createMockElement } from '@canvasengine/testing';\n\nconst element = createMockElement('Container', { x: 100 });\n// All properties are automatically set up\n```\n\n## Best Practices\n\n1. **Use createMockElement for Elements**: Always use `createMockElement` when you need an Element in tests. It ensures all required properties are present.\n\n2. **Spy on componentInstance**: Use `spyOnElement` to spy on the PixiJS instance methods and properties.\n\n3. **Use Appropriate Mocks**: Use the specific mock class (MockSprite, MockText, etc.) when you need a particular PixiJS class.\n\n4. **Test Behavior, Not Implementation**: Focus on testing the behavior of your components rather than internal PixiJS implementation details.\n\n5. **Clean Up**: The mocks are lightweight and don't require cleanup, but if you're using spies, remember to clear them between tests if needed.\n\n## TypeScript Support\n\nThe package is fully typed and provides TypeScript definitions for all mocks and helpers. You'll get full autocomplete and type checking in your tests.\n\n```typescript\nimport { createMockElement, Element, ComponentInstance } from '@canvasengine/testing';\n\nconst element: Element = createMockElement('Container');\n```\n\n## Using Mocks with bootstrapCanvas\n\nThe `bootstrapCanvas` function supports component registration configuration, allowing you to use mocks for testing.\n\n### mockComponents\n\nThe `mockComponents` object provides a mapping of all CanvasEngine component names to their corresponding mock classes. You can import it from `@canvasengine/testing`:\n\n```typescript\nimport { mockComponents } from '@canvasengine/testing';\n```\n\n### Registering All Mocks\n\nTo register all components as mocks:\n\n```typescript\nimport { bootstrapCanvas } from 'canvasengine';\nimport { mockComponents } from '@canvasengine/testing';\n\nawait bootstrapCanvas(rootElement, MyComponent, {\n components: mockComponents,\n autoRegister: false // Only register the specified (mocked) components\n});\n```\n\n### Registering Specific Mocks\n\nTo register only specific components as mocks while keeping others as real components:\n\n```typescript\nimport { bootstrapCanvas } from 'canvasengine';\nimport { MockSprite, MockContainer, mockComponents } from '@canvasengine/testing';\n\nawait bootstrapCanvas(rootElement, MyComponent, {\n components: {\n Sprite: MockSprite,\n Container: MockContainer,\n // Other components will be registered normally\n },\n autoRegister: true // Register all default components, then override with mocks\n});\n```\n\n### Overriding Specific Components\n\nTo register all default components but override specific ones with mocks:\n\n```typescript\nimport { bootstrapCanvas } from 'canvasengine';\nimport { MockSprite } from '@canvasengine/testing';\n\nawait bootstrapCanvas(rootElement, MyComponent, {\n components: {\n Sprite: MockSprite // Replace Sprite with mock, keep others as real\n },\n autoRegister: true // Register all default components first\n});\n```\n\n### Available Mock Components\n\nThe `mockComponents` object includes mappings for:\n\n- `Canvas` → `MockContainer`\n- `Container` → `MockContainer`\n- `Sprite` → `MockSprite`\n- `Text` → `MockText`\n- `Graphics`, `Rect`, `Circle`, `Ellipse`, `Triangle`, `Svg` → `MockGraphics`\n- `Mesh` → `MockMesh`\n- `TilingSprite` → `MockTilingSprite`\n- `NineSliceSprite` → `MockNineSlicePlane`\n- `DOMContainer` → `MockDOMContainer`\n- `DOMElement` → `MockDOMElement`\n- `Viewport` → `MockContainer`\n- `ParticlesEmitter` → `MockContainer`\n\nYou can access individual mocks directly:\n\n```typescript\nimport {\n MockContainer,\n MockSprite,\n MockText,\n MockGraphics,\n MockMesh,\n MockTilingSprite,\n MockNineSlicePlane,\n MockDOMElement,\n MockDOMContainer,\n mockComponents\n} from '@canvasengine/testing';\n```\n\n## API Reference\n\n### mockComponents\n\n```typescript\nconst mockComponents: {\n readonly Canvas: typeof MockContainer;\n readonly Container: typeof MockContainer;\n readonly Sprite: typeof MockSprite;\n readonly Text: typeof MockText;\n readonly Graphics: typeof MockGraphics;\n readonly Rect: typeof MockGraphics;\n readonly Circle: typeof MockGraphics;\n readonly Ellipse: typeof MockGraphics;\n readonly Triangle: typeof MockGraphics;\n readonly Svg: typeof MockGraphics;\n readonly Mesh: typeof MockMesh;\n readonly TilingSprite: typeof MockTilingSprite;\n readonly NineSliceSprite: typeof MockNineSlicePlane;\n readonly DOMContainer: typeof MockDOMContainer;\n readonly DOMElement: typeof MockDOMElement;\n readonly Viewport: typeof MockContainer;\n readonly ParticlesEmitter: typeof MockContainer;\n}\n```\n\nMapping of CanvasEngine component names to their corresponding mock classes. Can be used directly with `bootstrapCanvas()`.\n\n### createMockElement\n\n```typescript\nfunction createMockElement(\n tag: string,\n props?: Props,\n componentInstance?: T\n): Element\n```\n\nCreates a mock Element with all required properties.\n\n### createMockComponentInstance\n\n```typescript\nfunction createMockComponentInstance(componentType: string): ComponentInstance\n```\n\nCreates a mock ComponentInstance based on the component type.\n\n### spyOnElement\n\n```typescript\nfunction spyOnElement(\n element: Element,\n property: keyof T | string\n): ReturnType\n```\n\nCreates a spy on a property or method of an element's componentInstance.\n\n### spyOnElementMultiple\n\n```typescript\nfunction spyOnElementMultiple(\n element: Element,\n properties: (keyof T | string)[]\n): Record>\n```\n\nCreates spies on multiple properties or methods at once.\n" }, { "path": "docs/components/_display-object.md", "content": "## Common Properties\n\n| Property | Type | Description |\n|----------------|---------------------|-----------------------------------------------------------------------------|\n| x | number | X-coordinate position of the display object. |\n| y | number | Y-coordinate position of the display object. |\n| width | number | Width of the display object. |\n| height | number | Height of the display object. |\n| scale | object | Scale of the display object. |\n| anchor | object | Anchor point of the display object. |\n| skew | object | Skew of the display object. |\n| tint | number | Tint color of the display object. |\n| rotation | number | Rotation of the display object in radians. |\n| angle | number | Rotation of the display object in degrees. |\n| zIndex | number | Z-index of the display object. |\n| roundPixels | boolean | Whether to round pixel values. |\n| cursor | string | Cursor style when hovering over the display object. |\n| visible | boolean | Visibility of the display object. |\n| alpha | number | Alpha transparency of the display object. |\n| pivot | object | Pivot point of the display object. |\n| filters | array | Filters applied to the display object. |\n| maskOf | Element | Element that this display object masks. |\n| blendMode | string | Blend mode for rendering. |\n| filterArea | object | Filter area for rendering. |\n\n## Layout Properties\n\nPour obtenir la documentation complète et détaillée sur toutes les propriétés de mise en page, consultez la documentation officielle de [PixiJS Layout](https://layout.pixijs.io/).\n\n### Sizing and Dimensions\n\n| Property | Type | Description |\n|----------------|---------------------|-----------------------------------------------------------------------------|\n| width | number/string | Width of the display object. Accepts pixels or percentage (e.g. '50%'). |\n| height | number/string | Height of the display object. Accepts pixels or percentage (e.g. '50%'). |\n| minWidth | number/string | Minimum width the object can shrink to. |\n| minHeight | number/string | Minimum height the object can shrink to. |\n| maxWidth | number/string | Maximum width the object can expand to. |\n| maxHeight | number/string | Maximum height the object can expand to. |\n| aspectRatio | number | Ratio between width and height (e.g. 1.5 for 3:2 ratio). |\n\n### Flex Layout\n\n| Property | Type | Description |\n|----------------|---------------------|-----------------------------------------------------------------------------|\n| flexDirection | string | Direction of flex items. Values: 'row', 'column', 'row-reverse', 'column-reverse'. |\n| flexWrap | string | Whether items wrap. Values: 'wrap', 'nowrap', 'wrap-reverse'. |\n| justifyContent | string | Alignment along main axis. Values: 'flex-start', 'flex-end', 'center', 'space-between', 'space-around'. |\n| alignItems | string | Alignment along cross axis. Values: 'flex-start', 'flex-end', 'center', 'stretch', 'baseline'. |\n| alignContent | string | Alignment of lines with multiple items. Values: 'flex-start', 'flex-end', 'center', 'stretch', 'space-between', 'space-around'. |\n| alignSelf | string | Override of parent's alignItems for specific item. |\n| flexGrow | number | Grow factor of item relative to other items. |\n| flexShrink | number | Shrink factor of item relative to other items. |\n| flexBasis | number/string | Initial size of item before flex growing/shrinking. |\n| gap | number/object | Gap between items. |\n| rowGap | number | Gap between rows. |\n| columnGap | number | Gap between columns. |\n\n### Positioning\n\n| Property | Type | Description |\n|----------------|---------------------|-----------------------------------------------------------------------------|\n| positionType | string | Type of positioning. Values: 'relative', 'absolute', 'static'. |\n| top | number/string | Distance from the top edge. |\n| right | number/string | Distance from the right edge. |\n| bottom | number/string | Distance from the bottom edge. |\n| left | number/string | Distance from the left edge. |\n\n### Spacing, Margins and Borders\n\n| Property | Type | Description |\n|----------------|---------------------|-----------------------------------------------------------------------------|\n| margin | number/array | Space outside border box. Can be single value or array for different sides. |\n| padding | number/array | Space inside border box. Can be single value or array for different sides. |\n| border | number/array | Border width. Can be single value or array for different sides. |\n\n### Object Fitting and Alignment\n\n| Property | Type | Description |\n|----------------|---------------------|-----------------------------------------------------------------------------|\n| objectFit | string | How object is resized to fit layout box. Values: 'contain', 'cover', 'fill', 'none', 'scale-down'. |\n| objectPosition | string | Anchor point of object inside layout box. E.g. 'center', 'top left'. |\n| transformOrigin| string | Pivot point for rotation and scaling of layout box. |\n\n## Shadow \n\n| Property | Type | Description |\n|----------------|---------------------|-----------------------------------------------------------------------------|\n| blur | number | Blur strength. |\n| color | number | Color of the shadow. |\n| offset | object | Offset of the shadow. |\n| quality | number | Quality of the shadow. |\n\n\n# Hook before destroy\n\n\n```html\n\n\n\n\n \n @if (bool) {\n \n }\n \n\n```" }, { "path": "docs/components/button.md", "content": "# Button\n\nThe Button component provides an interactive button with visual feedback for different states (normal, hover, pressed, disabled). It supports both sprite-based and graphics-based rendering approaches.\n\n## Basic Usage\n\n```html\n\n```\n\n### Button with Multiple Elements\n\n```html\n\n```\n\nWhen `children` are provided, they take priority over the `text` property.\n\n## Custom Background\n\nYou can provide a custom background component:\n\n```html\n\n\n\n\n```\n\n\n```\n\n## TypeScript Types\n\n```typescript\ninterface ButtonStyle {\n backgroundColor?: {\n normal?: string;\n hover?: string;\n pressed?: string;\n disabled?: string;\n };\n border?: {\n color?: string;\n width?: number;\n radius?: number;\n };\n text?: {\n color?: string;\n fontSize?: number;\n fontFamily?: string;\n };\n textures?: {\n normal?: string;\n hover?: string;\n pressed?: string;\n disabled?: string;\n };\n}\n\ninterface ButtonProps {\n text?: string;\n disabled?: boolean;\n click?: (event: FederatedPointerEvent) => void;\n hoverEnter?: (event: FederatedPointerEvent) => void;\n hoverLeave?: (event: FederatedPointerEvent) => void;\n pressDown?: (event: FederatedPointerEvent) => void;\n pressUp?: (event: FederatedPointerEvent) => void;\n style?: ButtonStyle;\n width?: number;\n height?: number;\n x?: number;\n y?: number;\n alpha?: number;\n visible?: boolean;\n cursor?: string;\n controls?: ControlsDirective | JoystickControls;\n controlName?: string;\n shape?: 'rect' | 'circle' | 'ellipse';\n background?: Element | ComponentFunction;\n children?: Element[];\n}\n``` " }, { "path": "docs/components/canvas.md", "content": "# Use Canvas component\n\nIt's the starting point for all the other components.\n\nCommon example:\n\n```html\n\n \n\n```\n\n### options\n\nYou can use all properties from [PixiJS Canvas Renderer](https://pixijs.download/release/docs/rendering.html#autoDetectRenderer)" }, { "path": "docs/components/container.md", "content": "# Use Container component\n\nCommon example:\n\n```html\n\n```\n\nExample with x and y:\n\n```html\n\n\n\n```\n\n" }, { "path": "docs/components/dom-container.md", "content": "# DOMContainer Component\n\nThe `DOMContainer` component provides a bridge between the canvas rendering system and traditional DOM manipulation. It allows you to render standard DOM elements within your canvas application while maintaining proper transform hierarchy and visibility.\n\nThis component is especially useful for rendering form elements like ``, `