@fabrika/annotations 0.2.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/annotations",
-	"version": "0.2.0",
+	"version": "0.3.1",
 	"type": "module",
 	"description": "React annotation state, text/block/region locators, editor and feedback surface.",
 	"license": "MIT",
@@ -29,6 +29,11 @@
 			"types": "./src/runtime.ts",
 			"default": "./src/runtime.ts"
 		},
+		"./schemas": {
+			"bun": "./src/schemas.ts",
+			"types": "./src/schemas.ts",
+			"default": "./src/schemas.ts"
+		},
 		"./styles.css": "./src/styles.css",
 		"./testing/dom.ts": {
 			"bun": "./src/testing/dom.ts",
@@ -49,5 +54,8 @@
 		"@happy-dom/global-registrator": {
 			"optional": true
 		}
+	},
+	"dependencies": {
+		"zod": "^3.25.76"
 	}
 }

package/src/AnnotationEditor.tsx

@@ -1,5 +1,6 @@
 import { type AnnotationHost, useAnnotationHost } from '@fabrika/annotations/runtime'
 import React, { useCallback, useEffect, useRef, useState } from 'react'
+import { localUploadResponseSchema, sharedUploadResponseSchema } from './schemas'
 import { autoResizeTextarea, hostAcceptsUploads } from './utils'
 
 interface AnnotationEditorProps {
@@ -44,11 +45,11 @@ async function uploadImage(host: AnnotationHost, file: File): Promise<string | n
 	formData.append('image', file)
 	try {
 		const resp = await fetch(endpoint(), { method: 'POST', body: formData })
-		const data = await resp.json()
+		const data: unknown = await resp.json()
 		// Local daemon returns { path }; worker returns { url }. Normalise to
 		// a single string that `imageToUrl` can resolve.
-		if (host.isShared) return data.url || null
-		return data.path || null
+		if (host.isShared) return sharedUploadResponseSchema.parse(data).url || null
+		return localUploadResponseSchema.parse(data).path || null
 	} catch {
 		return null
 	}

package/src/AnnotationProvider.tsx

@@ -1,6 +1,7 @@
 import { AnnotationCtx, SessionContext, useAnnotationHost } from '@fabrika/annotations/runtime'
-import React, { useEffect, useState } from 'react'
+import React, { useEffect, useRef, useState } from 'react'
 import type { Annotation, AnnotationState } from './runtime'
+import { annotationStateSchema } from './schemas'
 import { useAnnotationState } from './useAnnotationState'
 
 export { useAnnotations } from '@fabrika/annotations/runtime'
@@ -24,6 +25,7 @@ function AnnotationDraft({ scope, isReadOnly = false, remoteAnnotations, loadSta
 	const [annotations, setAnnotations] = useState<Annotation[]>([])
 	const [generalNote, setGeneralNote] = useState('')
 	const [hydrated, setHydrated] = useState(false)
+	const savedState = useRef<AnnotationState | null>(null)
 	const value = useAnnotationState({
 		annotations,
 		setAnnotations,
@@ -39,8 +41,10 @@ function AnnotationDraft({ scope, isReadOnly = false, remoteAnnotations, loadSta
 		setHydrated(false)
 		loadState(scope).then((saved) => {
 			if (cancelled) return
-			setAnnotations(saved?.annotations ?? [])
-			setGeneralNote(saved?.generalNote ?? '')
+			const result = annotationStateSchema.safeParse(saved)
+			savedState.current = result.success ? result.data : null
+			setAnnotations(result.success ? result.data.annotations : [])
+			setGeneralNote(result.success ? result.data.generalNote : '')
 			setHydrated(true)
 		})
 		return () => {
@@ -50,7 +54,7 @@ function AnnotationDraft({ scope, isReadOnly = false, remoteAnnotations, loadSta
 
 	useEffect(() => {
 		if (!hydrated || isReadOnly) return
-		const timer = setTimeout(() => saveState(scope, { annotations, generalNote }), 300)
+		const timer = setTimeout(() => saveState(scope, { ...savedState.current, annotations, generalNote }), 300)
 		return () => clearTimeout(timer)
 	}, [scope, annotations, generalNote, hydrated, isReadOnly, saveState])
 

package/src/schemas.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod'
+
+export const annotationContextSchema = z.object({
+	before: z.string(),
+	after: z.string(),
+	hierarchy: z.array(z.string()),
+	lineStart: z.number().optional(),
+	lineEnd: z.number().optional(),
+}).passthrough()
+
+export const annotationAuthorSchema = z.object({ id: z.string(), name: z.string() }).passthrough()
+export const annotationAttachmentSchema = z.object({ url: z.string(), mime: z.string().optional() }).passthrough()
+
+export const annotationSchema = z.object({
+	id: z.string(),
+	snippet: z.string(),
+	note: z.string(),
+	createdAt: z.string(),
+	filePath: z.string().optional(),
+	canvasFile: z.string().optional(),
+	context: annotationContextSchema.optional(),
+	images: z.array(z.string()).optional(),
+	attachments: z.array(annotationAttachmentSchema).optional(),
+	source: z.enum(['local', 'remote']).optional(),
+	author: annotationAuthorSchema.optional(),
+}).passthrough()
+
+// A damaged entry must not discard the other annotations in a saved draft.
+export const recoveredAnnotationsSchema = z.array(annotationSchema.optional().catch(undefined)).transform(entries =>
+	entries.filter(entry => entry !== undefined)
+).catch([])
+
+export const annotationStateSchema = z.object({
+	annotations: recoveredAnnotationsSchema,
+	generalNote: z.string().catch(''),
+}).passthrough()
+
+export const localUploadResponseSchema = z.object({ path: z.string() })
+export const sharedUploadResponseSchema = z.object({ url: z.string() })