@rocketium/auto-adapt

Layout adaptation engine for auto-sizing canvas elements across different dimensions. Ports the proven frontend auto-adapt algorithm to a reusable package for use in both client and server environments.

Overview

@rocketium/auto-adapt intelligently adapts canvas layouts from one size to another. Given a set of canvas elements (text, images, shapes, groups, SVGs) designed for one dimension, it produces a proportionally adapted layout for a target dimension while preserving alignment, edge-snapping, and visual hierarchy.

Key Features

• Closest-size matching -- finds the best reference size from available sizes using aspect-ratio + Euclidean distance scoring
• Smart skew detection -- decides whether to stretch (skew) or proportionally scale each element based on its canvas coverage
• Per-element-type adaptation -- specialized handling for text (font sizes, word styles, autofit), images (crop offsets, scale), shapes (SVG, rounded-rect, path), and groups (recursive child adaptation)
• Edge-aware positioning -- preserves alignment to canvas edges and centering
• Override system -- stores adapted layouts as per-size overrides on the original objects, keeping the base variant untouched

Installation

npm install @rocketium/auto-adapt

For local development (before publishing):

npm install ../auto-adapt

Peer Dependencies

Package	Version	Required
@types/fabric	^5.3.9	Optional (compile-time only)

The package uses @types/fabric for canvas element type definitions. If you're consuming typed APIs, ensure it's installed as a devDependency.

Quick Start

import { generateBaseLayoutForSize } from '@rocketium/auto-adapt';

const newCapsule = generateBaseLayoutForSize({
  originalCapsule,       // ServerCapsule with existing sizes and objects
  capsuleId: 'abc123',
  creativeId: null,      // null = auto-detect best reference size
  sizeId: 'new-size-id',
  sizeToGenerate: '300x250',
  sizeName: 'Medium Rectangle',
  sizeCategory: 'Display',
});

API Reference

generateBaseLayoutForSize(params)

Main entry point. Generates a complete adapted capsule for a target size.

Parameters:

Param	Type	Description
originalCapsule	ServerCapsule	Source capsule with canvas data, sizes, and objects
capsuleId	string	ID of the capsule being adapted
creativeId	string | null	Reference size ID to adapt from. Pass null to auto-detect the closest match
sizeId	string	ID for the new size entry
sizeToGenerate	string	Target dimensions as "WIDTHxHEIGHT" (e.g. "1080x1080")
sizeName	string?	Display name for the new size
sizeCategory	string?	Category label for the new size

Returns: ServerCapsule -- a deep copy of the original capsule with the new size added, objects adapted as overrides, and metadata updated.

---

getAdaptedObjectsJSON(params)

Core adaptation algorithm. Adapts a flat record of canvas elements from one size to another.

Parameters:

Param	Type	Description
adaptSize	string	Target dimensions ("WIDTHxHEIGHT")
objects	Record<string, CanvasElementJSON>	Source elements keyed by ID
closestSize	string	Reference dimensions ("WIDTHxHEIGHT")

Returns: Record<string, CanvasElementJSON> -- adapted elements.

---

findClosestSizeWithMatches(params)

Finds the closest matching size from a list, with match-quality scores.

Parameters:

Param	Type	Description
availableSizes	string[]	Array of dimension strings
adaptSize	string	Target dimension string

Returns: { closestSize: string; sortedMatches: Record<string, number> } -- best match and percentage scores for all sizes.

---

findBestReferenceSize(availableSizes, targetSize)

Finds the best reference size ID from a sizes record.

Parameters:

Param	Type	Description
availableSizes	Record<string, { width: number; height: number }>	Available sizes keyed by ID
targetSize	string	Target dimension string

Returns: string -- the key of the best matching size.

---

Utility Exports

Function	Description
resolveObjectsForSize(objects, sizeId)	Flatten overrides for a specific size into base objects
applyAdaptedAsOverrides(originals, adapted, sizeId)	Store adapted objects as overrides on originals
getNormalizedSizeValue(sizeValue)	Normalize named sizes ("square" -> "720x720")
getEuclideanDistanceBetweenSizes({ size1, size2 })	Distance between two size strings

Type Guard Exports

Function	Checks for
isTextJSON(object)	TextContainerJSON
isImageJSON(object)	ImageContainerJSON
isShapeJSON(object)	PathJSON | RoundedRectJSON | SvgJSON
isSVGContainerJSON(object)	SvgJSON
isRoundedRectJSON(object)	RoundedRectJSON
isGroupJSON(object)	GroupContainerJSON
isCreativeBoxJSON(object)	Creative box elements
isAudioJSON(object)	Audio elements

Algorithm

Size Matching

Uses a weighted scoring system combining:

• Aspect ratio similarity (90% weight) -- prefers sizes with matching proportions
• Euclidean distance (10% weight) -- tiebreaks with absolute dimension proximity

Element Adaptation

For each element, the algorithm decides between two paths:

1. Skew path -- stretches the element to fill proportionally. Used when:

   • Element covers >90% of the canvas area
   • Element spans the full width or full height of the canvas
   • Groups are excluded from skewing

2. Non-skew path -- proportionally scales while preserving position. Uses:

   • Edge alignment detection (snaps to nearest edge within 1px threshold)
   • Horizontal centering detection (area-based left/right balance)
   • Quadrant-based positioning for non-centered, non-edge-aligned elements

Per-Type Handling

Type	Special Handling
Text	Scales fontSize, wordStyle font sizes (px only), autoFitSizes, padding, wordSpacing
Image	Scales imageScale, imageLeft/imageTop offsets, cornerRadius
SVG	Same as image + colorMap passthrough
RoundedRect	Scales cornerRadius
Path/Shape	Scales scaleX/scaleY instead of width/height
Group	Recursively adapts all children with group-relative scaling
CreativeBox	Resized to target dimensions (canvas background)
Audio	Passed through unchanged

Project Structure

src/
├── index.ts               # Public API exports
├── adapter.ts             # Core adapt logic + entry function
├── constants.ts           # Thresholds and defaults
├── types/
│   ├── index.ts           # Type barrel exports
│   ├── canvas.ts          # Canvas element type definitions
│   └── capsule.ts         # ServerCapsule type
└── utils/
    ├── sizeMatching.ts    # Size comparison and closest-match algorithms
    ├── scaling.ts         # Element scaling, border, padding helpers
    └── typeGuards.ts      # Runtime type guards for canvas elements

Development

# Install dependencies
npm install

# Type check
npm run typecheck

# Build (CJS + ESM + .d.ts)
npm run build

# Lint
npm run lint

# Format
npm run format

For local linking: npm install ../auto-adapt from a consumer project.

Publishing

Publishing uses the Rocketium org account. Personal ~/.npmrc is left unchanged.

1. Create .npmrc in the project root (gitignored). Use this structure:

   //registry.npmjs.org/:_authToken=REPLACE_WITH_ROCKETIUM_NPM_TOKEN
   

2. Replace REPLACE_WITH_ROCKETIUM_NPM_TOKEN with the actual token (or ${NPM_TOKEN} for env-based auth).

3. Publish:

   npm run release:patch/minor/major

   as per the requirement

License

MIT