customforge 0.1.0-alpha.0 → 0.1.0-alpha.2

package/README.md

@@ -1,23 +1,28 @@
-<div align="center">
-
-# CustomForge
-
-**Turn a 2D texture canvas into a live 3D product preview**
-
-A lightweight, framework-agnostic prototype for building browser-based product customization experiences with Fabric.js and Three.js
-
-<p>
-  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white">
-  <img alt="Vite" src="https://img.shields.io/badge/Vite-8-646CFF?logo=vite&logoColor=white">
-  <img alt="Three.js" src="https://img.shields.io/badge/Three.js-r185-111111?logo=threedotjs&logoColor=white">
-  <img alt="Fabric.js" src="https://img.shields.io/badge/Fabric.js-7-DB4D6D">
-  <img alt="License" src="https://img.shields.io/badge/License-Apache%202.0-2F6F9F">
-</p>
-
-<p>
-  <strong>English</strong> |
-  <a href="./README.zh-CN.md">中文简体</a>
-</p>
+<div align="center">
+
+<img src="./src/workbench/assets/CustomForgeLogo.png" alt="CustomForge Logo" width="136">
+
+<h1>CustomForge</h1>
+
+<hr>
+
+<p><strong>Turn a 2D texture canvas into a live 3D product preview</strong></p>
+
+<p>A lightweight, framework-agnostic toolkit for building browser-based product customization experiences with Fabric.js and Three.js</p>
+
+<p>
+  <strong>English</strong>
+  <span> · </span>
+  <a href="./README.zh-CN.md">简体中文</a>
+</p>
+
+<p>
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-2563EB?style=flat-square&logo=typescript&logoColor=white&labelColor=1F2937">
+  <img alt="Vite" src="https://img.shields.io/badge/Vite-8-7C3AED?style=flat-square&logo=vite&logoColor=white&labelColor=1F2937">
+  <img alt="Three.js" src="https://img.shields.io/badge/Three.js-r185-27272A?style=flat-square&logo=threedotjs&logoColor=white&labelColor=1F2937">
+  <img alt="Fabric.js" src="https://img.shields.io/badge/Fabric.js-7-BE185D?style=flat-square&labelColor=1F2937">
+  <img alt="License" src="https://img.shields.io/badge/License-Apache%202.0-0F766E?style=flat-square&logo=apache&logoColor=white&labelColor=1F2937">
+</p>
 
 </div>
 
@@ -32,15 +37,19 @@ CustomForge connects a familiar 2D design surface to a UV-mapped 3D model:
 - Preview every canvas change on a 3D product in real time
 - Load remote GLB/GLTF models and optional base textures
 - Select the customizable surface by mesh name
-- Rotate and zoom the 3D preview with OrbitControls
-- Export the composed texture as a PNG
-- Save and restore editable objects through versioned Design JSON
+- Rotate and zoom the 3D preview with OrbitControls
+- Export the composed texture as a PNG
+- Save and restore editable objects through versioned Design JSON
+- Organize objects through names, visibility, locking, and layer order
+- Undo and redo design changes through snapshot history
+- Use configurable typography, background, and decorative asset Dialogs
+- Adapt the default Workbench with branding, labels, theme tokens, and icons
 
 The included workbench starts with a procedural cup, so the project works immediately without external assets
 
-## Repository Development
-
-Requirements: Node.js 22+ and pnpm 11+
+## Repository Development
+
+Requirements: Node.js 22+ and pnpm 11+
 
 ```bash
 pnpm install
@@ -49,43 +58,59 @@ pnpm dev
 
 Open the URL printed by Vite
 
-The built-in demo appears with a UV workspace on the left and a live 3D preview on the right
-
-## npm Alpha Package
-
-CustomForge is prepared for public alpha releases under the `alpha` dist-tag. The API and Design JSON Schema may change between alpha versions
-
-After the first release is published, install the current alpha and its peer dependencies with:
-
-```powershell
-pnpm add customforge@alpha
-pnpm add fabric three
-```
-
-For repository-independent verification before publishing, build and create the local package from the repository root:
-
-```powershell
-pnpm pack:local
-```
-
-The command builds JavaScript, TypeScript declarations, and core styles, checks the npm file list, and creates:
-
-```text
-customforge-0.1.0-alpha.0.tgz
-```
-
-Install that local package and its peer dependencies in an independent Vite TypeScript project:
-
-```powershell
-pnpm add D:\project\CustomForge\CustomForge\customforge-0.1.0-alpha.0.tgz
-pnpm add fabric three
-```
-
-The checked-in `examples/npm-consumer` project imports CustomForge only through this `.tgz`. Run `pnpm install --ignore-workspace` in that directory so pnpm installs it independently from the parent workspace
+The built-in demo appears with a UV workspace on the left and a live 3D preview on the right
+
+## npm Alpha Package
+
+CustomForge is available from the npm Registry under the `alpha` dist-tag and the API and Design JSON Schema may change between alpha versions
+
+Install the current public alpha with:
+
+```powershell
+pnpm add customforge@alpha
+```
+
+Fabric.js and Three.js are installed automatically as transitive dependencies
+
+pnpm may report that the optional native `canvas` build script was ignored
+
+CustomForge runs in the browser and does not use Node native canvas, so `pnpm approve-builds` is not required
+
+Consumer projects can explicitly acknowledge this browser-only choice in `package.json`:
+
+```json
+{
+  "pnpm": {
+    "ignoredBuiltDependencies": ["canvas"]
+  }
+}
+```
+
+Package page: [npmjs.com/package/customforge](https://www.npmjs.com/package/customforge)
+
+For repository-independent verification before publishing, build and create the local package from the repository root:
+
+```powershell
+pnpm pack:local
+```
+
+The command builds JavaScript, TypeScript declarations, and public styles, checks the npm file list, and creates:
+
+```text
+customforge-0.1.0-alpha.2.tgz
+```
+
+Install that local package in an independent Vite TypeScript project:
+
+```powershell
+pnpm add D:\projects\3DRendering\core_code\customforge-0.1.0-alpha.2.tgz
+```
+
+The checked-in `examples/npm-consumer` project imports CustomForge only through this `.tgz`. Run `pnpm install --ignore-workspace` in that directory so pnpm installs it independently from the parent workspace
 
 ## Load Your Product
 
-Choose **Load remote** in the demo and provide:
+Choose **Load product** in the demo and provide:
 
 | Field | Purpose |
 | --- | --- |
@@ -103,22 +128,22 @@ The optional texture image is the visual base layer, not a replacement for model
 >
 > A blocked or canvas-tainting resource may fail to load and can prevent PNG export
 
-## Basic Usage
-
-The framework-independent Library entry can be mounted into any two DOM containers:
-
-CustomForge is browser-only and must be initialized after its DOM containers are available
-
-The editor and viewer require two different containers; call `destroy()` when the page, host component, or instance is no longer in use to release Fabric, WebGL, observer, and event resources
+## Basic Usage
+
+The framework-independent Library entry can be mounted into any two DOM containers:
+
+CustomForge is browser-only and must be initialized after its DOM containers are available
+
+The editor and viewer require two different containers; call `destroy()` when the page, host component, or instance is no longer in use to release Fabric, WebGL, observer, and event resources
 
 ```html
 <div id="texture-editor"></div>
 <div id="product-viewer"></div>
 ```
 
-```ts
-import { createCustomizer } from 'customforge'
-import 'customforge/style.css'
+```ts
+import { createCustomizer } from 'customforge'
+import 'customforge/style.css'
 
 const customizer = await createCustomizer({
   editor: '#texture-editor',
@@ -141,64 +166,222 @@ customizer.addText({
   color: '#172126',
 })
 
-await customizer.addImage({
-  src: 'https://example.com/logo.png',
-  x: 720,
-  y: 240,
-  width: 220,
-})
-
-window.addEventListener('beforeunload', () => customizer.destroy(), {
-  once: true,
-})
-```
-
-The public package uses the same root and style imports as the local `.tgz`; pin an exact alpha version when reproducible installs are required
-
-## Design JSON
-
-`saveDesign()` returns a Library-owned, JSON-safe document instead of exposing Fabric.js serialization. `loadDesign()` validates unknown input and restores the editable object stack asynchronously:
-
-```ts
-const design = customizer.saveDesign()
-localStorage.setItem('customforge-design', JSON.stringify(design))
-
-const savedDesign = localStorage.getItem('customforge-design')
-if (savedDesign) {
-  await customizer.loadDesign(JSON.parse(savedDesign))
-}
-```
-
-The current Schema version is `1`. It stores the logical canvas size and the text and image objects in back-to-front render order, including stable object IDs and center-based transforms
-
-Design JSON intentionally excludes the product model, target mesh, and base texture. A document can only be loaded into an editor with exactly the same logical width and height
-
-Loading is transactional: the current design remains unchanged unless the document validates and every referenced image loads successfully. Blob URL images are converted to Data URLs when added; remote image URLs remain URLs and must continue to satisfy browser CORS requirements when restored
-
-The Schema is still an alpha contract and may change in later alpha versions
-
-## Instance API
+await customizer.addImage({
+  src: 'https://example.com/logo.png',
+  x: 720,
+  y: 240,
+  width: 220,
+})
+
+window.addEventListener('beforeunload', () => customizer.destroy(), {
+  once: true,
+})
+```
+
+The public package uses the same root and style imports as the local `.tgz`; pin an exact alpha version when reproducible installs are required
+
+## Ready-made Workbench
+
+Use the optional Workbench entry when a complete default interface is preferable to building controls from scratch
+
+The host element must have an explicit height so the design surface, layers, and 3D preview can measure their available space
+
+```html
+<div id="customforge-workbench" style="height: 720px"></div>
+```
+
+```ts
+import { createWorkbench } from 'customforge/workbench'
+import 'customforge/style.css'
+
+const workbench = await createWorkbench({
+  container: '#customforge-workbench',
+  product: {
+    modelUrl: 'https://example.com/product.glb',
+    surfaceMesh: 'PrintArea',
+  },
+  features: {
+    presetBackgrounds: true,
+    presetElements: true,
+  },
+  layout: {
+    header: true,
+    layers: true,
+  },
+  branding: {
+    logoUrl: '/brand/logo.png',
+    title: 'Studio',
+    subtitle: 'Product personalization',
+  },
+  labels: {
+    addText: 'Typography',
+    addImage: 'Artwork',
+  },
+  theme: {
+    accent: '#0057b8',
+    accentHover: '#003f87',
+    accentContrast: '#ffffff',
+  },
+  assets: {
+    backgrounds: [
+      { id: 'floral', name: 'Floral', url: '/presets/floral.png' },
+    ],
+    elements: [
+      { id: 'flower', name: 'Flower', url: '/presets/flower.png' },
+    ],
+  },
+})
+```
+
+The bundled CustomForge logo is used by default and can be replaced or hidden through `branding`
+
+`labels` replaces visible Workbench copy, `theme` maps to scoped CSS variables, and `icons` can disable built-in icons or replace individual semantic icons with image URLs
+
+The default UI font stack prefers the rounded `Nunito Sans` family and falls back to system sans-serif fonts
+
+CustomForge bundles the font asset and does not fetch third-party font services at runtime
+
+Text and image commands open focused Dialogs instead of immediately mutating the canvas
+
+- The text Dialog includes an input, color control, and replaceable typography presets
+- The image Dialog includes local upload, background presets, and decorative element presets
+- A design background replaces the previous design background, fills the canvas, starts locked at the bottom layer, and persists in Design JSON
+
+Feature and layout switches can also be changed after initialization
+
+```ts
+workbench.setFeature('addText', true)
+workbench.setLayout('header', true)
+```
+
+| Feature switch | Controls |
+| --- | --- |
+| `addText`, `addImage`, `deleteSelection` | Object Dialogs and deletion |
+| `undoRedo` | Undo and redo buttons plus Workbench keyboard shortcuts |
+| `saveDesign`, `loadDesign` | Design JSON actions |
+| `loadRemoteProduct`, `exportTexture`, `resetView` | Product and output actions |
+| `reorderObjects`, `toggleObjectVisibility`, `lockObjects`, `renameObjects` | Layer management |
+| `presetBackgrounds`, `presetElements` | Image Dialog preset tabs |
+
+| Layout switch | Region |
+| --- | --- |
+| `header` | Brand and global product actions |
+| `editorHeader`, `viewerHeader` | Workspace panel headings |
+| `toolbar` | Design tool controls |
+| `layers` | Object layer panel |
+| `status` | Runtime status and object count |
+
+All feature and layout values default to `true`
+
+Feature switches only control the built-in Workbench controls and do not remove methods from `workbench.customizer`
+
+Theme values are intended for coherent product-level styling rather than per-button color configuration
+
+```ts
+const workbench = await createWorkbench({
+  container: '#customforge-workbench',
+  icons: {
+    enabled: true,
+    sources: {
+      addText: '/icons/typography.svg',
+      exportTexture: null,
+    },
+  },
+  textPresets: [
+    {
+      id: 'brand-display',
+      name: 'Brand display',
+      fontFamily: 'Arial',
+      fontSize: 72,
+      width: 460,
+      color: '#17191c',
+    },
+  ],
+})
+```
+
+## Design JSON
+
+`saveDesign()` returns a Library-owned, JSON-safe document instead of exposing Fabric.js serialization. `loadDesign()` validates unknown input and restores the editable object stack asynchronously:
+
+```ts
+const design = customizer.saveDesign()
+localStorage.setItem('customforge-design', JSON.stringify(design))
+
+const savedDesign = localStorage.getItem('customforge-design')
+if (savedDesign) {
+  await customizer.loadDesign(JSON.parse(savedDesign))
+}
+```
+
+The current Schema version is `1`. It stores the logical canvas size and the text and image objects in back-to-front render order, including stable object IDs, names, visibility, locking, image roles, and center-based transforms
+
+Design JSON intentionally excludes the product model, target mesh, and base texture. A document can only be loaded into an editor with exactly the same logical width and height
+
+An image with `role: 'background'` is a design object rather than the product base texture. Only one is allowed, it must be the first object, and older version 1 documents without `role` continue to load as ordinary image elements
+
+Loading is transactional: the current design remains unchanged unless the document validates and every referenced image loads successfully. Blob URL images are converted to Data URLs when added; remote image URLs remain URLs and must continue to satisfy browser CORS requirements when restored
+
+The Schema is still an alpha contract and may change in later alpha versions
+
+## Undo and Redo
+
+History is enabled in both the headless core and Workbench and defaults to 50 undo steps
+
+Set `historyLimit` in `createCustomizer` or `createWorkbench` options to change the retained undo depth
+
+```ts
+if (customizer.canUndo()) {
+  await customizer.undo()
+}
+
+await customizer.redo()
+customizer.clearHistory()
+
+const stop = customizer.on('historychange', ({ canUndo, canRedo }) => {
+  console.log({ canUndo, canRedo })
+})
+```
+
+History covers object creation, deletion, canvas transforms, text edits, layer order, names, visibility, locking, and Design JSON loading
+
+Workbench also supports `Ctrl` or `Cmd` + `Z`, `Ctrl` or `Cmd` + `Shift` + `Z`, and `Ctrl` + `Y` while focus is outside form fields
+
+Successful product replacement keeps the current design but starts a new history baseline
+
+## Instance API
 
 | Method | Description |
 | --- | --- |
-| `addText(options)` | Add and select editable text, constrained to the canvas |
-| `addImage(options)` | Load and select an image, constrained to the canvas |
-| `deleteSelected()` | Remove the active object or selection |
-| `saveDesign()` | Return the current versioned Design JSON document |
-| `loadDesign(value)` | Validate and transactionally restore Design JSON |
-| `loadProduct(product)` | Replace the model, base texture, and target mesh |
+| `addText(options)` | Add and select editable text, constrained to the canvas |
+| `addImage(options)` | Load and select an element or replace the design background |
+| `getObjects()` | Return the current objects in back-to-front layer order |
+| `getSelectedObjectIds()` | Return stable IDs for the current selection |
+| `selectObject(id)` | Select a visible object by stable ID |
+| `removeObject(id)` | Remove an object by stable ID |
+| `moveObject(id, index)` | Move an object to a zero-based layer index |
+| `renameObject(id, name)` | Change the object name shown in layer tools |
+| `setObjectVisibility(id, visible)` | Include or exclude an object from rendering |
+| `setObjectLocked(id, locked)` | Lock or unlock canvas transformations |
+| `deleteSelected()` | Remove the active object or selection |
+| `saveDesign()` | Return the current versioned Design JSON document |
+| `loadDesign(value)` | Validate and transactionally restore Design JSON |
+| `canUndo()`, `canRedo()` | Query the current history directions |
+| `undo()`, `redo()` | Restore the previous or next design snapshot |
+| `clearHistory()` | Make the current design the new history baseline |
+| `loadProduct(product)` | Replace the model, base texture, and target mesh |
 | `exportTexture(filename?)` | Download the composed texture as PNG |
 | `resetView()` | Restore the default 3D camera position |
 | `on(event, listener)` | Subscribe to instance events; returns an unsubscribe function |
 | `destroy()` | Release DOM events, Fabric state, and WebGL resources |
 
-Available events are `ready`, `change`, `selectionchange`, `status`, and `error`
-
-The initial alpha stability boundary is limited to the methods above, `createCustomizer`, `ProductCustomizer`, and the configuration, event, and Design JSON types exported from the package root
-
-`ProductCustomizer` does not expose its Fabric.js editor or Three.js viewer instances; consumers interact through the facade API
-
-Imports from `core`, `editor`, `viewer`, `bridge`, or any other undeclared package subpath are unsupported
+Available events are `ready`, `change`, `selectionchange`, `historychange`, `status`, and `error`
+
+The initial alpha stability boundary is limited to the methods above, `createCustomizer`, `ProductCustomizer`, the `customforge/workbench` entry, and the configuration, event, Workbench, and Design JSON types exported from declared package entries
+
+`ProductCustomizer` does not expose its Fabric.js editor or Three.js viewer instances; consumers interact through the facade API
+
+Imports from `core`, `editor`, `viewer`, `bridge`, or any other undeclared package subpath are unsupported
 
 ## Architecture
 
@@ -223,7 +406,7 @@ ProductCustomizer
 
 `ProductCustomizer` coordinates the modules while keeping Fabric.js and Three.js details behind a small instance API
 
-The demo UI uses Vanilla TypeScript; the core does not depend on Vue, React, or another UI framework
+The optional Workbench and demo use Vanilla TypeScript; the core does not depend on Vue, React, or another UI framework
 
 ## Model Contract
 
@@ -240,36 +423,37 @@ The built-in demo follows the same `PrintArea` mesh convention
 ## Project Structure
 
 ```text
-src/
-|-- bridge/           Canvas and Three.js texture synchronization
-|-- core/             Public types, configuration, and DOM helpers
-|-- customizer/       Public instance orchestration
-|-- demo/             Runnable workbench UI
-|-- editor/           Fabric.js design surface
-|-- style.css         Public Library style entry
-|-- styles/           Library core styles
-|-- viewer/           Three.js product preview
-`-- index.ts          Framework-independent source entry
-
-examples/
-`-- npm-consumer/     Independent local .tgz consumer
-
-scripts/
-`-- verify-package.mjs  npm file and artifact boundary checks
-```
+src/
+|-- bridge/           Canvas and Three.js texture synchronization
+|-- core/             Public types, configuration, and DOM helpers
+|-- customizer/       Public instance orchestration
+|-- demo/             Runnable workbench UI
+|-- editor/           Fabric.js design surface and snapshot history
+|-- style.css         Public Library style entry
+|-- styles/           Core and Workbench styles
+|-- viewer/           Three.js product preview
+|-- workbench/        Configurable UI, Dialogs, icons, and preset assets
+`-- index.ts          Framework-independent source entry
+
+examples/
+`-- npm-consumer/     Independent local .tgz consumer
+
+scripts/
+`-- verify-package.mjs  npm file and artifact boundary checks
+```
 
 ## Development Commands
 
 ```bash
-pnpm check       # TypeScript project check
-pnpm test        # Unit tests
-pnpm build       # Type-check and production build
-pnpm build:lib   # Build ESM, declarations, and core styles
-pnpm verify:package # Check dist and the npm file list
-pnpm pack:local  # Build, verify, and create the local .tgz
-pnpm release:check # Run checks, tests, package build, verification, and local pack
-pnpm preview     # Preview the production build
-```
+pnpm check       # TypeScript project check
+pnpm test        # Unit tests
+pnpm build       # Type-check and production build
+pnpm build:lib   # Build core and Workbench ESM, declarations, and styles
+pnpm verify:package # Check dist and the npm file list
+pnpm pack:local  # Build, verify, and create the local .tgz
+pnpm release:check # Run checks, tests, package build, verification, and local pack
+pnpm preview     # Preview the production build
+```
 
 ## Current Scope
 
@@ -277,16 +461,17 @@ This is an early technical prototype
 
 The public API and design document format are not stable yet
 
-The current milestone intentionally focuses on one texture and one customizable mesh
-
-Public npm releases use the `alpha` dist-tag until the API and Design JSON contract are ready for a more stable channel
-
-Multi-surface products, undo/redo, and framework adapters are not implemented yet. Undo/redo is the next planned milestone and will build on the Design JSON snapshot contract
+The current milestone intentionally focuses on one texture and one customizable mesh
+
+Public npm releases use the `alpha` dist-tag until the API and Design JSON contract are ready for a more stable channel
+
+Multi-surface products, advanced alignment tools, and framework adapters are not implemented yet
 
 ## Technology
 
 - [Fabric.js](https://fabricjs.com/) for the 2D editing surface
 - [Three.js](https://threejs.org/) for model loading and real-time 3D rendering
+- [Lucide](https://lucide.dev/) for bundled Workbench controls
 - [Vite](https://vite.dev/) for development and application builds
 - [TypeScript](https://www.typescriptlang.org/) with strict checking enabled
 
@@ -297,3 +482,5 @@ CustomForge is licensed under the Apache License 2.0
 See [LICENSE](./LICENSE) for the full license terms
 
 Third-party dependencies and assets remain subject to their respective licenses
+
+The bundled Nunito Sans font is licensed under the SIL Open Font License 1.1, available in [NunitoSans-OFL.txt](./LICENSES/NunitoSans-OFL.txt)