# fabric-editor-sdk

Public integration documentation: https://fabric-editor-sdk.pages.dev/example.
That Pages project serves documentation only; the consuming sites host the
immutable browser engine and codec assets described below.

Private, versioned shared Fabric browser engine for Coffee Frame and EditGator.
The engine runs in the browser. Hosting uses the consuming Pages deployment,
not the former fabric-editor Worker. No database or secret is required.

## Integration

Install the committed, SHA-256-checked package archive. In the remote Cloudflare
build, call `installAssets(distDirectory)` from `fabric-editor-sdk/assets` after
the website build. Route `/api/fabric-editor/*` to `handleFabricEditorRequest`
from `fabric-editor-sdk/cloudflare-pages`, passing the incoming Request and the
Pages `env.ASSETS` binding. Never forward these requests to a Worker.

The facade preserves GET/HEAD, conditional requests, byte ranges and immutable
release paths. It accepts only the packaged module graph. Cookies and bearer
headers are not forwarded. The manifest keeps the existing browser contract,
including the exact public limits previously provided by the Worker.

Release 1.1.12 advertises `sha256-2ad3204899f37180` and retains previous
`sha256-981b894ce35cbff8` byte-for-byte, including third-party licenses.
Resize and the general editor show source pixels outside the original reference.
Straighten opts into `clipSourceToDocument` for a fixed original frame. Live source
transforms reuse that clip; document synchronization compares accepted commands
to avoid rebuilding the source raster on every angle update.
The bundled HEIC codec uses a fast preset and honors export quality. See
[codec source and build notes](codecs/heic/README.md). On a synthetic 4032×3024
RGBA test, encoding fell from 17.4s to 9.3s at quality 75 on the same host; output
was 12.6 MB versus 6.6 MB. These timings are not a mobile performance guarantee.
Only the active release is advertised. The previous slot protects open tabs.

`npm pack --ignore-scripts` packages the reviewed source without building or
querying any service. Website validation runs remotely through the native
GitHub main → Cloudflare Pages workflow.

Codec worker responses receive a dedicated same-origin CSP permitting WebAssembly.
The document policy is unchanged. New immutable worker URLs prevent cached
pre-fix security headers from continuing to block compression after upgrading.

## Universal interaction API

Import `createToolInteraction` from `fabric-editor-sdk/interaction`. The same
module owns the frame queue used by Fabric, bounded settings scheduling,
validated product event transport, and action stage coordination.

Call `begin(initial)` at gesture start, `update(sample)` for pointer samples,
`commit(finalSample)` on release, `cancel()` on cancellation or target changes,
and `dispose()` on teardown. `project` uses cached geometry and returns a precise
draft; `visual` paints it without publishing document state. `values` publishes
changed presentation values at most every 32ms, flushed immediately on commit.
`onCommit` alone commits the gesture to the document. `onCancel` restores the
initial presentation. Input notifications must never become commands back to
the originating renderer.

For expensive asynchronous previews use `effect`, `onEffectResult`, and `onError`:
one effect runs at a time, only the latest queued request survives, and obsolete
results cannot publish. `execute(operation, input)` is explicit and supplies an
AbortSignal; obsolete results reject with AbortError. Non-abortable codec work
still requires the product's target/run checks before applying its result.

Adapters retain tool algorithms and rendering: Fabric owns transforms and
strokes; HTML crop overlays use the frame queue; effects retain bounded work;
codecs and remote operations only run on explicit execution. Draw adapters must
retain their ordered stroke data rather than treating a path as one position.
No application state, secret, network service, or Cloudflare Worker is added.

Quarter-turn rotation preserves the fitted display scale, zoom, and screen center; resetting orientation restores the original bounds without refitting.

The EditGator interactive editor accepts `setTool({id: 'view'})` for fixed
image previews without selection, transform handles, or editing shortcuts.
Viewport zoom remains available. Other tool modes retain their behavior.

The HEIC binary disables dynamic JavaScript execution; its WASM test enforces
the same restriction as the browser CSP.

## Source placement and undo history

`setSourceTransform(command, {phase: 'commit'})` records a changed source
placement in native history and emits one normal `onChange` callback. Repeating
an identical committed state does not create another history entry. Null commits
reset source placement and remain reversible. Preview is noncommitting.
`setSourceTransform(null, {phase: 'cancel'})` restores the pre-preview placement
without a document callback/history entry; it returns false without an active
preview. Loading/rebuilding a document invalidates the previous preview baseline.

The history tests execute the actual method bodies with isolated rendering doubles.
They prove command/history/callback transitions, not browser geometry, pixel output
or integration with an existing consumer.

Baked watermarks accept a decoded image, repeated in staggered rows through the
shared renderer. Image dimensions, asset budgets, and baked mode are validated.
Text watermarks retain their existing command contract.

Interactive image movement publishes presentation values through the shared 32ms
scheduler and flushes the exact transform on commit. Neutral adjustments reuse
the original render canvas without reading or rewriting pixels.
`inspectImageEditTransparency` defers work off the commit callback and checks
every output pixel in bounded 256×256 tiles, yielding after a 4ms work budget.
It supports cancellation and releases its temporary raster on completion/abort.
This is an exact alpha scan, not a reduced-resolution estimate.

Image Editor select mode accepts optional boolean `rotationOnly`. It shows the
native Fabric rotation handle and connector, hides all resize handles, and
selects the first image when entering this mode without an image selected.
Live and committed rotation use the existing transform callbacks and history.
Leaving rotation mode restores the normal resize handles.

Crop allows background viewport panning in both complete and standalone
editors. Object selection/movement remains disabled. Viewport callbacks keep
the crop overlay aligned, and pinch start cancels an active pan. Standalone
empty-touch page scrolling yields to viewport panning while Crop is active.

Canvas snapshots and hit-testing use the universal `excludeFromExport` and
visibility flags. The legacy guide object is removed only when loading saved
snapshots, preserving compatibility without repeated name-based exclusions.