KQ-1592 · FIELD/LOUPE

Field Loupe

A photo inspected with a jeweller's loupe: a circle of it magnified `power` times inside a hairline brass rim follows the pointer on the flick spring, and annotated points are magnetic — come close and the loupe settles onto the note on the glide spring and holds until you pull clearly away, while a leader line draws out from the rim and a note card rises in beside it on flick. The wheel or a trackpad pinch (two fingers on the lens on touch) changes the magnification and hands the scroll back to the page at either end. Every note is a button, so Tab walks the loupe from note to note, + and - change the power and Escape closes the card.

KQ-1592 · FIELD/LOUPE

Fernworks Bench Co.

Inside the workshop

loupe 2.5× · Fieldline gauge

Open it on the Canvas stage

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/field-loupe

Props

notes: readonly FieldLoupeNote[]; default defaultFieldLoupeNotes; The annotated points: { id, x, y (fractions of the photo), title, body, tag? }.
src: string; default —; An image to inspect instead of the drawn workbench.
alt: string; default —; What the photo shows, for assistive technology.
aspectRatio: number; default 1.6; The photo's width divided by its height.
value / defaultValue: string | null; default the first note; The id of the open note.
onValueChange: (id: string | null) => void; default —; Fires when a note opens or closes.
power: number; default 2.5; Magnification at rest; the wheel, a pinch or + and - change it from there.
minPower: number; default 1.25; The least the wheel or a pinch can magnify.
maxPower: number; default 5; The most the wheel or a pinch can magnify.
onPowerChange: (power: number) => void; default —; Fires when the wheel, a pinch or a key changes the magnification.
lensSize: number; default 144; The lens diameter in px, capped to fit small photos.
snap: number; default 0.6; How strongly notes pull the loupe, 0 (free) to 1 (a firm magnetic detent).
wheelZoom: boolean; default true; Let the wheel and a trackpad pinch change magnification over the photo.
markers: boolean; default true; Draw the hairline rings that mark each note.
rimColor: string; default a brass pigment from --warn; The rim and leader line, any CSS colour.
label: string; default "Photo with notes"; Names the photo with its notes for assistive technology.
disabled: boolean; default false; Shows the photo without the loupe's input.
className: string; default "w-full"; Sizes the component; the photo keeps its aspect ratio at this width.

Prop	Type	Default	Description
notes	readonly FieldLoupeNote[]	defaultFieldLoupeNotes	The annotated points: { id, x, y (fractions of the photo), title, body, tag? }.
src	string	—	An image to inspect instead of the drawn workbench.
alt	string	—	What the photo shows, for assistive technology.
aspectRatio	number	1.6	The photo's width divided by its height.
value / defaultValue	string \| null	the first note	The id of the open note.
onValueChange	(id: string \| null) => void	—	Fires when a note opens or closes.
power	number	2.5	Magnification at rest; the wheel, a pinch or + and - change it from there.
minPower	number	1.25	The least the wheel or a pinch can magnify.
maxPower	number	5	The most the wheel or a pinch can magnify.
onPowerChange	(power: number) => void	—	Fires when the wheel, a pinch or a key changes the magnification.
lensSize	number	144	The lens diameter in px, capped to fit small photos.
snap	number	0.6	How strongly notes pull the loupe, 0 (free) to 1 (a firm magnetic detent).
wheelZoom	boolean	true	Let the wheel and a trackpad pinch change magnification over the photo.
markers	boolean	true	Draw the hairline rings that mark each note.
rimColor	string	a brass pigment from --warn	The rim and leader line, any CSS colour.
label	string	"Photo with notes"	Names the photo with its notes for assistive technology.
disabled	boolean	false	Shows the photo without the loupe's input.
className	string	"w-full"	Sizes the component; the photo keeps its aspect ratio at this width.