@coolms/image-editor-angular 2.0.0-alpha.2 → 2.0.0-alpha.4

package/ATTRIBUTION.md

@@ -0,0 +1,43 @@
+# Attribution
+
+`@coolms/image-editor-angular` builds on one open-source canvas
+library. This file acknowledges it and records the license under
+which it is used. The entry is MIT-compatible with CoolMS's own
+MIT license.
+
+## fabric.js
+
+- **Project**: `fabric`
+- **Version**: `^6.9.1` (peer dependency)
+- **Copyright**: Printio (Juriy Zaytsev, Maxim Chernyak) and the
+  fabric.js contributors
+- **License**: MIT
+- **Repository**: https://github.com/fabricjs/fabric.js
+- **Role**: Provides the canvas rendering surface (`Canvas`), the
+  image object (`FabricImage`), interactive corner / rotation
+  controls, and the filter pipeline (WebGL primary, Canvas2D
+  fallback) wrapped by `FabricEngineAdapter`. Imported via
+  `from 'fabric/es'` for tree-shaking.
+- **Notes**: zero runtime dependencies, ESM-first, Promise-based
+  image loading, ships its own TypeScript types.
+
+## Why this file exists
+
+Even though every dependency is MIT and CoolMS itself ships under
+MIT, the project policy is to track each transitive vendor surfaced
+through public-facing packages. When `@coolms/image-editor` is
+consumed by downstream CoolMS deployments, this file documents the
+upstream chain without forcing operators to crawl `node_modules` to
+assemble it.
+
+## History
+
+Prior to (May 3-4, 2026) this package wrapped Toast UI
+Image Editor in headless mode. Toast UI in turn embedded fabric.js
+v4. replaced the Toast UI layer with a direct
+`FabricEngineAdapter` against fabric.js v6, and removed the
+`tui-image-editor`, `tui-color-picker`, and `tui-code-snippet`
+dependencies. See `docs/adr/079-toast-ui-rejection.md` for the
+rationale and `docs/adr/081-image-editor-engine-swap.md` for the
+journey. Toast UI Image Editor was MIT-licensed (NHN Cloud Corp,
+https://github.com/nhn/tui.image-editor).

package/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+All notable changes to `@coolms/image-editor-angular` are recorded here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+This file starts at the version named below, which is what the registry
+currently serves. Earlier alphas are deliberately not reconstructed: entries are written
+in the same commit as the work they describe, and inventing the ones that
+predate this file would be a worse record than not having them.
+
+## 2.0.0-alpha.4 -- 2026-10-22
+
+### Added
+
+- **A tool rail on the left and a properties panel on the right.** The rail
+  draws the tools in their groups (Transform, Insert, Filters, Layers), with
+  their names or as icons whose names and shortcuts are tooltips; the
+  person switches at its foot, and the host remembers the choice through
+  `IMAGE_EDITOR_RAIL_MODE` (for this page load when it provides none). The
+  active tool is always scrolled into view. The panel shows the active
+  tool's properties under its name, or, with no tool, the image's own: its
+  size, its format and how many layers it has.
+- **Each tool has a shortcut**: C crop, R rotate, F flip, I resize, M mask,
+  U shapes, T text, L layers. A tool's key selects it and, when it is the
+  active one, closes it; only while the editor has the keyboard, never from a
+  field, and never with Ctrl, Alt or Meta.
+- **The editor's text goes through keys.** `IMAGE_EDITOR_TRANSLATOR` answers
+  them; without a host translator the base catalogue's English does
+  (`IMAGE_EDITOR_MESSAGES`), and `catalogueTranslator()` puts a host's
+  catalogue in front of it, never showing a key or an empty label for a
+  message it lacks or holds blank.
+- **`src/core/` holds the tools and the text as data, with no framework**, so
+  a React host uses them as they are; a lint rule refuses any import there
+  from outside it, and any package at all.
+- Delete acts on the editor's own selection: it removes the selected shape or
+  text layer, and does nothing when nothing, or the base image, is selected.
+  It is bound to the editor's own layer through the keyboard scope, so it never
+  reaches a page beneath the editor. Needs `@coolms/ui-angular` 2.0.0-alpha.4.
+- A save names the version it opened (`If-Match`): when the image changed
+  meanwhile (412) or was deleted (404), the editor says so and offers Save as,
+  never writing over the newer file or making the deleted one again; a change
+  made elsewhere is said at once, through the host's `VFS_NODE_WATCH`. Needs
+  `@coolms/ui-angular` with `VFS_NODE_WATCH`.
+- Declares `bugs` so a page imported from this package, and the catalogue,
+  know where a correction is filed. The registry filled the gap from GitHub when
+  the manifest was silent; the declared field is the one that holds on any
+  registry.
+
+### Changed
+
+- **Breaking: `engines.node` names exactly the Node lines CI runs.** It moves from
+  `^22.22.3 || ^24.15.0 || >=26` to `^22.22.3 || ^24.15.0 || ^26.0.0`: Node 27
+  and later are not declared until CI runs them. Within each line the floor is
+  the highest one any package in the lockfile declares. CI checks both, from
+  the matrix and the lockfile. The published code does not change.
+
+- The right sidebar is gone: tools are picked on the rail and their properties
+  shown in the panel. A tool registers a name key, a group, an order and a
+  shortcut instead of a label and a category.
+- The version an overwrite names is the version of the pixels the editor
+  opened: the host reads the file's bytes and takes their version from the
+  same response (its `ETag`). The listing's version, a separate and earlier
+  read, is no longer part of the VFS host data (`node.version` is removed). A
+  file changed between the listing and the open is edited as it is now, and
+  bytes served from a cache name their own older version, so saving them over
+  the newer file is refused. A read that names no version leaves Save off;
+  Save as still works.
+- The same for a media asset: given `asset.sourceUrl`, the host reads the
+  asset's bytes and their version from one response, and the replace names
+  that version (`If-Match`, which the replace now requires). An asset replaced
+  meanwhile (412) or deleted (404) is not overwritten: the editor says so and
+  offers Save as. Without `sourceUrl` the image is shown from `originalUrl`,
+  which names no version, and Save is off.
+
+## 2.0.0-alpha.3 -- 2026-09-03
+
+**A pre-release, carrying no compatibility promise.** Published under the
+`alpha` dist-tag.
+
+The image editor: a fabric.js v6 engine behind a framework-agnostic adapter,
+with transform tools (crop, rotate, flip, resize), seven filters, insert tools
+(shapes, text, mask), a layers panel over the object stack, and a save flow
+wired to the Media Library and the VFS.
+
+The adapter is the reason the engine could be replaced without touching the UI
+shell or any tool component, and it is why the editor loads as its own lazy
+chunk.
+
+### Fixed
+
+- **Save overwrites only a PNG or a JPEG.** Save wrote JPEG bytes over every
+  source that was not a PNG: an SVG's vectors became pixels, a GIF lost its
+  animation, and the file's name and type no longer said what it held. Save
+  now overwrites only a PNG or a JPEG, which the editor writes back in the
+  same format; every other format -- GIF, SVG, TIFF, HEIC, BMP, and WebP until
+  its export is verified in every supported browser -- has Save as only, and
+  the Save button says why. A JPEG whose edit gained transparent areas is not
+  written over as PNG under its name: Save says so and opens Save as.
+  `writtenBackAs(mimeType)` names the format Save writes a source back as.
+- **A photo is saved upright.** Its EXIF orientation is applied when the
+  editor opens it, so the saved pixels are turned upright themselves. The
+  export carries no EXIF of its own; a JPEG export embeds an sRGB colour
+  profile, a PNG export none. The canvas the editor draws on is sRGB: a
+  Display P3 photo saved as JPEG loses its own profile, and its colours
+  beyond sRGB are clipped (measured, not yet changed). On a JPEG overwrite, a CoolMS backend that
+  carries the replaced photo's EXIF into the new file keeps the camera, the
+  dates and the location, sets the orientation to normal and removes the stale
+  embedded thumbnail. The location is kept: removing it is an action of its
+  own, never a side effect of a save.
+- The Shapes tool had no icon. Its class named an icon Bootstrap Icons does not
+  define, which renders nothing and reports nothing -- measured, it behaved
+  identically to a class invented at random.
+- The roadmap listed Shapes as planned when it ships, and the feature list
+  omitted the insert tools entirely.
+- The licence section pointed at `ATTRIBUTION.md`, which the package did not
+  copy into the tarball. The file now ships.
+- The package described itself as being for "CoolMS DXP", which is not what the
+  platform is called, and claimed the package was framework-agnostic when it is
+  the engine adapter behind it that is.

package/README.md

@@ -1,12 +1,16 @@
 # @coolms/image-editor-angular
 
-Modern image editor for CoolMS DXP. Built on fabric.js v6 via a
+Modern image editor for CoolMS. Built on fabric.js v6 via a
 custom `FabricEngineAdapter`, wrapped by a CoolMS-native UI shell.
 
+## Tests
+
+This package has no test runner of its own, so CI finds no tests in it: only typecheck, lint and build guard it here, and a check of "the same number of tests before and after" proves nothing for it. Its 10 spec files run in the admin suite of [coolms/theme-admin](https://github.com/coolms/theme-admin), which compiles this package from source. A change here is tested there, not by this repository's CI.
+
 ## Status
 
 **Feature-complete on the fabric.js v6 engine.** The shell
-(top toolbar, canvas mount, right sidebar, properties panel) drives
+(top toolbar, tool rail, canvas mount, properties panel) drives
 all editing operations through the engine API. The save flow is
 integrated end-to-end with the Media Library and the VFS file
 manager: open an image asset (or any VFS image file), edit, Save
@@ -54,6 +58,16 @@ Slider filters live-preview during drag with a coalesced
 preview session. `clearRedoStack()` on commit prevents stale preview
 entries from leaking into the redo stack.
 
+**Insert** (3 tools):
+- **Shapes** — rectangle, ellipse, triangle, line and arrow, each
+  added as its own fabric object with solid, linear-gradient or
+  radial-gradient fill, stroke width and colour
+- **Text** — editable text layers with font, size, weight and colour
+- **Mask** — shape masks applied to the image
+
+**Layers** — the object stack for everything Insert adds: select,
+reorder, and remove without disturbing the underlying image.
+
 ### Top toolbar
 
 - **Undo** / **Redo** — bound to engine history events. The custom
@@ -125,11 +139,18 @@ Three layers, separated for swappability:
                   (interface)             (this package)             (npm peer dep)
 ```
 
-1. **UI shell** — `<coolms-image-editor>` host component with three
-   panes (top toolbar, canvas mount, right sidebar). Tools register
-   themselves into a `ToolRegistryService`; the right sidebar uses
-   `NgComponentOutlet` with `inputs` to render the active tool's
-   properties panel.
+1. **UI shell** — `<coolms-image-editor>` host component: a top
+   toolbar, then the tool rail on the left, the canvas mount, and the
+   properties panel on the right. Tools register themselves into a
+   `ToolRegistryService` with a definition from `src/core/` (name key,
+   icon, group, order, shortcut) and the component that shows their
+   properties; the panel uses `NgComponentOutlet` with `inputs` to
+   render the active tool's, or the image's own when no tool is
+   active. The rail draws the tools with their names or as icons;
+   the host remembers which (`IMAGE_EDITOR_RAIL_MODE`). The editor's
+   text goes through `IMAGE_EDITOR_TRANSLATOR`, which falls back to
+   the base catalogue (`IMAGE_EDITOR_MESSAGES`). `src/core/` imports
+   no framework, so a React host uses the same tools and text.
 2. **Engine adapter** — `FabricEngineAdapter` implements
    `ImageEditorEngine`. Owns canvas dimensions (no vendor CSS
    auto-fit layer), normalises the public API (lowercase filter
@@ -311,7 +332,7 @@ Two intentionally hard-coded values exist:
 
 ## Performance
 
-Measured on Chrome for Windows (, NVIDIA GTX
+Measured on Chrome for Windows (NVIDIA GTX
 1650 via ANGLE D3D11, `WebGLFilterBackend` confirmed,
 `MAX_TEXTURE_SIZE=16384`):
 
@@ -356,7 +377,8 @@ fraction of that — most is Angular CD + paint.
 
 ### Done
 
-- Headless mount, engine adapter, UI shell, 11 tools, theming, save flow
+- Headless mount, engine adapter, UI shell, the transform and filter tools,
+  theming, save flow
 - `FabricEngineAdapter` rewrite (~640 LOC) and the state-service switch
 - Canvas-space crop (bake-and-replace), Sharpen `textureSize` fix, blob-URL undo
 - Bidirectional sync (`imageTransformed` event), live-bound rotate slider,
@@ -364,10 +386,12 @@ fraction of that — most is Angular CD + paint.
 - Canvas frame overlay
 - Toast UI dependency removed (640 LOC adapter deleted)
 - Bundle, memory and functional verification
+- Insert tools — Shapes, Text and Mask — with a Layers panel over the
+  object stack
 
 ### Planned
 
-- Shapes (Free Draw, Rectangle, Circle, Text, Icons, Mask)
+- Free-draw brush and an icon library for the Shapes tool
 - Color picker / eyedropper
 - WebP / AVIF export options
 - Rich-text inline widget integration
@@ -385,7 +409,7 @@ fraction of that — most is Angular CD + paint.
   consumer-defined tools
 - **Video editor companion** sharing the engine-adapter pattern
 
-## License
+## Licence
 
-MIT (CoolMS DXP). The runtime peer dependency `fabric` is also MIT.
+MIT. The runtime peer dependency `fabric` is also MIT.
 See `ATTRIBUTION.md` for the full vendor acknowledgement chain.