Packages & Architecture

osdlabel is decomposed into a layered monorepo of 7 packages with clear dependency boundaries. This architecture ensures that core logic remains framework-agnostic while still providing a seamless, fully-integrated UI layer.

The 7 Packages

@osdlabel/annotation

Pure annotation data model with zero framework dependencies.

• Contains branded ID types (AnnotationId, ImageId), geometry discriminated unions, the generic Annotation<E> type, and basic sanitization utilities.
• Pluggable serialization system (createAnnotationValidator, ExtensionValidator<E>).
• Depends only on @standard-schema/spec (types-only).

@osdlabel/viewer-api

Viewer state types with zero framework dependencies.

• Contains types like CellTransform, UIState, and KeyboardShortcutMap.
• Depends only on @osdlabel/annotation.

@osdlabel/annotation-context

Annotation context, constraints, and scoping logic.

• Defines AnnotationContext, ToolConstraint, and the ContextFields extension interface.
• Contains validation and scoping utilities.
• Depends only on @osdlabel/annotation.

@osdlabel/validation

Valibot schema implementations for rigorous data validation.

• Implements the Standard Schema interface for annotation types (GeometrySchema, PointSchema, BaseAnnotationSchema).
• Depends on @osdlabel/annotation and valibot.

@osdlabel/fabric-annotations

Fabric.js annotation tools and utilities, completely SolidJS-agnostic and OSD-agnostic.

• Contains all tool implementations (RectangleTool, CircleTool, FreeHandPathTool, etc.).
• Defines the ToolOverlay interface and FabricFields extension interface.
• Depends on @osdlabel/annotation, @osdlabel/annotation-context, @osdlabel/viewer-api, and fabric.

@osdlabel/fabric-osd

The overlay bridge connecting Fabric.js and OpenSeaDragon.

• Implements the FabricOverlay class, handling coordinate transformations and pointer event routing.
• SolidJS-agnostic.
• Depends on the core packages, fabric, and openseadragon.

osdlabel

The final SolidJS annotator UI layer.

• Re-exports and composes all the above packages.
• Contains the reactive state stores, hooks (useAnnotator, useConstraints), and components (Annotator, ViewerCell, Toolbar, etc.).
• The OsdAnnotation type is composed here by intersecting BaseAnnotation with ContextFields and FabricFields.

---

Import structure

For most applications, importing directly from the main osdlabel package is the quickest and easiest way to get started. osdlabel provides ESM-friendly sub-path exports.

1. Main barrel

Recommended for quick starts. Re-exports the primary components and functions.

import { Annotator, useAnnotator, serialize } from 'osdlabel';

2. Sub-path barrels

Preferred for better build performance and tree-shaking in production apps.

import { Annotator } from 'osdlabel/components';
import { useAnnotator } from 'osdlabel/state';

3. Direct Package Imports

For advanced usage, you can import types and core logic directly from the granular packages. This is particularly useful if you are building a custom UI layer instead of using the SolidJS components.

import type { Annotation } from '@osdlabel/annotation';
import type { ImageSource } from '@osdlabel/viewer-api';
import type { AnnotationContext } from '@osdlabel/annotation-context';
import { serialize } from 'osdlabel';