From bc0e3a2e43077c517e332a679a33f67d15d6945b Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Wed, 4 Nov 2026 18:17:53 +0100 Subject: [PATCH 01/17] feat: add a maxSize image option --- .../java/me/sectiontn/inkpad/ExportOptions.kt | 7 +++- .../java/me/sectiontn/inkpad/ImageExporter.kt | 7 ++-- .../me/sectiontn/inkpad/ExportOptionsTest.kt | 32 +++++++++++++++-- ios/INKImageExporter.m | 4 +++ src/__tests__/exportImage.test.ts | 36 +++++++++++++++++++ src/__tests__/imageOptions.test.ts | 9 +++++ src/imageOptions.ts | 3 ++ src/types.ts | 2 ++ src/web/exportImage.ts | 12 +++++-- 9 files changed, 103 insertions(+), 9 deletions(-) diff --git a/android/src/main/java/me/sectiontn/inkpad/ExportOptions.kt b/android/src/main/java/me/sectiontn/inkpad/ExportOptions.kt index b7ce0f0..ba79abf 100644 --- a/android/src/main/java/me/sectiontn/inkpad/ExportOptions.kt +++ b/android/src/main/java/me/sectiontn/inkpad/ExportOptions.kt @@ -8,6 +8,7 @@ internal class ExportOptions( val jpeg: Boolean, val quality: Float, val scale: Float, + val maxSize: Int, val trim: Boolean, val padding: Float, val background: Boolean, @@ -16,7 +17,10 @@ internal class ExportOptions( val backgroundImageUri: String?, val backgroundFit: BackgroundFit?, ) { - fun pixels(units: Float): Int = maxOf(1, (units * scale).roundToInt()) + fun scaleFor(areaWidth: Float, areaHeight: Float): Float = + if (maxSize > 0) minOf(scale, maxSize / maxOf(areaWidth, areaHeight)) else scale + + fun pixels(units: Float, scale: Float): Int = maxOf(1, (units * scale).roundToInt()) companion object { fun parse(json: String?): ExportOptions { @@ -26,6 +30,7 @@ internal class ExportOptions( jpeg = o.optString("format") == "jpeg", quality = o.optDouble("quality", 0.9).toFloat().coerceIn(0f, 1f), scale = if (scale > 0f) scale else 1f, + maxSize = o.optInt("maxSize", 0).coerceAtLeast(0), trim = o.optBoolean("trim", false), padding = o.optDouble("padding", 0.0).toFloat().coerceAtLeast(0f), background = o.optBoolean("background", true), diff --git a/android/src/main/java/me/sectiontn/inkpad/ImageExporter.kt b/android/src/main/java/me/sectiontn/inkpad/ImageExporter.kt index 5a96ecb..101058a 100644 --- a/android/src/main/java/me/sectiontn/inkpad/ImageExporter.kt +++ b/android/src/main/java/me/sectiontn/inkpad/ImageExporter.kt @@ -42,15 +42,16 @@ internal object ImageExporter { areaWidth = boxes.maxOf { it.xMax } + options.padding - left areaHeight = boxes.maxOf { it.yMax } + options.padding - top } - val pixelWidth = options.pixels(areaWidth) - val pixelHeight = options.pixels(areaHeight) + val scale = options.scaleFor(areaWidth, areaHeight) + val pixelWidth = options.pixels(areaWidth, scale) + val pixelHeight = options.pixels(areaHeight, scale) val bitmap = Bitmap.createBitmap(pixelWidth, pixelHeight, Bitmap.Config.ARGB_8888) try { val canvas = Canvas(bitmap) if (options.jpeg) canvas.drawColor(Color.WHITE) if (options.background && Color.alpha(canvasColor) > 0) canvas.drawColor(canvasColor) val transform = Matrix().apply { - setScale(options.scale, options.scale) + setScale(scale, scale) preTranslate(-left, -top) } canvas.concat(transform) diff --git a/android/src/test/java/me/sectiontn/inkpad/ExportOptionsTest.kt b/android/src/test/java/me/sectiontn/inkpad/ExportOptionsTest.kt index 0517ef7..5d344cd 100644 --- a/android/src/test/java/me/sectiontn/inkpad/ExportOptionsTest.kt +++ b/android/src/test/java/me/sectiontn/inkpad/ExportOptionsTest.kt @@ -57,7 +57,35 @@ class ExportOptionsTest { @Test fun roundsPixelSizesAndNeverReturnsZero() { val options = ExportOptions.parse("""{"scale":2.625}""") - assertEquals(840, options.pixels(320f)) - assertEquals(1, options.pixels(0.1f)) + assertEquals(840, options.pixels(320f, options.scale)) + assertEquals(1, options.pixels(0.1f, options.scale)) + } + + @Test + fun readsMaxSize() { + assertEquals(160, ExportOptions.parse("""{"maxSize":160}""").maxSize) + assertEquals(0, ExportOptions.parse("{}").maxSize) + } + + @Test + fun capsTheScaleToMaxSize() { + val options = ExportOptions.parse("""{"scale":2,"maxSize":160}""") + val scale = options.scaleFor(300f, 200f) + assertEquals(160, options.pixels(300f, scale)) + assertEquals(107, options.pixels(200f, scale)) + } + + @Test + fun neverRaisesTheScale() { + val options = ExportOptions.parse("""{"scale":2,"maxSize":1000}""") + assertEquals(2f, options.scaleFor(300f, 200f), 0f) + } + + @Test + fun clampsTheShortSideToOnePixel() { + val options = ExportOptions.parse("""{"scale":1,"maxSize":160}""") + val scale = options.scaleFor(2000f, 10f) + assertEquals(160, options.pixels(2000f, scale)) + assertEquals(1, options.pixels(10f, scale)) } } diff --git a/ios/INKImageExporter.m b/ios/INKImageExporter.m index 4755360..aeceea6 100644 --- a/ios/INKImageExporter.m +++ b/ios/INKImageExporter.m @@ -26,6 +26,7 @@ + (void)exportDrawing:(PKDrawing *)drawing BOOL jpeg = [options[@"format"] isEqual:@"jpeg"]; CGFloat quality = options[@"quality"] ? MIN(1, MAX(0, [options[@"quality"] doubleValue])) : 0.9; CGFloat scale = [options[@"scale"] doubleValue] > 0 ? [options[@"scale"] doubleValue] : UIScreen.mainScreen.scale; + NSInteger maxSize = [options[@"maxSize"] integerValue]; BOOL trim = [options[@"trim"] boolValue]; CGFloat padding = MAX(0, [options[@"padding"] doubleValue]); BOOL background = options[@"background"] ? [options[@"background"] boolValue] : YES; @@ -39,6 +40,9 @@ + (void)exportDrawing:(PKDrawing *)drawing } area = CGRectInset(drawing.bounds, -padding, -padding); } + if (maxSize > 0) { + scale = MIN(scale, maxSize / MAX(area.size.width, area.size.height)); + } CGSize pixels = CGSizeMake(MAX(1, round(area.size.width * scale)), MAX(1, round(area.size.height * scale))); dispatch_async(dispatch_get_global_queue(QOS_CLASS_USER_INITIATED, 0), ^{ diff --git a/src/__tests__/exportImage.test.ts b/src/__tests__/exportImage.test.ts index f5e3b73..94c5939 100644 --- a/src/__tests__/exportImage.test.ts +++ b/src/__tests__/exportImage.test.ts @@ -21,6 +21,7 @@ const opts = (over: Partial): NativeImageOptions => ({ format: 'png', quality: 0.9, scale: 2, + maxSize: 0, trim: false, padding: 0, background: true, @@ -96,6 +97,7 @@ describe('exportArea', () => { y: 8, width: 44, height: 4, + scale: 3, pixelWidth: 132, pixelHeight: 12, }); @@ -120,6 +122,33 @@ describe('exportArea', () => { expect.objectContaining({ code: 'E_EMPTY' }), ); }); + + it('caps the scale at maxSize', () => { + const area = exportArea(doc([line]), opts({ maxSize: 160 })); + expect(area).toMatchObject({ pixelWidth: 160, pixelHeight: 107 }); + expect(area.scale).toBeCloseTo(160 / 300); + }); + + it('never raises the scale', () => { + expect(exportArea(doc([line]), opts({ maxSize: 1000 }))).toMatchObject({ + pixelWidth: 600, + pixelHeight: 400, + scale: 2, + }); + }); + + it('caps the trimmed area', () => { + const area = exportArea(doc([line]), opts({ trim: true, padding: 5, maxSize: 50 })); + expect(Math.max(area.pixelWidth, area.pixelHeight)).toBe(50); + }); + + it('clamps the short side to one pixel', () => { + const strip = { ...doc([]), size: { width: 2000, height: 10 } }; + expect(exportArea(strip, opts({ scale: 1, maxSize: 160 }))).toMatchObject({ + pixelWidth: 160, + pixelHeight: 1, + }); + }); }); describe('exportImage', () => { @@ -155,6 +184,13 @@ describe('exportImage', () => { expect(calls.find((call) => call.op === 'setTransform')?.args).toEqual([3, 0, 0, 3, -24, -24]); }); + it('draws at the capped scale', async () => { + await exportImage(doc([line]), opts({ maxSize: 160 }), undefined, deps); + const [a, , , d] = calls.find((call) => call.op === 'setTransform')?.args ?? []; + expect(a).toBeCloseTo(160 / 300); + expect(d).toBeCloseTo(160 / 300); + }); + it('rejects when the browser cannot encode', async () => { await expect(exportImage(doc([line]), opts({}), undefined, failingDeps)).rejects.toMatchObject({ code: 'E_EXPORT_FAILED', diff --git a/src/__tests__/imageOptions.test.ts b/src/__tests__/imageOptions.test.ts index 5764b06..969a3a2 100644 --- a/src/__tests__/imageOptions.test.ts +++ b/src/__tests__/imageOptions.test.ts @@ -7,6 +7,7 @@ describe('toNativeImageOptions', () => { format: 'png', quality: 0.9, scale: 3, + maxSize: 0, trim: false, padding: 0, background: true, @@ -31,6 +32,7 @@ describe('toNativeImageOptions', () => { format: 'jpeg', quality: 1, scale: 2, + maxSize: 0, trim: true, padding: 8, background: false, @@ -41,6 +43,13 @@ describe('toNativeImageOptions', () => { it('falls back to the device scale when the scale is not positive', () => { expect(toNativeImageOptions({ scale: 0 }, 2).scale).toBe(2); }); + + it('maps maxSize', () => { + expect(toNativeImageOptions({ maxSize: 160.9 }, 2).maxSize).toBe(160); + for (const maxSize of [0, -5, Number.POSITIVE_INFINITY, Number.NaN]) { + expect(toNativeImageOptions({ maxSize }, 2).maxSize).toBe(0); + } + }); }); describe('withBackground', () => { diff --git a/src/imageOptions.ts b/src/imageOptions.ts index 203df37..b34825e 100644 --- a/src/imageOptions.ts +++ b/src/imageOptions.ts @@ -4,6 +4,7 @@ export type NativeImageOptions = { format: 'png' | 'jpeg'; quality: number; scale: number; + maxSize: number; trim: boolean; padding: number; background: boolean; @@ -15,10 +16,12 @@ export function toNativeImageOptions( defaultScale: number, ): NativeImageOptions { const trim = options.trim ?? false; + const maxSize = options.maxSize ?? 0; return { format: options.format ?? 'png', quality: Math.min(1, Math.max(0, options.quality ?? 0.9)), scale: options.scale !== undefined && options.scale > 0 ? options.scale : defaultScale, + maxSize: Number.isFinite(maxSize) && maxSize >= 1 ? Math.floor(maxSize) : 0, trim: trim !== false, padding: typeof trim === 'object' ? Math.max(0, trim.padding) : 0, background: options.background ?? true, diff --git a/src/types.ts b/src/types.ts index 3a8cec7..8e8dd51 100644 --- a/src/types.ts +++ b/src/types.ts @@ -82,6 +82,8 @@ export type ImageOptions = { quality?: number; /** Pixels per layout unit. Default: the screen's pixel ratio. */ scale?: number; + /** Longest side in pixels. Lowers the scale when the image would be bigger; never raises it. */ + maxSize?: number; /** Default `false`. */ trim?: Trim; /** Keeps the canvas color and background image in the export. Default `true`. */ diff --git a/src/web/exportImage.ts b/src/web/exportImage.ts index 543d02a..4e970b4 100644 --- a/src/web/exportImage.ts +++ b/src/web/exportImage.ts @@ -13,6 +13,7 @@ export type ExportArea = { y: number; width: number; height: number; + scale: number; pixelWidth: number; pixelHeight: number; }; @@ -57,13 +58,18 @@ export function exportArea(doc: InkDocument, options: NativeImageOptions): Expor width = bounds.maxX - bounds.minX + options.padding * 2; height = bounds.maxY - bounds.minY + options.padding * 2; } + const scale = + options.maxSize > 0 + ? Math.min(options.scale, options.maxSize / Math.max(width, height)) + : options.scale; return { x, y, width, height, - pixelWidth: pixels(width, options.scale), - pixelHeight: pixels(height, options.scale), + scale, + pixelWidth: pixels(width, scale), + pixelHeight: pixels(height, scale), }; } @@ -83,7 +89,7 @@ export async function exportImage( if (options.format === 'jpeg') drawBackground(ctx, '#FFFFFFFF', area.pixelWidth, area.pixelHeight); if (options.background) drawBackground(ctx, backgroundColor, area.pixelWidth, area.pixelHeight); - const { scale } = options; + const { scale } = area; ctx.setTransform(scale, 0, 0, scale, -area.x * scale, -area.y * scale); if (options.background && backgroundImage) { drawBackgroundImage(ctx, backgroundImage.image, doc.size, backgroundImage.fit); From a5c878d9deb6fc332f2dac77ea7211cd29330294 Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Wed, 4 Nov 2026 18:22:09 +0100 Subject: [PATCH 02/17] feat: render a document to SVG without a canvas --- src/__tests__/renderCore.test.ts | 101 +++++++++++++++++++++++++++++++ src/index.tsx | 3 + src/render/core.ts | 47 ++++++++++++++ src/render/renderSVG.ts | 9 +++ src/render/resolveImage.ts | 5 ++ src/render/resolveImage.web.ts | 7 +++ src/render/resolvers.ts | 12 ++++ src/svg/toSVG.ts | 2 +- src/trim.ts | 2 + src/types.ts | 19 ++++-- 10 files changed, 202 insertions(+), 5 deletions(-) create mode 100644 src/__tests__/renderCore.test.ts create mode 100644 src/render/core.ts create mode 100644 src/render/renderSVG.ts create mode 100644 src/render/resolveImage.ts create mode 100644 src/render/resolveImage.web.ts create mode 100644 src/render/resolvers.ts create mode 100644 src/trim.ts diff --git a/src/__tests__/renderCore.test.ts b/src/__tests__/renderCore.test.ts new file mode 100644 index 0000000..f313472 --- /dev/null +++ b/src/__tests__/renderCore.test.ts @@ -0,0 +1,101 @@ +import { describe, expect, it } from 'vitest'; +import type { InkDocument } from '../document'; +import { ErrorCode, InkpadError } from '../errors'; +import { type BackgroundResolvers, renderSvgWith, resolveBackground } from '../render/core'; +import { toSVG } from '../svg/toSVG'; + +const doc: InkDocument = { + version: 1, + size: { width: 300, height: 200 }, + strokes: [ + { + brush: { type: 'pen', color: '#000000FF', size: 4 }, + input: 'touch', + points: [10, 10, 0, -1, -1, -1, 50, 10, 16, -1, -1, -1], + }, + ], +}; + +const resolvers: BackgroundResolvers = { + color: (value) => (typeof value === 'string' ? '#FFFFFFFF' : undefined), + image: (source) => (typeof source === 'string' ? `https://x/${source}` : undefined), +}; + +describe('resolveBackground', () => { + it('resolves color and image through the resolvers', () => { + expect(resolveBackground({ color: 'c', image: 'p.png', fit: 'cover' }, resolvers)).toEqual({ + color: '#FFFFFFFF', + uri: 'https://x/p.png', + fit: 'cover', + }); + }); + + it('defaults fit to contain', () => { + expect(resolveBackground({ image: 'p.png' }, resolvers).fit).toBe('contain'); + expect(resolveBackground(undefined, resolvers)).toEqual({ + color: undefined, + uri: undefined, + fit: 'contain', + }); + }); + + it('uses the first entry of an array source', () => { + expect(resolveBackground({ image: ['a.png', 'b.png'] }, resolvers).uri).toBe('https://x/a.png'); + }); + + it("drops a color the resolver can't read", () => { + expect(resolveBackground({ color: {} }, resolvers).color).toBeUndefined(); + }); + + it('throws E_IMAGE_LOAD for an image with no usable URI', () => { + for (const image of [{}, ''] as const) { + const call = () => + resolveBackground( + { image }, + { color: resolvers.color, image: () => (image === '' ? '' : undefined) }, + ); + expect(call).toThrow(InkpadError); + expect(call).toThrow(expect.objectContaining({ code: ErrorCode.IMAGE_LOAD })); + } + }); + + it('passes through an InkpadError from the resolver', () => { + const error = new InkpadError(ErrorCode.IMAGE_LOAD, 'numeric'); + const throwing = { + color: resolvers.color, + image: () => { + throw error; + }, + }; + expect(() => resolveBackground({ image: 1 }, throwing)).toThrow(error); + }); +}); + +describe('renderSvgWith', () => { + it('leaves the background out when none is given', () => { + expect(renderSvgWith(doc, undefined, resolvers)).toBe(toSVG(doc)); + }); + + it('matches toSVG with the same background', () => { + const fixed = { color: () => '#FFFFFFFF', image: () => 'https://x/p.png' }; + expect( + renderSvgWith( + doc, + { trim: true, background: { color: 'c', image: 'i', fit: 'cover' } }, + fixed, + ), + ).toBe( + toSVG(doc, { + trim: true, + backgroundColor: '#FFFFFFFF', + backgroundImage: { uri: 'https://x/p.png', fit: 'cover' }, + }), + ); + }); + + it('throws E_INVALID_DOCUMENT for a bad document', () => { + expect(() => renderSvgWith({ version: 1 }, undefined, resolvers)).toThrow( + expect.objectContaining({ code: ErrorCode.INVALID_DOCUMENT }), + ); + }); +}); diff --git a/src/index.tsx b/src/index.tsx index 633bfc5..7ef6103 100644 --- a/src/index.tsx +++ b/src/index.tsx @@ -2,6 +2,7 @@ export type { InkBrush, InkDocument, InkStroke, InputType } from './document'; export { validateDocument } from './document'; export { ErrorCode, InkpadError } from './errors'; export { InkCanvas } from './InkCanvas'; +export { renderSVG } from './render/renderSVG'; export type { Background, BackgroundFit, @@ -13,6 +14,8 @@ export type { InkCanvasRef, InkState, InputMode, + RenderImageOptions, + RenderSVGOptions, SvgOptions, Trim, } from './types'; diff --git a/src/render/core.ts b/src/render/core.ts new file mode 100644 index 0000000..46bfffd --- /dev/null +++ b/src/render/core.ts @@ -0,0 +1,47 @@ +import { validateDocument } from '../document'; +import { ErrorCode, InkpadError } from '../errors'; +import type { BackgroundFit } from '../geometry/fit'; +import { toSVG } from '../svg/toSVG'; +import type { Trim } from '../trim'; + +export type BackgroundInput = { color?: C; image?: I | readonly I[]; fit?: BackgroundFit }; + +export type BackgroundResolvers = { + /** Returns `#RRGGBBAA`, or `undefined` for a color it can't read. */ + color(value: C): string | undefined; + image(source: I): string | undefined; +}; + +export type ResolvedBackground = { + color: string | undefined; + uri: string | undefined; + fit: BackgroundFit; +}; + +export function resolveBackground( + background: BackgroundInput | undefined, + resolvers: BackgroundResolvers, +): ResolvedBackground { + const fit = background?.fit ?? 'contain'; + const color = background?.color != null ? resolvers.color(background.color) : undefined; + const image = background?.image; + if (image == null) return { color, uri: undefined, fit }; + const source = Array.isArray(image) ? image[0] : (image as I); + const uri = source != null ? resolvers.image(source) : undefined; + if (!uri) throw new InkpadError(ErrorCode.IMAGE_LOAD, 'background.image has no usable URI'); + return { color, uri, fit }; +} + +export function renderSvgWith( + doc: unknown, + options: { trim?: Trim; background?: BackgroundInput } | undefined, + resolvers: BackgroundResolvers, +): string { + const valid = validateDocument(doc); + const { color, uri, fit } = resolveBackground(options?.background, resolvers); + return toSVG(valid, { + trim: options?.trim, + backgroundColor: color, + backgroundImage: uri ? { uri, fit } : undefined, + }); +} diff --git a/src/render/renderSVG.ts b/src/render/renderSVG.ts new file mode 100644 index 0000000..dc300f4 --- /dev/null +++ b/src/render/renderSVG.ts @@ -0,0 +1,9 @@ +import type { InkDocument } from '../document'; +import type { RenderSVGOptions } from '../types'; +import { renderSvgWith } from './core'; +import { appResolvers } from './resolvers'; + +/** Renders a stored document to an SVG string without mounting a canvas. */ +export function renderSVG(doc: InkDocument, options?: RenderSVGOptions): string { + return renderSvgWith(doc, options, appResolvers); +} diff --git a/src/render/resolveImage.ts b/src/render/resolveImage.ts new file mode 100644 index 0000000..d8621cc --- /dev/null +++ b/src/render/resolveImage.ts @@ -0,0 +1,5 @@ +import { Image, type ImageSourcePropType } from 'react-native'; + +export function resolveImage(source: ImageSourcePropType): string | undefined { + return Image.resolveAssetSource(source)?.uri; +} diff --git a/src/render/resolveImage.web.ts b/src/render/resolveImage.web.ts new file mode 100644 index 0000000..3ee6dfe --- /dev/null +++ b/src/render/resolveImage.web.ts @@ -0,0 +1,7 @@ +import type { ImageSourcePropType } from 'react-native'; +import { uriOf } from '../web/imageSource'; + +export function resolveImage(source: ImageSourcePropType): string | undefined { + const uri = uriOf(source); + return uri ? new URL(uri, document.baseURI).href : undefined; +} diff --git a/src/render/resolvers.ts b/src/render/resolvers.ts new file mode 100644 index 0000000..9e7ac57 --- /dev/null +++ b/src/render/resolvers.ts @@ -0,0 +1,12 @@ +import { type ColorValue, type ImageSourcePropType, processColor } from 'react-native'; +import { argbToHex } from '../color'; +import type { BackgroundResolvers } from './core'; +import { resolveImage } from './resolveImage'; + +export const appResolvers: BackgroundResolvers = { + color(value) { + const processed = processColor(value); + return typeof processed === 'number' ? argbToHex(processed) : undefined; + }, + image: resolveImage, +}; diff --git a/src/svg/toSVG.ts b/src/svg/toSVG.ts index 6fe44ad..2fdbfc2 100644 --- a/src/svg/toSVG.ts +++ b/src/svg/toSVG.ts @@ -6,7 +6,7 @@ import type { BackgroundFit } from '../geometry/fit'; import { nibFor } from '../geometry/nib'; import { fmt, outlinePath, widthPoints } from '../geometry/outline'; import { strokePaint } from '../paint'; -import type { Trim } from '../types'; +import type { Trim } from '../trim'; export type SvgRenderOptions = { trim?: Trim; diff --git a/src/trim.ts b/src/trim.ts new file mode 100644 index 0000000..7ce9477 --- /dev/null +++ b/src/trim.ts @@ -0,0 +1,2 @@ +/** `true` crops the export to the strokes; `{ padding }` also adds room around them, in layout units. */ +export type Trim = boolean | { padding: number }; diff --git a/src/types.ts b/src/types.ts index 8e8dd51..52f4fbd 100644 --- a/src/types.ts +++ b/src/types.ts @@ -3,8 +3,9 @@ import type { ColorValue, ImageSourcePropType, ViewProps } from 'react-native'; import type { BrushType, InkDocument } from './document'; import type { InkpadError } from './errors'; import type { BackgroundFit } from './geometry/fit'; +import type { Trim } from './trim'; -export type { BackgroundFit, BrushType }; +export type { BackgroundFit, BrushType, Trim }; /** The brush new strokes use. */ export type Brush = { @@ -72,9 +73,6 @@ export type InkCanvasProps = ViewProps & { onError?: (error: InkpadError) => void; }; -/** `true` crops the export to the strokes; `{ padding }` also adds room around them, in layout units. */ -export type Trim = boolean | { padding: number }; - export type ImageOptions = { /** Default `'png'`. */ format?: 'png' | 'jpeg'; @@ -109,3 +107,16 @@ export type SvgOptions = { /** Keeps the canvas color and background image in the SVG. Default `true`. */ background?: boolean; }; + +/** Options for `renderImage`. The background is the canvas's `Background`, not a flag; default: none (transparent). */ +export type RenderImageOptions = Omit & { + background?: Background; +}; + +/** Options for `renderSVG`. */ +export type RenderSVGOptions = { + /** Default `false`. */ + trim?: Trim; + /** Canvas color and background image drawn under the strokes. Default: none. */ + background?: Background; +}; From 035707674efe3b9855815380205b38b110e9ea74 Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Wed, 4 Nov 2026 18:24:38 +0100 Subject: [PATCH 03/17] feat: add a server entry that renders SVG without React Native The normalize-colors range is * so a package manager dedupes it with the copy React Native already installs, whatever the app's RN version. --- package.json | 8 +++ src/__tests__/svgEntry.test.ts | 93 ++++++++++++++++++++++++++++++++++ src/svg/cssColor.ts | 11 ++++ src/svg/index.ts | 24 +++++++++ types/normalize-colors.d.ts | 3 ++ yarn.lock | 8 +++ 6 files changed, 147 insertions(+) create mode 100644 src/__tests__/svgEntry.test.ts create mode 100644 src/svg/cssColor.ts create mode 100644 src/svg/index.ts create mode 100644 types/normalize-colors.d.ts diff --git a/package.json b/package.json index 3c7a4ae..10ac247 100644 --- a/package.json +++ b/package.json @@ -15,6 +15,11 @@ "types": "./lib/typescript/src/compat/SignatureCanvas.d.ts", "default": "./lib/module/compat/SignatureCanvas.js" }, + "./svg": { + "react-native-inkpad-source": "./src/svg/index.ts", + "types": "./lib/typescript/src/svg/index.d.ts", + "default": "./lib/module/svg/index.js" + }, "./package.json": "./package.json" }, "files": [ @@ -95,6 +100,9 @@ "vite": "8.3.2", "vitest": "5.0.3" }, + "dependencies": { + "@react-native/normalize-colors": "*" + }, "peerDependencies": { "react": "*", "react-native": ">=0.84.0" diff --git a/src/__tests__/svgEntry.test.ts b/src/__tests__/svgEntry.test.ts new file mode 100644 index 0000000..cc7daf4 --- /dev/null +++ b/src/__tests__/svgEntry.test.ts @@ -0,0 +1,93 @@ +import { existsSync, readFileSync } from 'node:fs'; +import { dirname, resolve } from 'node:path'; +import { describe, expect, it, vi } from 'vitest'; +import type { InkDocument } from '../document'; +import { renderSvgWith } from '../render/core'; + +vi.mock('react-native', () => { + throw new Error('react-native imported'); +}); + +const doc: InkDocument = { + version: 1, + size: { width: 100, height: 60 }, + strokes: [ + { + brush: { type: 'pen', color: '#1C1C1EFF', size: 3 }, + input: 'touch', + points: [10, 10, 0, -1, -1, -1, 50, 30, 16, -1, -1, -1], + }, + ], +}; + +function resolveFile(from: string, specifier: string): string | undefined { + const base = resolve(dirname(from), specifier); + return [`${base}.ts`, `${base}.tsx`, `${base}/index.ts`, base].find( + (path) => path.match(/\.tsx?$/) && existsSync(path), + ); +} + +function collectSpecifiers(entry: string): string[] { + const seen = new Set(); + const bare: string[] = []; + const queue = [entry]; + while (queue.length > 0) { + const file = queue.pop() as string; + if (seen.has(file)) continue; + seen.add(file); + const source = readFileSync(file, 'utf8'); + for (const match of source.matchAll(/(?:from|import)\s*\(?\s*'([^']+)'/g)) { + const specifier = match[1] as string; + if (specifier.startsWith('.')) { + const next = resolveFile(file, specifier); + if (next) queue.push(next); + } else { + bare.push(specifier); + } + } + } + return bare; +} + +describe('react-native-inkpad/svg', () => { + it('loads without react-native', async () => { + const entry = await import('../svg'); + expect(typeof entry.renderSVG).toBe('function'); + }); + + it('has no react-native import anywhere in its graph', () => { + const bare = collectSpecifiers(resolve(__dirname, '../svg/index.ts')); + const offenders = bare.filter((s) => s === 'react-native' || s.startsWith('react-native/')); + expect(offenders).toEqual([]); + }); + + it('parses CSS colors', async () => { + const { cssColorToHex } = await import('../svg/cssColor'); + expect(cssColorToHex('white')).toBe('#FFFFFFFF'); + expect(cssColorToHex('rgba(255, 0, 0, 0.5)')).toBe('#FF000080'); + expect(cssColorToHex('#00F')).toBe('#0000FFFF'); + }); + + it("throws E_EXPORT_FAILED for a color it can't parse", async () => { + const { cssColorToHex } = await import('../svg/cssColor'); + expect(() => cssColorToHex('not-a-color')).toThrowError( + expect.objectContaining({ + code: 'E_EXPORT_FAILED', + message: 'background.color is not a CSS color: not-a-color', + }), + ); + }); + + it('matches the root renderSVG', async () => { + const { renderSVG } = await import('../svg'); + const options = { + trim: true, + background: { color: '#FFFFFF', image: { uri: 'https://x/p.png' }, fit: 'cover' as const }, + }; + const expected = renderSvgWith(doc, options, { + color: () => '#FFFFFFFF', + image: () => 'https://x/p.png', + }); + expect(renderSVG(doc, options)).toBe(expected); + }); +}); diff --git a/src/svg/cssColor.ts b/src/svg/cssColor.ts new file mode 100644 index 0000000..a1dc89f --- /dev/null +++ b/src/svg/cssColor.ts @@ -0,0 +1,11 @@ +import normalizeColor from '@react-native/normalize-colors'; +import { ErrorCode, InkpadError } from '../errors'; + +/** Parses a CSS color into `#RRGGBBAA`. */ +export function cssColorToHex(color: string): string { + const value = normalizeColor(color); + if (value == null) { + throw new InkpadError(ErrorCode.EXPORT_FAILED, `background.color is not a CSS color: ${color}`); + } + return `#${(value >>> 0).toString(16).padStart(8, '0').toUpperCase()}`; +} diff --git a/src/svg/index.ts b/src/svg/index.ts new file mode 100644 index 0000000..4e49c22 --- /dev/null +++ b/src/svg/index.ts @@ -0,0 +1,24 @@ +import type { InkDocument } from '../document'; +import type { BackgroundFit } from '../geometry/fit'; +import { renderSvgWith } from '../render/core'; +import type { Trim } from '../trim'; +import { cssColorToHex } from './cssColor'; + +export type ServerSVGOptions = { + trim?: Trim; + background?: { color?: string; image?: { uri: string }; fit?: BackgroundFit }; +}; + +/** Renders a stored document to an SVG string in Node, with no React Native loaded. */ +export function renderSVG(doc: InkDocument, options?: ServerSVGOptions): string { + return renderSvgWith(doc, options, { + color: cssColorToHex, + image: (source) => source.uri, + }); +} + +export type { InkBrush, InkDocument, InkStroke, InputType } from '../document'; +export { validateDocument } from '../document'; +export { ErrorCode, InkpadError } from '../errors'; +export type { BackgroundFit } from '../geometry/fit'; +export type { Trim } from '../trim'; diff --git a/types/normalize-colors.d.ts b/types/normalize-colors.d.ts new file mode 100644 index 0000000..d2e28d0 --- /dev/null +++ b/types/normalize-colors.d.ts @@ -0,0 +1,3 @@ +declare module '@react-native/normalize-colors' { + export default function normalizeColor(color: unknown): number | null; +} diff --git a/yarn.lock b/yarn.lock index c94b660..b286cc3 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3657,6 +3657,13 @@ __metadata: languageName: node linkType: hard +"@react-native/normalize-colors@npm:*": + version: 0.88.1 + resolution: "@react-native/normalize-colors@npm:0.88.1" + checksum: 10c0/3db7e7b7ac754f648759cced1cccfb0e2526ed5088495312da7d2b797e1bb1b9df351fd583e4c6bf09fd5c99a757335bc503736673962df173fe9afeab6c1205 + languageName: node + linkType: hard + "@react-native/normalize-colors@npm:0.86.3": version: 0.86.3 resolution: "@react-native/normalize-colors@npm:0.86.3" @@ -8654,6 +8661,7 @@ __metadata: "@e2e-dev/mobile": "npm:0.12.0" "@e2e-dev/web": "npm:0.14.0" "@react-native/babel-preset": "npm:0.86.2" + "@react-native/normalize-colors": "npm:*" "@release-it/conventional-changelog": "npm:^12.0.0" "@types/node": "npm:^26.6.4" "@types/react": "npm:^19.2.0" From 54061e0ffbc05fd9dcf9cfe46cca99c5f229e329 Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Wed, 4 Nov 2026 18:30:44 +0100 Subject: [PATCH 04/17] feat: render a document to an image without a canvas --- src/__tests__/exportImage.test.ts | 49 +-------- src/__tests__/fakeCanvas.ts | 51 +++++++++ src/__tests__/imageCore.test.ts | 150 +++++++++++++++++++++++++++ src/__tests__/renderDocument.test.ts | 84 +++++++++++++++ src/index.tsx | 1 + src/render/imageCore.ts | 55 ++++++++++ src/render/renderImage.ts | 13 +++ src/render/renderImage.web.ts | 22 ++++ src/specs/NativeInkpad.ts | 8 ++ src/web/renderDocument.ts | 32 ++++++ 10 files changed, 419 insertions(+), 46 deletions(-) create mode 100644 src/__tests__/fakeCanvas.ts create mode 100644 src/__tests__/imageCore.test.ts create mode 100644 src/__tests__/renderDocument.test.ts create mode 100644 src/render/imageCore.ts create mode 100644 src/render/renderImage.ts create mode 100644 src/render/renderImage.web.ts create mode 100644 src/specs/NativeInkpad.ts create mode 100644 src/web/renderDocument.ts diff --git a/src/__tests__/exportImage.test.ts b/src/__tests__/exportImage.test.ts index 94c5939..92f2a2f 100644 --- a/src/__tests__/exportImage.test.ts +++ b/src/__tests__/exportImage.test.ts @@ -2,8 +2,8 @@ import { beforeEach, describe, expect, it } from 'vitest'; import type { InkDocument, InkStroke } from '../document'; import type { NativeImageOptions } from '../imageOptions'; import type { ImageLike } from '../web/backgroundImage'; -import { type ExportCanvas, type ExportDeps, exportArea, exportImage } from '../web/exportImage'; -import type { MakePath } from '../web/render'; +import { type ExportDeps, exportArea, exportImage } from '../web/exportImage'; +import { calls, depsWith, fakeCanvas, resetFakes } from './fakeCanvas'; const marker = (points: number[]): InkStroke => ({ brush: { type: 'marker', color: '#000000FF', size: 4 }, @@ -29,57 +29,14 @@ const opts = (over: Partial): NativeImageOptions => ({ ...over, }); -type Call = { op: string; args: unknown[]; fillStyle: unknown }; -let calls: Call[]; -let urls: number; - -const fakePath: MakePath = (d) => ({ d }) as unknown as Path2D; const paper = { image: { naturalWidth: 200, naturalHeight: 100 } as ImageLike, fit: 'contain' as const, }; -const fakeCanvas = (blob: Blob | null): ExportCanvas => { - const state = { - fillStyle: '' as unknown, - globalAlpha: 1, - globalCompositeOperation: 'source-over', - }; - const record = - (op: string) => - (...args: unknown[]) => { - calls.push({ op, args, fillStyle: state.fillStyle }); - }; - const ctx = Object.assign(state, { - save() {}, - restore() {}, - setTransform: record('setTransform'), - fillRect: record('fillRect'), - fill: record('fill'), - beginPath() {}, - rect() {}, - clip: record('clip'), - drawImage: (_image: unknown, ...args: unknown[]) => record('drawImage')(...args), - }) as unknown as CanvasRenderingContext2D; - return { - width: 0, - height: 0, - getContext: () => ctx, - toBlob: (callback) => callback(blob), - toDataURL: () => 'data:image/png;base64,AAAA', - }; -}; -const depsWith = (blob: Blob | null): ExportDeps => ({ - createCanvas: () => fakeCanvas(blob), - createObjectURL: () => `blob:fake/${++urls}`, - makePath: fakePath, -}); const deps = depsWith({} as Blob); const failingDeps = depsWith(null); -beforeEach(() => { - calls = []; - urls = 0; -}); +beforeEach(resetFakes); describe('exportArea', () => { it('sizes an untrimmed export to the canvas', () => { diff --git a/src/__tests__/fakeCanvas.ts b/src/__tests__/fakeCanvas.ts new file mode 100644 index 0000000..fe3ce65 --- /dev/null +++ b/src/__tests__/fakeCanvas.ts @@ -0,0 +1,51 @@ +import type { ExportCanvas, ExportDeps } from '../web/exportImage'; +import type { MakePath } from '../web/render'; + +export type Call = { op: string; args: unknown[]; fillStyle: unknown }; + +export const calls: Call[] = []; +let urls = 0; + +export function resetFakes(): void { + calls.length = 0; + urls = 0; +} + +export const fakePath: MakePath = (d) => ({ d }) as unknown as Path2D; + +export const fakeCanvas = (blob: Blob | null): ExportCanvas => { + const state = { + fillStyle: '' as unknown, + globalAlpha: 1, + globalCompositeOperation: 'source-over', + }; + const record = + (op: string) => + (...args: unknown[]) => { + calls.push({ op, args, fillStyle: state.fillStyle }); + }; + const ctx = Object.assign(state, { + save() {}, + restore() {}, + setTransform: record('setTransform'), + fillRect: record('fillRect'), + fill: record('fill'), + beginPath() {}, + rect() {}, + clip: record('clip'), + drawImage: (_image: unknown, ...args: unknown[]) => record('drawImage')(...args), + }) as unknown as CanvasRenderingContext2D; + return { + width: 0, + height: 0, + getContext: () => ctx, + toBlob: (callback) => callback(blob), + toDataURL: () => 'data:image/png;base64,AAAA', + }; +}; + +export const depsWith = (blob: Blob | null): ExportDeps => ({ + createCanvas: () => fakeCanvas(blob), + createObjectURL: () => `blob:fake/${++urls}`, + makePath: fakePath, +}); diff --git a/src/__tests__/imageCore.test.ts b/src/__tests__/imageCore.test.ts new file mode 100644 index 0000000..5c4e196 --- /dev/null +++ b/src/__tests__/imageCore.test.ts @@ -0,0 +1,150 @@ +import { describe, expect, it, vi } from 'vitest'; +import type { InkDocument } from '../document'; +import { ErrorCode, InkpadError } from '../errors'; +import { toNativeImageOptions, withBackground } from '../imageOptions'; +import type { BackgroundResolvers } from '../render/core'; +import { + nativeRender, + oneAtATime, + type RenderImageDeps, + renderImageWith, +} from '../render/imageCore'; +import type { ImageResult } from '../types'; + +const doc: InkDocument = { + version: 1, + size: { width: 300, height: 200 }, + strokes: [ + { + brush: { type: 'pen', color: '#000000FF', size: 4 }, + input: 'touch', + points: [10, 10, 0, -1, -1, -1, 50, 10, 16, -1, -1, -1], + }, + ], +}; +const result: ImageResult = { uri: 'file:///a.png', width: 2, height: 1 }; +const fixed: BackgroundResolvers = { + color: () => '#FFFFFFFF', + image: () => 'file:///p.png', +}; +const nativeOptions = withBackground(toNativeImageOptions({}, 2), { + color: undefined, + uri: undefined, + fit: 'contain', +}); + +const spyDeps = () => { + const render = vi.fn(async () => result); + return { render, deps: { defaultScale: 3, render } }; +}; + +describe('renderImageWith', () => { + it('passes the document and the canvas export options to render', async () => { + const { render, deps } = spyDeps(); + const options = { maxSize: 160, background: { color: 'c', image: 'i', fit: 'cover' as const } }; + await expect(renderImageWith(doc, options, fixed, deps)).resolves.toBe(result); + expect(render).toHaveBeenCalledWith(doc, { + format: 'png', + quality: 0.9, + scale: 3, + trim: false, + padding: 0, + background: true, + base64: false, + maxSize: 160, + backgroundColor: '#FFFFFFFF', + backgroundImageUri: 'file:///p.png', + backgroundFit: 'cover', + }); + }); + + it('sends a transparent background when none is given', async () => { + const { render, deps } = spyDeps(); + await renderImageWith(doc, undefined, fixed, deps); + expect(render.mock.calls[0]?.[1]).toMatchObject({ + background: true, + backgroundColor: '', + backgroundImageUri: '', + backgroundFit: 'contain', + }); + }); + + it('rejects a bad document without calling render', async () => { + const { render, deps } = spyDeps(); + let call: Promise | undefined; + expect(() => { + call = renderImageWith(null, undefined, fixed, deps); + }).not.toThrow(); + await expect(call).rejects.toMatchObject({ code: 'E_INVALID_DOCUMENT' }); + expect(render).not.toHaveBeenCalled(); + }); + + it('rejects E_IMAGE_LOAD for an unusable source', async () => { + const { render, deps } = spyDeps(); + const unusable = { color: fixed.color, image: () => undefined }; + await expect( + renderImageWith(doc, { background: { image: 'i' } }, unusable, deps), + ).rejects.toMatchObject({ code: 'E_IMAGE_LOAD' }); + expect(render).not.toHaveBeenCalled(); + }); +}); + +describe('nativeRender', () => { + it('rejects E_EXPORT_FAILED when the module is missing', async () => { + await expect(nativeRender(null)(doc, nativeOptions)).rejects.toMatchObject({ + code: 'E_EXPORT_FAILED', + message: 'the react-native-inkpad native module is missing; rebuild the app', + }); + }); + + it("parses the module's JSON", async () => { + const renderImage = vi.fn(async () => '{"uri":"file:///a.png","width":2,"height":1}'); + await expect(nativeRender({ renderImage })(doc, nativeOptions)).resolves.toEqual({ + uri: 'file:///a.png', + width: 2, + height: 1, + }); + expect(renderImage).toHaveBeenCalledWith(JSON.stringify(doc), JSON.stringify(nativeOptions)); + }); + + it('maps a native rejection code', async () => { + const renderImage = async (): Promise => { + throw Object.assign(new Error('nothing to trim'), { code: 'E_EMPTY' }); + }; + const call = nativeRender({ renderImage })(doc, nativeOptions); + await expect(call).rejects.toBeInstanceOf(InkpadError); + await expect(call).rejects.toMatchObject({ code: 'E_EMPTY', message: 'nothing to trim' }); + }); +}); + +describe('oneAtATime', () => { + const flush = () => new Promise((resolve) => setTimeout(resolve, 0)); + + it('starts each render after the previous one settles', async () => { + const finish: Array<() => void> = []; + const render = vi.fn( + () => new Promise((resolve) => finish.push(() => resolve(result))), + ); + const queued = oneAtATime(render); + const calls = [1, 2, 3].map(() => queued(doc, nativeOptions)); + for (let i = 0; i < 3; i++) { + await flush(); + expect(render).toHaveBeenCalledTimes(i + 1); + finish[i]?.(); + } + await expect(Promise.all(calls)).resolves.toEqual([result, result, result]); + expect(render).toHaveBeenNthCalledWith(3, doc, nativeOptions); + }); + + it('runs the next render after one fails', async () => { + const render = vi + .fn() + .mockRejectedValueOnce(new InkpadError(ErrorCode.EXPORT_FAILED, 'no 2d context')) + .mockResolvedValueOnce(result); + const queued = oneAtATime(render); + const failed = queued(doc, nativeOptions); + const next = queued(doc, nativeOptions); + await expect(failed).rejects.toMatchObject({ code: 'E_EXPORT_FAILED' }); + await expect(next).resolves.toBe(result); + }); +}); diff --git a/src/__tests__/renderDocument.test.ts b/src/__tests__/renderDocument.test.ts new file mode 100644 index 0000000..e33c8dc --- /dev/null +++ b/src/__tests__/renderDocument.test.ts @@ -0,0 +1,84 @@ +import { beforeEach, describe, expect, it } from 'vitest'; +import type { InkDocument } from '../document'; +import { toNativeImageOptions, withBackground } from '../imageOptions'; +import type { ImageLike } from '../web/backgroundImage'; +import { type ExportCanvas, exportImage } from '../web/exportImage'; +import { renderDocumentImage } from '../web/renderDocument'; +import { calls, depsWith, fakeCanvas, resetFakes } from './fakeCanvas'; + +const doc: InkDocument = { + version: 1, + size: { width: 300, height: 200 }, + strokes: [ + { + brush: { type: 'marker', color: '#000000FF', size: 4 }, + input: 'touch', + points: [10, 10, 0, -1, -1, -1, 50, 10, 16, -1, -1, -1], + }, + ], +}; +const empty: InkDocument = { ...doc, strokes: [] }; + +const imageThat = (decode: () => Promise) => (): ImageLike => ({ + src: '', + crossOrigin: null, + naturalWidth: 200, + naturalHeight: 100, + decode, +}); +const decodes = imageThat(() => Promise.resolve()); +const deps = { ...depsWith({} as Blob), createImage: decodes }; + +beforeEach(resetFakes); + +describe('renderDocumentImage', () => { + it('matches exportImage for the same document', async () => { + const image = decodes(); + const base = toNativeImageOptions({ scale: 2, trim: { padding: 4 } }, 1); + const expected = await exportImage(doc, base, '#FF0000FF', deps, { image, fit: 'cover' }); + const expectedCalls = calls.splice(0); + const options = withBackground(base, { + color: '#FF0000FF', + uri: 'https://x/p.png', + fit: 'cover', + }); + const actual = await renderDocumentImage(doc, options, deps); + expect(actual).toMatchObject({ width: expected.width, height: expected.height }); + expect(calls).toEqual(expectedCalls); + expect(calls.some((call) => call.op === 'drawImage')).toBe(true); + }); + + it('renders an empty document at its size', async () => { + let canvas: ExportCanvas | undefined; + const sized = { + ...deps, + createCanvas: () => { + canvas = fakeCanvas({} as Blob); + return canvas; + }, + }; + const options = withBackground(toNativeImageOptions({ scale: 2 }, 1), { + color: undefined, + uri: undefined, + fit: 'contain', + }); + await expect(renderDocumentImage(empty, options, sized)).resolves.toMatchObject({ + width: 600, + height: 400, + }); + expect(canvas).toMatchObject({ width: 600, height: 400 }); + }); + + it('rejects E_IMAGE_LOAD when the image fails to decode', async () => { + const broken = imageThat(() => Promise.reject(new Error('broken'))); + const options = withBackground(toNativeImageOptions({}, 1), { + color: undefined, + uri: 'https://x/p.png', + fit: 'contain', + }); + await expect( + renderDocumentImage(doc, options, { ...deps, createImage: broken }), + ).rejects.toMatchObject({ code: 'E_IMAGE_LOAD' }); + expect(calls).toEqual([]); + }); +}); diff --git a/src/index.tsx b/src/index.tsx index 7ef6103..85f62ab 100644 --- a/src/index.tsx +++ b/src/index.tsx @@ -2,6 +2,7 @@ export type { InkBrush, InkDocument, InkStroke, InputType } from './document'; export { validateDocument } from './document'; export { ErrorCode, InkpadError } from './errors'; export { InkCanvas } from './InkCanvas'; +export { renderImage } from './render/renderImage'; export { renderSVG } from './render/renderSVG'; export type { Background, diff --git a/src/render/imageCore.ts b/src/render/imageCore.ts new file mode 100644 index 0000000..60bb8f9 --- /dev/null +++ b/src/render/imageCore.ts @@ -0,0 +1,55 @@ +import { type InkDocument, validateDocument } from '../document'; +import { ErrorCode, InkpadError, toInkpadError } from '../errors'; +import { toNativeImageOptions, withBackground } from '../imageOptions'; +import type { Spec } from '../specs/NativeInkpad'; +import type { ImageOptions, ImageResult } from '../types'; +import { type BackgroundInput, type BackgroundResolvers, resolveBackground } from './core'; + +export type NativeRenderOptions = ReturnType; + +export type RenderImageDeps = { + defaultScale: number; + render(doc: InkDocument, options: NativeRenderOptions): Promise; +}; + +export async function renderImageWith( + doc: unknown, + options: (Omit & { background?: BackgroundInput }) | undefined, + resolvers: BackgroundResolvers, + deps: RenderImageDeps, +): Promise { + const valid = validateDocument(doc); + const { background, ...rest } = options ?? {}; + const { color, uri, fit } = resolveBackground(background, resolvers); + const native = toNativeImageOptions({ ...rest, background: true }, deps.defaultScale); + return deps.render(valid, withBackground(native, { color, uri, fit })); +} + +/** Starts each render after the previous one settles, as the native renderers do. */ +export function oneAtATime(render: RenderImageDeps['render']): RenderImageDeps['render'] { + let last: Promise = Promise.resolve(); + return (doc, options) => { + const next = last.then(() => render(doc, options)); + last = next.catch(() => {}); + return next; + }; +} + +export function nativeRender(module: Pick | null): RenderImageDeps['render'] { + return async (doc, options) => { + if (!module) { + throw new InkpadError( + ErrorCode.EXPORT_FAILED, + 'the react-native-inkpad native module is missing; rebuild the app', + ); + } + let payload: string; + try { + payload = await module.renderImage(JSON.stringify(doc), JSON.stringify(options)); + } catch (error) { + const failure = error as { code?: unknown; message?: unknown } | null; + throw toInkpadError(String(failure?.code), String(failure?.message ?? error)); + } + return JSON.parse(payload) as ImageResult; + }; +} diff --git a/src/render/renderImage.ts b/src/render/renderImage.ts new file mode 100644 index 0000000..173abab --- /dev/null +++ b/src/render/renderImage.ts @@ -0,0 +1,13 @@ +import { PixelRatio } from 'react-native'; +import type { InkDocument } from '../document'; +import NativeInkpad from '../specs/NativeInkpad'; +import type { ImageResult, RenderImageOptions } from '../types'; +import { nativeRender, renderImageWith } from './imageCore'; +import { appResolvers } from './resolvers'; + +const render = nativeRender(NativeInkpad ?? null); + +/** Renders a stored document to an image without mounting a canvas. */ +export function renderImage(doc: InkDocument, options?: RenderImageOptions): Promise { + return renderImageWith(doc, options, appResolvers, { defaultScale: PixelRatio.get(), render }); +} diff --git a/src/render/renderImage.web.ts b/src/render/renderImage.web.ts new file mode 100644 index 0000000..eaa9a3c --- /dev/null +++ b/src/render/renderImage.web.ts @@ -0,0 +1,22 @@ +import type { InkDocument } from '../document'; +import type { ImageResult, RenderImageOptions } from '../types'; +import { renderDocumentImage } from '../web/renderDocument'; +import { oneAtATime, renderImageWith } from './imageCore'; +import { appResolvers } from './resolvers'; + +// One at a time, so a list of thumbnails holds one full-size canvas while toBlob is pending. +const render = oneAtATime((valid, native) => + renderDocumentImage(valid, native, { + createCanvas: () => document.createElement('canvas'), + createObjectURL: (blob) => URL.createObjectURL(blob), + createImage: () => new Image(), + }), +); + +/** Renders a stored document to an image without mounting a canvas. */ +export function renderImage(doc: InkDocument, options?: RenderImageOptions): Promise { + return renderImageWith(doc, options, appResolvers, { + defaultScale: window.devicePixelRatio || 1, + render, + }); +} diff --git a/src/specs/NativeInkpad.ts b/src/specs/NativeInkpad.ts new file mode 100644 index 0000000..787fbea --- /dev/null +++ b/src/specs/NativeInkpad.ts @@ -0,0 +1,8 @@ +import type { TurboModule } from 'react-native'; +import { TurboModuleRegistry } from 'react-native'; + +export interface Spec extends TurboModule { + renderImage(documentJson: string, optionsJson: string): Promise; +} + +export default TurboModuleRegistry.get('Inkpad'); diff --git a/src/web/renderDocument.ts b/src/web/renderDocument.ts new file mode 100644 index 0000000..9a60aa3 --- /dev/null +++ b/src/web/renderDocument.ts @@ -0,0 +1,32 @@ +import type { InkDocument } from '../document'; +import type { InkpadError } from '../errors'; +import type { NativeRenderOptions } from '../render/imageCore'; +import type { ImageResult } from '../types'; +import { BackgroundImage, type ImageLike } from './backgroundImage'; +import { type ExportDeps, exportImage } from './exportImage'; + +export async function renderDocumentImage( + doc: InkDocument, + options: NativeRenderOptions, + deps: ExportDeps & { createImage(): ImageLike }, +): Promise { + let image: ImageLike | null = null; + if (options.backgroundImageUri) { + const failures: InkpadError[] = []; + const loader = new BackgroundImage( + deps.createImage, + () => {}, + (error) => failures.push(error), + ); + loader.set(options.backgroundImageUri); + image = await loader.ready(); + if (failures[0]) throw failures[0]; + } + return exportImage( + doc, + options, + options.backgroundColor || undefined, + deps, + image ? { image, fit: options.backgroundFit } : undefined, + ); +} From baa00a4d775f6e9fb33ca4f039b7ca54a7dd401b Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Wed, 4 Nov 2026 18:46:35 +0100 Subject: [PATCH 05/17] feat(android): render documents in a TurboModule --- .../sectiontn/inkpad/DocumentRendererTest.kt | 273 ++++++++++++++++++ .../inkpad/InkpadViewCommandsTest.kt | 2 +- .../me/sectiontn/inkpad/DocumentRenderer.kt | 36 +++ .../java/me/sectiontn/inkpad/ImageExporter.kt | 14 +- .../me/sectiontn/inkpad/InkpadExecutors.kt | 14 + .../java/me/sectiontn/inkpad/InkpadModule.kt | 18 ++ .../java/me/sectiontn/inkpad/InkpadView.kt | 14 +- .../me/sectiontn/inkpad/InkpadViewPackage.kt | 17 +- 8 files changed, 371 insertions(+), 17 deletions(-) create mode 100644 android/src/androidTest/java/me/sectiontn/inkpad/DocumentRendererTest.kt create mode 100644 android/src/main/java/me/sectiontn/inkpad/DocumentRenderer.kt create mode 100644 android/src/main/java/me/sectiontn/inkpad/InkpadExecutors.kt create mode 100644 android/src/main/java/me/sectiontn/inkpad/InkpadModule.kt diff --git a/android/src/androidTest/java/me/sectiontn/inkpad/DocumentRendererTest.kt b/android/src/androidTest/java/me/sectiontn/inkpad/DocumentRendererTest.kt new file mode 100644 index 0000000..14322c5 --- /dev/null +++ b/android/src/androidTest/java/me/sectiontn/inkpad/DocumentRendererTest.kt @@ -0,0 +1,273 @@ +package me.sectiontn.inkpad + +import android.content.Context +import android.graphics.Bitmap +import android.graphics.BitmapFactory +import android.graphics.Color +import android.net.Uri +import android.util.Base64 +import androidx.test.ext.junit.runners.AndroidJUnit4 +import androidx.test.platform.app.InstrumentationRegistry +import com.facebook.react.soloader.OpenSourceMergedSoMapping +import com.facebook.react.uimanager.ThemedReactContext +import com.facebook.soloader.SoLoader +import org.json.JSONObject +import org.junit.Assert.assertEquals +import org.junit.Assert.assertTrue +import org.junit.Before +import org.junit.Test +import org.junit.runner.RunWith +import java.io.ByteArrayOutputStream +import java.io.File +import java.util.Collections +import java.util.concurrent.CountDownLatch +import java.util.concurrent.TimeUnit + +@RunWith(AndroidJUnit4::class) +class DocumentRendererTest { + private val instrumentation = InstrumentationRegistry.getInstrumentation() + private lateinit var base: Context + private lateinit var context: RecordingReactContext + + @Before + fun createContext() { + base = instrumentation.targetContext + // Events build their payloads with React Native's native maps. + SoLoader.init(base, OpenSourceMergedSoMapping) + context = RecordingReactContext(base) + } + + @Test + fun matchesTheCanvasExport() { + val density = base.resources.displayMetrics.density + val (view, doc) = drawnCanvas() + + val cases = listOf( + "{}", + """{"trim":true,"padding":8}""", + """{"backgroundColor":"#FFEEDDFF"}""", + """{"maxSize":160}""", + JSONObject().put("backgroundImageUri", paper).put("backgroundFit", "contain").toString(), + ) + for ((i, case) in cases.withIndex()) { + val options = options(case, density) + val requestId = 10 + i + onMain { view.exportImage(requestId, options) } + settle() + val canvas = decode(payload(requestId)) + val rendered = decode(render(doc, options).getOrThrow()) + assertTrue("$case differs from the canvas export", canvas.sameAs(rendered)) + if (case.contains("trim")) assertTrue(rendered.width < 320 * density) + if (case.contains("backgroundColor")) assertEquals(0xFFFFEEDD.toInt(), rendered.getPixel(0, 0)) + if (case.contains("maxSize")) { + assertEquals(160, maxOf(canvas.width, canvas.height)) + assertEquals(160, maxOf(rendered.width, rendered.height)) + } + // The center of the canvas is inside the contained image and clear of every stroke. + if (case.contains("backgroundImageUri")) { + assertEquals(255, Color.alpha(rendered.getPixel(rendered.width / 2, rendered.height / 2))) + } + } + } + + @Test + fun rendersAnEmptyDocumentAtItsSize() { + val bitmap = decode(render(EMPTY, options("{}", 2f)).getOrThrow()) + + assertEquals(640, bitmap.width) + assertEquals(480, bitmap.height) + val pixels = IntArray(bitmap.width * bitmap.height) + bitmap.getPixels(pixels, 0, bitmap.width, 0, 0, bitmap.width, bitmap.height) + assertTrue(pixels.all { it == 0 }) + } + + @Test + fun rejectsTrimOnAnEmptyDocument() { + val result = render(EMPTY, options("""{"trim":true}""", 2f)) + + assertEquals(ErrorCodes.EMPTY, (result.exceptionOrNull() as? InkpadException)?.code) + } + + @Test + fun rejectsABackgroundThatFailsToLoad() { + val result = render(EMPTY, options("""{"backgroundImageUri":"file:///nonexistent.png"}""", 2f)) + + assertEquals(ErrorCodes.IMAGE_LOAD, (result.exceptionOrNull() as? InkpadException)?.code) + } + + @Test + fun settlesManyRendersAtOnce() = settlesManyRenders(options("{}", 1f)) + + @Test + fun settlesManyRendersWithABackground() = + settlesManyRenders(options(JSONObject().put("backgroundImageUri", paper).toString(), 1f)) + + @Test + fun exportsAndRendersAtTheSameTime() { + val (view, doc) = drawnCanvas() + val options = options("{}", 1f) + onMain { view.exportImage(10, options) } + settle() + val reference = decode(payload(10)) + val count = 20 + val latch = CountDownLatch(count) + val rendered = Collections.synchronizedList(mutableListOf>()) + onMain { + repeat(count) { i -> + view.exportImage(100 + i, options) + DocumentRenderer.render(context, doc, options) { result -> + rendered += result + latch.countDown() + } + } + } + + assertTrue("renders still pending after 30 s", latch.await(30, TimeUnit.SECONDS)) + settle() + repeat(count) { i -> + val canvas = decode(payload(100 + i)) + assertTrue("canvas export $i differs", reference.sameAs(canvas)) + canvas.recycle() + } + rendered.forEachIndexed { i, result -> + val bitmap = decode(result.getOrThrow()) + assertTrue("render $i differs", reference.sameAs(bitmap)) + bitmap.recycle() + } + } + + private fun settlesManyRenders(options: String) { + val count = 20 + val latch = CountDownLatch(count) + val results = Collections.synchronizedList(mutableListOf>()) + val threads = Collections.synchronizedSet(mutableSetOf()) + val doc = drawing() + repeat(count) { + DocumentRenderer.render(context, doc, options) { result -> + results += result + threads += Thread.currentThread() + latch.countDown() + } + } + + assertTrue("renders still pending after 30 s", latch.await(30, TimeUnit.SECONDS)) + val uris = results.map { JSONObject(it.getOrThrow()).getString("uri") } + assertEquals(count, uris.toSet().size) + val renderer = InkpadExecutors.renderer.submit { Thread.currentThread() }.get() + assertEquals(setOf(renderer), threads.toSet()) + uris.forEach { File(Uri.parse(it).path!!).delete() } + } + + // A laid out 320 x 240 dp canvas that holds the drawing, and the document it saved. + private fun drawnCanvas(): Pair { + val density = base.resources.displayMetrics.density + val width = 320 * density + val height = 240 * density + assertTrue("320 x 240 dp is $width x $height px", width % 1f == 0f && height % 1f == 0f) + lateinit var view: InkpadView + onMain { + view = InkpadView(ThemedReactContext(context, base, null, -1)) + view.layout(0, 0, width.toInt(), height.toInt()) + view.setStrokes(1, drawing()) + view.getStrokes(2) + } + settle() + val doc = payload(2) + assertEquals(4, DocumentJson.parse(doc).strokes.size) + onMain { view.setStrokes(3, doc) } + settle() + return view to doc + } + + private fun onMain(block: () -> Unit) = instrumentation.runOnMainSync(block) + + // Two rounds, since an answer that lands on the main thread can start the next background job. + private fun settle() = repeat(2) { + InkpadExecutors.worker.submit {}.get() + InkpadExecutors.exporter.submit {}.get() + instrumentation.waitForIdleSync() + } + + private fun payload(requestId: Int): String { + var payload: String? = null + onMain { + payload = context.events + .firstOrNull { it.hasKey("requestId") && it.getInt("requestId") == requestId } + ?.getString("payload") + } + return checkNotNull(payload) { "no answer to request $requestId" } + } + + private fun render(document: String, options: String): Result { + val latch = CountDownLatch(1) + var result: Result? = null + DocumentRenderer.render(context, document, options) { + result = it + latch.countDown() + } + assertTrue("render still pending after 30 s", latch.await(30, TimeUnit.SECONDS)) + return result!! + } + + private fun decode(json: String): Bitmap { + val file = File(Uri.parse(JSONObject(json).getString("uri")).path!!) + val bitmap = checkNotNull(BitmapFactory.decodeFile(file.path)) { "could not decode $file" } + file.delete() + return bitmap + } + + // The same background keys renderImage and toImage send, empty when unset. + private fun options(case: String, scale: Float): String { + val options = JSONObject() + .put("scale", scale.toDouble()) + .put("background", true) + .put("backgroundColor", "") + .put("backgroundImageUri", "") + .put("backgroundFit", "contain") + val extra = JSONObject(case) + for (key in extra.keys()) options.put(key, extra.get(key)) + return options.toString() + } + + private fun drawing(): String = DocumentJson.write( + Doc( + 320f, + 240f, + listOf( + stroke(BrushType.PEN, InputType.TOUCH, 0xFF000000.toInt(), 3f, 40f), + stroke(BrushType.PEN, InputType.STYLUS, 0xFF1E40AF.toInt(), 4f, 90f), + stroke(BrushType.MARKER, InputType.TOUCH, 0xFFB91C1C.toInt(), 8f, 140f), + stroke(BrushType.HIGHLIGHTER, InputType.TOUCH, 0xFFFACC15.toInt(), 16f, 190f), + ), + ), + ) + + private fun stroke(type: BrushType, input: InputType, color: Int, size: Float, y: Float): DocStroke { + val stride = DocumentJson.STRIDE + val points = FloatArray(POINTS * stride) { k -> + val i = k / stride + when (k % stride) { + 0 -> 30f + i * 10 + 1 -> y + if (i % 2 == 0) 0f else 8f + 2 -> i * 8f + 3 -> if (input == InputType.STYLUS) 0.2f + 0.7f * i / (POINTS - 1) else -1f + else -> -1f + } + } + return DocStroke(type, color, size, input, points) + } + + private companion object { + const val POINTS = 24 + val EMPTY = DocumentJson.write(Doc(320f, 240f, emptyList())) + + val paper: String by lazy { + val bitmap = Bitmap.createBitmap(4, 4, Bitmap.Config.ARGB_8888).apply { eraseColor(0xFF2E7D32.toInt()) } + val bytes = ByteArrayOutputStream().use { out -> + bitmap.compress(Bitmap.CompressFormat.PNG, 100, out) + out.toByteArray() + } + "data:image/png;base64," + Base64.encodeToString(bytes, Base64.NO_WRAP) + } + } +} diff --git a/android/src/androidTest/java/me/sectiontn/inkpad/InkpadViewCommandsTest.kt b/android/src/androidTest/java/me/sectiontn/inkpad/InkpadViewCommandsTest.kt index b499963..6920e2d 100644 --- a/android/src/androidTest/java/me/sectiontn/inkpad/InkpadViewCommandsTest.kt +++ b/android/src/androidTest/java/me/sectiontn/inkpad/InkpadViewCommandsTest.kt @@ -94,7 +94,7 @@ class InkpadViewCommandsTest { // Two rounds, since a load that lands on the main thread can start a save on the document thread. private fun settle() = repeat(2) { - InkpadView.WORKER.submit {}.get() + InkpadExecutors.worker.submit {}.get() instrumentation.waitForIdleSync() } diff --git a/android/src/main/java/me/sectiontn/inkpad/DocumentRenderer.kt b/android/src/main/java/me/sectiontn/inkpad/DocumentRenderer.kt new file mode 100644 index 0000000..b2508d3 --- /dev/null +++ b/android/src/main/java/me/sectiontn/inkpad/DocumentRenderer.kt @@ -0,0 +1,36 @@ +package me.sectiontn.inkpad + +import android.content.Context +import android.graphics.Bitmap +import android.graphics.Color + +internal object DocumentRenderer { + fun render(context: Context, documentJson: String, optionsJson: String, done: (Result) -> Unit) { + InkpadExecutors.renderer.execute { done(runCatching { draw(context, documentJson, optionsJson) }) } + } + + private fun draw(context: Context, documentJson: String, optionsJson: String): String { + val options = ExportOptions.parse(optionsJson) + val image = options.backgroundImageUri?.takeIf { it.isNotEmpty() }?.let { load(context, it) } + try { + val doc = DocumentJson.parse(documentJson) + val metrics = context.resources.displayMetrics + val unitLengthCm = InkConverter.strokeUnitLengthCm(metrics.density, metrics.xdpi, metrics.ydpi) + val strokes = doc.strokes.map { InkConverter.toInk(it, unitLengthCm) } + val color = options.backgroundColor ?: Color.TRANSPARENT + val fit = options.backgroundFit ?: BackgroundFit.CONTAIN + return ImageExporter.export(context, strokes, doc.width, doc.height, color, image, fit, options) + } finally { + image?.recycle() + } + } + + private fun load(context: Context, uri: String): Bitmap = + runCatching { BackgroundLoader.load(context, uri) }.getOrElse { error -> + throw error as? InkpadException + ?: InkpadException( + ErrorCodes.IMAGE_LOAD, + "could not load the background image $uri: ${error.message ?: error.javaClass.simpleName}", + ) + } +} diff --git a/android/src/main/java/me/sectiontn/inkpad/ImageExporter.kt b/android/src/main/java/me/sectiontn/inkpad/ImageExporter.kt index 101058a..7366a10 100644 --- a/android/src/main/java/me/sectiontn/inkpad/ImageExporter.kt +++ b/android/src/main/java/me/sectiontn/inkpad/ImageExporter.kt @@ -17,8 +17,13 @@ import java.util.UUID import kotlin.math.roundToInt internal object ImageExporter { - private val renderer by lazy { CanvasStrokeRenderer.create() } - private val imagePaint = Paint(Paint.FILTER_BITMAP_FLAG) + // One per thread: Ink renderers keep unsynchronized scratch state, and exports and renders run at once. + private val renderer = object : ThreadLocal() { + override fun initialValue(): CanvasStrokeRenderer = CanvasStrokeRenderer.create() + } + private val imagePaint = object : ThreadLocal() { + override fun initialValue() = Paint(Paint.FILTER_BITMAP_FLAG) + } fun export( context: Context, @@ -56,7 +61,8 @@ internal object ImageExporter { } canvas.concat(transform) if (options.background && image != null) drawImage(canvas, image, width, height, fit) - for (item in strokes) renderer.draw(canvas, item.stroke, transform) + val strokeRenderer = renderer.get()!! + for (item in strokes) strokeRenderer.draw(canvas, item.stroke, transform) val bytes = ByteArrayOutputStream().use { out -> val format = if (options.jpeg) Bitmap.CompressFormat.JPEG else Bitmap.CompressFormat.PNG bitmap.compress(format, (options.quality * 100).roundToInt(), out) @@ -79,7 +85,7 @@ internal object ImageExporter { val rect = Fit.rect(image.width.toFloat(), image.height.toFloat(), width, height, fit) val saved = canvas.save() canvas.clipRect(0f, 0f, width, height) - canvas.drawBitmap(image, null, RectF(rect.x, rect.y, rect.x + rect.width, rect.y + rect.height), imagePaint) + canvas.drawBitmap(image, null, RectF(rect.x, rect.y, rect.x + rect.width, rect.y + rect.height), imagePaint.get()) canvas.restoreToCount(saved) } } diff --git a/android/src/main/java/me/sectiontn/inkpad/InkpadExecutors.kt b/android/src/main/java/me/sectiontn/inkpad/InkpadExecutors.kt new file mode 100644 index 0000000..4e038f9 --- /dev/null +++ b/android/src/main/java/me/sectiontn/inkpad/InkpadExecutors.kt @@ -0,0 +1,14 @@ +package me.sectiontn.inkpad + +import java.util.concurrent.ExecutorService +import java.util.concurrent.Executors + +internal object InkpadExecutors { + // Saves and loads documents. Exports have their own thread, since they can wait on the background image. + val worker: ExecutorService = Executors.newSingleThreadExecutor() + val exporter: ExecutorService = Executors.newSingleThreadExecutor() + val loader: ExecutorService = Executors.newCachedThreadPool() + + // Runs renderImage jobs one at a time, background load included, so a list of thumbnails holds one image at once. + val renderer: ExecutorService = Executors.newSingleThreadExecutor() +} diff --git a/android/src/main/java/me/sectiontn/inkpad/InkpadModule.kt b/android/src/main/java/me/sectiontn/inkpad/InkpadModule.kt new file mode 100644 index 0000000..45b3c9a --- /dev/null +++ b/android/src/main/java/me/sectiontn/inkpad/InkpadModule.kt @@ -0,0 +1,18 @@ +package me.sectiontn.inkpad + +import com.facebook.react.bridge.Promise +import com.facebook.react.bridge.ReactApplicationContext + +class InkpadModule(context: ReactApplicationContext) : NativeInkpadSpec(context) { + override fun renderImage(documentJson: String, optionsJson: String, promise: Promise) { + DocumentRenderer.render(reactApplicationContext, documentJson, optionsJson) { result -> + result.fold( + onSuccess = promise::resolve, + onFailure = { error -> + val code = (error as? InkpadException)?.code ?: ErrorCodes.EXPORT_FAILED + promise.reject(code, error.message ?: "export failed", error) + }, + ) + } + } +} diff --git a/android/src/main/java/me/sectiontn/inkpad/InkpadView.kt b/android/src/main/java/me/sectiontn/inkpad/InkpadView.kt index a6576a7..fc4aee7 100644 --- a/android/src/main/java/me/sectiontn/inkpad/InkpadView.kt +++ b/android/src/main/java/me/sectiontn/inkpad/InkpadView.kt @@ -24,7 +24,6 @@ import com.facebook.react.bridge.WritableMap import com.facebook.react.uimanager.BackgroundStyleApplicator import com.facebook.react.uimanager.ThemedReactContext import com.facebook.react.uimanager.UIManagerHelper -import java.util.concurrent.Executors import java.util.concurrent.Future import java.util.concurrent.FutureTask @@ -218,7 +217,7 @@ class InkpadView(private val reactContext: ThemedReactContext) : FrameLayout(rea result.getOrNull() } imageLoad = load - LOADER.execute(load) + InkpadExecutors.loader.execute(load) } private fun finishBackground(generation: Int, result: Result) { @@ -266,7 +265,7 @@ class InkpadView(private val reactContext: ThemedReactContext) : FrameLayout(rea val canvasWidth = width / density val canvasHeight = height / density // A long drawing serializes to a large JSON string, so it belongs off the UI thread like the export. - WORKER.execute { + InkpadExecutors.worker.execute { val result = runCatching { DocumentJson.write(Doc(canvasWidth, canvasHeight, snapshot.map(InkConverter::fromInk))) } @@ -287,7 +286,7 @@ class InkpadView(private val reactContext: ThemedReactContext) : FrameLayout(rea val unitLengthCm = InkConverter.strokeUnitLengthCm(density, metrics.xdpi, metrics.ydpi) val slot = commands.reserve() // Loading a saved drawing builds an ink stroke per point, which is as heavy as reading one back. - WORKER.execute { + InkpadExecutors.worker.execute { val result = runCatching { DocumentJson.parse(json ?: "").strokes.map { InkConverter.toInk(it, unitLengthCm) } } @@ -321,7 +320,7 @@ class InkpadView(private val reactContext: ThemedReactContext) : FrameLayout(rea val snapshot = strokes.toList() val canvasWidth = width / density val canvasHeight = height / density - EXPORTER.execute { + InkpadExecutors.exporter.execute { val image = runCatching { load?.get() }.getOrNull() val result = runCatching { ImageExporter.export(reactContext, snapshot, canvasWidth, canvasHeight, color, image, fit, options) @@ -385,10 +384,5 @@ class InkpadView(private val reactContext: ThemedReactContext) : FrameLayout(rea companion object { private const val ERASER_RADIUS = 10f - - // Saves and loads documents. Exports have their own thread, since they can wait on the background image. - internal val WORKER = Executors.newSingleThreadExecutor() - private val EXPORTER = Executors.newSingleThreadExecutor() - private val LOADER = Executors.newCachedThreadPool() } } diff --git a/android/src/main/java/me/sectiontn/inkpad/InkpadViewPackage.kt b/android/src/main/java/me/sectiontn/inkpad/InkpadViewPackage.kt index 251c918..ec1c15b 100644 --- a/android/src/main/java/me/sectiontn/inkpad/InkpadViewPackage.kt +++ b/android/src/main/java/me/sectiontn/inkpad/InkpadViewPackage.kt @@ -3,6 +3,7 @@ package me.sectiontn.inkpad import com.facebook.react.BaseReactPackage import com.facebook.react.bridge.NativeModule import com.facebook.react.bridge.ReactApplicationContext +import com.facebook.react.module.model.ReactModuleInfo import com.facebook.react.module.model.ReactModuleInfoProvider import com.facebook.react.uimanager.ViewManager @@ -10,7 +11,19 @@ class InkpadViewPackage : BaseReactPackage() { override fun createViewManagers(reactContext: ReactApplicationContext): List> = listOf(InkpadViewManager()) - override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? = null + override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? = + if (name == NativeInkpadSpec.NAME) InkpadModule(reactContext) else null - override fun getReactModuleInfoProvider() = ReactModuleInfoProvider { emptyMap() } + override fun getReactModuleInfoProvider() = ReactModuleInfoProvider { + mapOf( + NativeInkpadSpec.NAME to ReactModuleInfo( + name = NativeInkpadSpec.NAME, + className = InkpadModule::class.java.name, + canOverrideExistingModule = false, + needsEagerInit = false, + isCxxModule = false, + isTurboModule = true, + ), + ) + } } From d9422662a91c0627602131fc49045eb90082e431 Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Wed, 4 Nov 2026 19:14:11 +0100 Subject: [PATCH 06/17] feat(ios): render documents in a TurboModule --- .github/workflows/ci.yml | 4 +- ios/INKDocumentRenderer.h | 16 ++ ios/INKDocumentRenderer.m | 85 ++++++++ ios/INKInkpadModule.h | 8 + ios/INKInkpadModule.mm | 34 +++ ios/INKStrokeCodec.h | 2 + ios/INKStrokeCodec.m | 10 + package.json | 3 + src/__tests__/iosRender.test.ts | 61 ++++++ src/__tests__/native/ios_render_check.m | 264 ++++++++++++++++++++++++ 10 files changed, 485 insertions(+), 2 deletions(-) create mode 100644 ios/INKDocumentRenderer.h create mode 100644 ios/INKDocumentRenderer.m create mode 100644 ios/INKInkpadModule.h create mode 100644 ios/INKInkpadModule.mm create mode 100644 src/__tests__/iosRender.test.ts create mode 100644 src/__tests__/native/ios_render_check.m diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a831a6b..c10ef8e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -140,10 +140,10 @@ jobs: npx agent-device prepare ios-runner --platform ios --udid "$udid" --timeout 900000 npx agent-device daemon stop - - name: Stroke codec and command queue + - name: Stroke codec, command queue and renderer env: INKPAD_IOS_SIMULATOR: ${{ steps.simulator.outputs.udid }} - run: yarn vitest run src/__tests__/iosCodec.test.ts src/__tests__/iosCommandQueue.test.ts + run: yarn vitest run src/__tests__/iosCodec.test.ts src/__tests__/iosCommandQueue.test.ts src/__tests__/iosRender.test.ts - name: End-to-end tests env: diff --git a/ios/INKDocumentRenderer.h b/ios/INKDocumentRenderer.h new file mode 100644 index 0000000..4fcd9e5 --- /dev/null +++ b/ios/INKDocumentRenderer.h @@ -0,0 +1,16 @@ +#import + +#import "INKImageExporter.h" + +NS_ASSUME_NONNULL_BEGIN + +@interface INKDocumentRenderer : NSObject + +// Renders a stored document the way a canvas of its size exports it. The completion may run on any queue. ++ (void)renderDocument:(NSString *)documentJSON + options:(NSString *)optionsJSON + completion:(INKExportCompletion)completion; + +@end + +NS_ASSUME_NONNULL_END diff --git a/ios/INKDocumentRenderer.m b/ios/INKDocumentRenderer.m new file mode 100644 index 0000000..0f745c7 --- /dev/null +++ b/ios/INKDocumentRenderer.m @@ -0,0 +1,85 @@ +#import "INKDocumentRenderer.h" + +#import "INKBackgroundLoader.h" +#import "INKColor.h" +#import "INKStrokeCodec.h" + +// Renders run one at a time, so a list of thumbnails holds one decoded background at a time. +static dispatch_queue_t INKRenderQueue(void) +{ + static dispatch_queue_t queue; + static dispatch_once_t once; + dispatch_once(&once, ^{ + queue = dispatch_queue_create( + "me.sectiontn.inkpad.render", + dispatch_queue_attr_make_with_qos_class(DISPATCH_QUEUE_SERIAL, QOS_CLASS_USER_INITIATED, 0)); + }); + return queue; +} + +@implementation INKDocumentRenderer + ++ (void)renderDocument:(NSString *)documentJSON + options:(NSString *)optionsJSON + completion:(INKExportCompletion)completion +{ + dispatch_async(INKRenderQueue(), ^{ + dispatch_semaphore_t done = dispatch_semaphore_create(0); + [self render:documentJSON + options:optionsJSON + completion:^(NSString *json, NSString *errorCode, NSString *message) { + completion(json, errorCode, message); + dispatch_semaphore_signal(done); + }]; + // The background loader calls back on the main queue, which this wait never blocks. + dispatch_semaphore_wait(done, DISPATCH_TIME_FOREVER); + }); +} + ++ (void)render:(NSString *)documentJSON options:(NSString *)optionsJSON completion:(INKExportCompletion)completion +{ + NSString *errorCode = nil; + NSString *message = nil; + INKDecodedDrawing *decoded = [INKStrokeCodec decode:documentJSON errorCode:&errorCode message:&message]; + if (decoded == nil) { + completion(nil, errorCode, message); + return; + } + CGSize size = decoded.size; + if (!(size.width > 0 && size.height > 0)) { + completion(nil, @"E_INVALID_DOCUMENT", @"size must have a positive width and height"); + return; + } + + NSData *data = [optionsJSON dataUsingEncoding:NSUTF8StringEncoding]; + id parsed = data ? [NSJSONSerialization JSONObjectWithData:data options:0 error:nil] : nil; + NSDictionary *options = [parsed isKindOfClass:NSDictionary.class] ? parsed : @{}; + UIColor *color = INKIsHexColor(options[@"backgroundColor"]) ? INKColorFromHex(options[@"backgroundColor"]) + : UIColor.clearColor; + BOOL cover = [options[@"backgroundFit"] isEqual:@"cover"]; + void (^finish)(UIImage *) = ^(UIImage *image) { + [INKImageExporter exportDrawing:decoded.drawing + canvasSize:size + canvasColor:color + backgroundImage:image + cover:cover + optionsJSON:optionsJSON + completion:completion]; + }; + + id uri = options[@"backgroundImageUri"]; + if (![uri isKindOfClass:NSString.class] || [uri length] == 0) { + finish(nil); + return; + } + [INKBackgroundLoader loadURI:uri + completion:^(UIImage *image, NSString *loadMessage) { + if (image == nil) { + completion(nil, @"E_IMAGE_LOAD", loadMessage); + return; + } + finish(image); + }]; +} + +@end diff --git a/ios/INKInkpadModule.h b/ios/INKInkpadModule.h new file mode 100644 index 0000000..14fdecd --- /dev/null +++ b/ios/INKInkpadModule.h @@ -0,0 +1,8 @@ +#import + +NS_ASSUME_NONNULL_BEGIN + +@interface INKInkpadModule : NSObject +@end + +NS_ASSUME_NONNULL_END diff --git a/ios/INKInkpadModule.mm b/ios/INKInkpadModule.mm new file mode 100644 index 0000000..c2a384f --- /dev/null +++ b/ios/INKInkpadModule.mm @@ -0,0 +1,34 @@ +#import "INKInkpadModule.h" + +#import "INKDocumentRenderer.h" + +@implementation INKInkpadModule + ++ (NSString *)moduleName +{ + return @"Inkpad"; +} + +- (void)renderImage:(NSString *)documentJson + optionsJson:(NSString *)optionsJson + resolve:(RCTPromiseResolveBlock)resolve + reject:(RCTPromiseRejectBlock)reject +{ + [INKDocumentRenderer renderDocument:documentJson + options:optionsJson + completion:^(NSString *json, NSString *errorCode, NSString *message) { + if (json != nil) { + resolve(json); + } else { + reject(errorCode ?: @"E_EXPORT_FAILED", message ?: @"export failed", nil); + } + }]; +} + +- (std::shared_ptr)getTurboModule: + (const facebook::react::ObjCTurboModule::InitParams &)params +{ + return std::make_shared(params); +} + +@end diff --git a/ios/INKStrokeCodec.h b/ios/INKStrokeCodec.h index 2fb42b6..a564587 100644 --- a/ios/INKStrokeCodec.h +++ b/ios/INKStrokeCodec.h @@ -18,6 +18,8 @@ NS_ASSUME_NONNULL_BEGIN @interface INKDecodedDrawing : NSObject @property (nonatomic, strong) PKDrawing *drawing; @property (nonatomic, copy) NSDictionary *brushes; +// Zero where the document has no numeric size; the canvas keeps its own. +@property (nonatomic) CGSize size; @end @interface INKStrokeCodec : NSObject diff --git a/ios/INKStrokeCodec.m b/ios/INKStrokeCodec.m index 4c47cce..2d7d26d 100644 --- a/ios/INKStrokeCodec.m +++ b/ios/INKStrokeCodec.m @@ -32,6 +32,15 @@ static INKPenTool INKPenToolForInput(NSString *input) return [input isEqualToString:@"mouse"] ? INKPenToolMouse : INKPenToolTouch; } +static CGSize INKDocumentSize(id value) +{ + NSDictionary *size = [value isKindOfClass:NSDictionary.class] ? value : nil; + id width = size[@"width"]; + id height = size[@"height"]; + return CGSizeMake([width isKindOfClass:NSNumber.class] ? [width doubleValue] : 0, + [height isKindOfClass:NSNumber.class] ? [height doubleValue] : 0); +} + // Pen strokes reload with Android's widths; marker and highlighter keep the brush size. The caller frees the result. static double *INKPointWidths(INKBrushInfo *info, NSArray *values) { @@ -181,6 +190,7 @@ + (INKDecodedDrawing *)decode:(NSString *)json errorCode:(NSString **)errorCode INKDecodedDrawing *decoded = [INKDecodedDrawing new]; decoded.drawing = [[PKDrawing alloc] initWithStrokes:result]; decoded.brushes = brushes; + decoded.size = INKDocumentSize(root[@"size"]); return decoded; } diff --git a/package.json b/package.json index 10ac247..0cd035c 100644 --- a/package.json +++ b/package.json @@ -141,6 +141,9 @@ "InkpadView": { "className": "INKPadView" } + }, + "modulesProvider": { + "Inkpad": "INKInkpadModule" } } }, diff --git a/src/__tests__/iosRender.test.ts b/src/__tests__/iosRender.test.ts new file mode 100644 index 0000000..48a498e --- /dev/null +++ b/src/__tests__/iosRender.test.ts @@ -0,0 +1,61 @@ +import { execFileSync, spawnSync } from 'node:child_process'; +import { mkdtempSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { expect, it } from 'vitest'; + +const path = (relative: string) => fileURLToPath(new URL(relative, import.meta.url)); +// The UDID of a booted iOS simulator; the check runs inside it, without touching the screen. +const simulator = process.env.INKPAD_IOS_SIMULATOR; + +it.skipIf(!simulator)( + 'renders a document on iOS as the canvas exports it', + () => { + const sdk = execFileSync('xcrun', ['--sdk', 'iphonesimulator', '--show-sdk-path']) + .toString() + .trim(); + const binary = join(mkdtempSync(join(tmpdir(), 'inkpad-')), 'ios_render_check'); + const sources = [ + 'INKDocumentRenderer.m', + 'INKImageExporter.m', + 'INKStrokeCodec.m', + 'INKPenModel.c', + 'INKColor.m', + 'INKBrushes.m', + 'INKBackgroundLoader.m', + ].map((file) => path(`../../ios/${file}`)); + execFileSync('xcrun', [ + '-sdk', + 'iphonesimulator', + 'clang', + '-target', + 'arm64-apple-ios17.0-simulator', + '-isysroot', + sdk, + '-fobjc-arc', + '-fmodules', + '-framework', + 'UIKit', + '-framework', + 'PencilKit', + '-framework', + 'ImageIO', + ...sources, + path('./native/ios_render_check.m'), + '-o', + binary, + ]); + const run = spawnSync('xcrun', [ + 'simctl', + 'spawn', + simulator as string, + binary, + path('../../example/src/sample.json'), + ]); + const output = `${run.stdout}${run.stderr}`; + expect(output).not.toContain('FAIL'); + expect(run.status, output).toBe(0); + }, + 240_000, +); diff --git a/src/__tests__/native/ios_render_check.m b/src/__tests__/native/ios_render_check.m new file mode 100644 index 0000000..481d7aa --- /dev/null +++ b/src/__tests__/native/ios_render_check.m @@ -0,0 +1,264 @@ +#import +#import +#import + +#import "../../../ios/INKColor.h" +#import "../../../ios/INKDocumentRenderer.h" +#import "../../../ios/INKImageExporter.h" +#import "../../../ios/INKStrokeCodec.h" + +typedef NSString *_Nullable (^INKInspect)(size_t width, size_t height, const uint8_t *rgba); + +static int failures = 0; +static int pending = 0; + +static void fail(NSString *name, NSString *reason) +{ + printf("FAIL %s: %s\n", name.UTF8String, reason.UTF8String); + failures++; +} + +static NSString *json(id object) +{ + NSData *data = [NSJSONSerialization dataWithJSONObject:object options:0 error:nil]; + return [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]; +} + +static NSDictionary *parse(NSString *_Nullable string) +{ + NSData *data = [string dataUsingEncoding:NSUTF8StringEncoding]; + return data ? [NSJSONSerialization JSONObjectWithData:data options:0 error:nil] : nil; +} + +// The options the JS side sends, with the case's own values on top. +static NSString *options(NSDictionary *overrides) +{ + NSMutableDictionary *result = [@{ + @"format" : @"png", + @"quality" : @0.9, + @"scale" : @3, + @"maxSize" : @0, + @"trim" : @NO, + @"padding" : @0, + @"background" : @YES, + @"base64" : @NO, + @"backgroundColor" : @"", + @"backgroundImageUri" : @"", + @"backgroundFit" : @"contain", + } mutableCopy]; + [result addEntriesFromDictionary:overrides]; + return json(result); +} + +// Hands the result to the handler on the main queue and stops the run loop after the last job. +static INKExportCompletion track(void (^handler)(NSString *json, NSString *code, NSString *message)) +{ + pending++; + return ^(NSString *result, NSString *code, NSString *message) { + dispatch_async(dispatch_get_main_queue(), ^{ + handler(result, code, message); + if (--pending == 0) { + CFRunLoopStop(CFRunLoopGetMain()); + } + }); + }; +} + +// Decodes the exported file to premultiplied sRGB RGBA, then deletes it. +static NSData *pixels(NSString *result, size_t *width, size_t *height) +{ + NSDictionary *parsed = parse(result); + NSURL *url = [NSURL URLWithString:parsed[@"uri"]]; + NSData *file = [NSData dataWithContentsOfURL:url]; + [NSFileManager.defaultManager removeItemAtURL:url error:nil]; + CGImageSourceRef source = file ? CGImageSourceCreateWithData((__bridge CFDataRef)file, NULL) : NULL; + CGImageRef image = source ? CGImageSourceCreateImageAtIndex(source, 0, NULL) : NULL; + if (source) { + CFRelease(source); + } + if (image == NULL) { + return nil; + } + *width = CGImageGetWidth(image); + *height = CGImageGetHeight(image); + if ([parsed[@"width"] unsignedLongValue] != *width || [parsed[@"height"] unsignedLongValue] != *height) { + CGImageRelease(image); + return nil; + } + NSMutableData *bytes = [NSMutableData dataWithLength:*width * *height * 4]; + CGColorSpaceRef srgb = CGColorSpaceCreateWithName(kCGColorSpaceSRGB); + CGContextRef context = CGBitmapContextCreate(bytes.mutableBytes, *width, *height, 8, *width * 4, srgb, + (CGBitmapInfo)kCGImageAlphaPremultipliedLast); + CGContextDrawImage(context, CGRectMake(0, 0, *width, *height), image); + CGContextRelease(context); + CGColorSpaceRelease(srgb); + CGImageRelease(image); + return bytes; +} + +static void compare(NSString *name, NSString *result, NSString *_Nullable expected, INKInspect inspect) +{ + size_t width = 0, height = 0, expectedWidth = 0, expectedHeight = 0; + NSData *actual = pixels(result, &width, &height); + NSData *reference = expected ? pixels(expected, &expectedWidth, &expectedHeight) : nil; + if (actual == nil || reference == nil) { + fail(name, @"an image did not decode at its reported size"); + return; + } + if (width != expectedWidth || height != expectedHeight) { + fail(name, [NSString stringWithFormat:@"%zux%zu, the canvas gives %zux%zu", width, height, expectedWidth, + expectedHeight]); + return; + } + if (![actual isEqualToData:reference]) { + const uint8_t *a = actual.bytes; + const uint8_t *b = reference.bytes; + size_t differ = 0; + for (size_t i = 0; i < actual.length; i += 4) { + differ += memcmp(a + i, b + i, 4) != 0; + } + fail(name, [NSString stringWithFormat:@"%zu pixels differ from the canvas", differ]); + return; + } + NSString *reason = inspect ? inspect(width, height, actual.bytes) : nil; + if (reason != nil) { + fail(name, reason); + return; + } + printf("ok %s\n", name.UTF8String); +} + +// The canvas exports what setStrokes installed, at its own size and color, so the reference is the exporter itself. +static void canvasCase(NSString *name, NSString *document, NSDictionary *overrides, INKInspect inspect) +{ + NSString *optionsJSON = options(overrides); + NSDictionary *size = parse(document)[@"size"]; + NSString *color = overrides[@"backgroundColor"]; + [INKDocumentRenderer renderDocument:document + options:optionsJSON + completion:track(^(NSString *result, NSString *code, NSString *message) { + if (result == nil) { + fail(name, [NSString stringWithFormat:@"%@ %@", code, message]); + return; + } + NSString *decodeCode = nil; + NSString *decodeMessage = nil; + INKDecodedDrawing *decoded = [INKStrokeCodec decode:document + errorCode:&decodeCode + message:&decodeMessage]; + [INKImageExporter exportDrawing:decoded.drawing + canvasSize:CGSizeMake([size[@"width"] doubleValue], + [size[@"height"] doubleValue]) + canvasColor:color ? INKColorFromHex(color) : UIColor.clearColor + backgroundImage:nil + cover:NO + optionsJSON:optionsJSON + completion:track(^(NSString *expected, NSString *c, NSString *m) { + compare(name, result, expected, inspect); + })]; + })]; +} + +static void errorCase(NSString *name, NSString *document, NSDictionary *overrides, NSString *code, NSString *prefix) +{ + [INKDocumentRenderer renderDocument:document + options:options(overrides) + completion:track(^(NSString *result, NSString *errorCode, NSString *message) { + if (result != nil || ![errorCode isEqualToString:code] || ![message hasPrefix:prefix]) { + fail(name, [NSString stringWithFormat:@"got %@ %@ %@", result, errorCode, message]); + return; + } + printf("ok %s\n", name.UTF8String); + })]; +} + +int main(int argc, char **argv) +{ + @autoreleasepool { + if (argc < 2) return 2; + NSString *sample = [NSString stringWithContentsOfFile:[NSString stringWithUTF8String:argv[1]] + encoding:NSUTF8StringEncoding + error:nil]; + if (sample == nil) return 2; + + canvasCase(@"canvas {}", sample, @{}, ^NSString *(size_t width, size_t height, const uint8_t *rgba) { + return rgba[3] == 0 ? nil : @"the corner is not transparent"; + }); + canvasCase(@"canvas trim", sample, @{@"trim" : @YES, @"padding" : @8}, + ^NSString *(size_t width, size_t height, const uint8_t *rgba) { + return width < 360 * 3 && height < 440 * 3 ? nil : @"the image is not trimmed"; + }); + canvasCase(@"canvas backgroundColor", sample, @{@"backgroundColor" : @"#FFEEDDFF"}, + ^NSString *(size_t width, size_t height, const uint8_t *rgba) { + BOOL paper = abs(rgba[0] - 0xFF) <= 2 && abs(rgba[1] - 0xEE) <= 2 && abs(rgba[2] - 0xDD) <= 2 && + rgba[3] == 0xFF; + return paper ? nil + : [NSString stringWithFormat:@"the corner is %02X%02X%02X%02X", rgba[0], rgba[1], + rgba[2], rgba[3]]; + }); + canvasCase(@"canvas maxSize", sample, @{@"maxSize" : @160}, + ^NSString *(size_t width, size_t height, const uint8_t *rgba) { + return MAX(width, height) == 160 + ? nil + : [NSString stringWithFormat:@"the longest side is %zu", MAX(width, height)]; + }); + + NSString *empty = @"{\"version\":1,\"size\":{\"width\":320,\"height\":240},\"strokes\":[]}"; + [INKDocumentRenderer renderDocument:empty + options:options(@{@"scale" : @2}) + completion:track(^(NSString *result, NSString *code, NSString *message) { + size_t width = 0, height = 0; + NSData *bytes = result ? pixels(result, &width, &height) : nil; + const uint8_t *rgba = bytes.bytes; + BOOL clear = bytes != nil; + for (NSUInteger i = 0; clear && i < bytes.length; i++) { + clear = rgba[i] == 0; + } + if (width != 640 || height != 480 || !clear) { + fail(@"empty", [NSString stringWithFormat:@"%zux%zu, transparent %d, %@ %@", width, + height, clear, code, message]); + return; + } + printf("ok empty\n"); + })]; + + errorCase(@"image", sample, @{@"backgroundImageUri" : @"file:///nonexistent.png"}, @"E_IMAGE_LOAD", + @"could not load the background image file:///nonexistent.png"); + errorCase(@"invalid strokes", @"{\"version\":1,\"size\":{\"width\":10,\"height\":10},\"strokes\":3}", @{}, + @"E_INVALID_DOCUMENT", @"strokes must be an array"); + errorCase(@"invalid size", @"{\"version\":1,\"strokes\":[]}", @{}, @"E_INVALID_DOCUMENT", @"size"); + + NSMutableArray *order = [NSMutableArray new]; + NSMutableSet *files = [NSMutableSet new]; + for (NSInteger i = 0; i < 20; i++) { + [INKDocumentRenderer renderDocument:sample + options:options(@{@"scale" : @1, @"maxSize" : @64}) + completion:track(^(NSString *result, NSString *code, NSString *message) { + [order addObject:@(i)]; + NSString *uri = parse(result)[@"uri"]; + if (uri != nil) { + [files addObject:uri]; + [NSFileManager.defaultManager removeItemAtURL:[NSURL URLWithString:uri] error:nil]; + } + if (order.count < 20) { + return; + } + NSArray *expected = [order sortedArrayUsingSelector:@selector(compare:)]; + if (files.count != 20 || ![order isEqualToArray:expected]) { + fail(@"many", [NSString stringWithFormat:@"%lu files, completed in order %@", + (unsigned long)files.count, + [order componentsJoinedByString:@","]]); + return; + } + printf("ok many\n"); + })]; + } + + dispatch_after(dispatch_time(DISPATCH_TIME_NOW, 90 * NSEC_PER_SEC), dispatch_get_main_queue(), ^{ + printf("FAIL timeout: %d jobs still pending\n", pending); + exit(1); + }); + CFRunLoopRun(); + return failures == 0 ? 0 : 1; + } +} From dd811ec73d2914ae828f344534925d82fbbb29ec Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Wed, 4 Nov 2026 19:31:12 +0100 Subject: [PATCH 07/17] feat(example): show a rendered thumbnail in the export sheet --- e2e/canvas.e2e.ts | 4 ++++ example/src/ExportSheet.tsx | 33 +++++++++++++++++++++++++++++++-- 2 files changed, 35 insertions(+), 2 deletions(-) diff --git a/e2e/canvas.e2e.ts b/e2e/canvas.e2e.ts index 47a5493..936b5c7 100644 --- a/e2e/canvas.e2e.ts +++ b/e2e/canvas.e2e.ts @@ -35,6 +35,10 @@ test('loads the sample, exports it and loads it back', async ({ app, screen }) = await expect(screen.getByTestId('status')).toContainText(strokes); await tapCenter(screen.getByLabel('Export')); await expect(screen.getByTestId('export-status')).toContainText('PNG · '); + const caption = await screen.getByTestId('thumbnail-size').textContent(); + const [, width, height] = caption?.match(/(\d+) x (\d+)/) ?? []; + expect(Math.max(Number(width), Number(height)), caption ?? 'no caption').toBe(160); + await expect(screen.getByTestId('thumbnail')).toBeVisible(); await tapCenter(screen.getByText('SVG')); await expect(screen.getByTestId('export-status')).toContainText('SVG · '); await tapCenter(screen.getByText('JSON')); diff --git a/example/src/ExportSheet.tsx b/example/src/ExportSheet.tsx index 9e2cb10..a031ec5 100644 --- a/example/src/ExportSheet.tsx +++ b/example/src/ExportSheet.tsx @@ -3,8 +3,8 @@ import { BottomSheetModal, BottomSheetView } from '@expo/ui/community/bottom-she import SegmentedControl from '@expo/ui/community/segmented-control'; import * as Sharing from 'expo-sharing'; import { type RefObject, useEffect, useRef, useState } from 'react'; -import { Image, Platform, Share, StyleSheet, Text, View } from 'react-native'; -import type { ImageResult, InkCanvasRef } from 'react-native-inkpad'; +import { Image, PixelRatio, Platform, Share, StyleSheet, Text, View } from 'react-native'; +import { type ImageResult, type InkCanvasRef, renderImage } from 'react-native-inkpad'; import { useTheme } from './theme'; const FORMATS = ['PNG', 'SVG', 'JSON'] as const; @@ -22,6 +22,7 @@ export function ExportSheet({ canvas, open, onClose }: Props) { const sheet = useRef(null); const [format, setFormat] = useState('PNG'); const [image, setImage] = useState(null); + const [thumbnail, setThumbnail] = useState(null); const [text, setText] = useState(''); const [status, setStatus] = useState(''); @@ -37,8 +38,11 @@ export function ExportSheet({ canvas, open, onClose }: Props) { const run = async () => { if (format === 'PNG') { const result = await ink.toImage({ trim: { padding: 8 } }); + const doc = await ink.getStrokes(); + const thumb = await renderImage(doc, { maxSize: 160, trim: { padding: 8 } }); if (!live) return; setImage(result); + setThumbnail(thumb); setStatus(`PNG · ${result.width} x ${result.height} px`); } else if (format === 'SVG') { const svg = await ink.toSVG({ trim: true }); @@ -108,6 +112,25 @@ export function ExportSheet({ canvas, open, onClose }: Props) { )} + {showImage && thumbnail ? ( + + + + {`Thumbnail · ${thumbnail.width} x ${thumbnail.height} px`} + + + ) : null} {status} @@ -137,6 +160,12 @@ const styles = StyleSheet.create({ overflow: 'hidden', }, image: { flex: 1 }, + thumbnailRow: { flexDirection: 'row', alignItems: 'center', justifyContent: 'center', gap: 12 }, + thumbnail: { + backgroundColor: '#FFFFFF', + borderRadius: 8, + borderWidth: StyleSheet.hairlineWidth, + }, code: { fontFamily: Platform.select({ ios: 'Menlo', default: 'monospace' }), fontSize: 11 }, caption: { fontSize: 13, textAlign: 'center' }, actions: { flexDirection: 'row', justifyContent: 'center', gap: 12 }, From 6c7a051c7bb856ea08eb53902bc174e6a7a17fde Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Wed, 4 Nov 2026 19:59:50 +0100 Subject: [PATCH 08/17] ci: run the built svg entry in node --- .github/workflows/ci.yml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c10ef8e..5b1bf11 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -33,6 +33,15 @@ jobs: - name: Build package run: yarn prepare + - name: Run the built svg entry in Node + run: | + node --input-type=module -e " + import { renderSVG } from 'react-native-inkpad/svg'; + const doc = { version: 1, size: { width: 10, height: 10 }, strokes: [] }; + const svg = renderSVG(doc, { background: { color: 'white' } }); + if (!svg.includes(' Date: Wed, 4 Nov 2026 19:33:56 +0100 Subject: [PATCH 09/17] docs: document rendering without a canvas --- README.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 46 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 6bdb791..e4353e4 100644 --- a/README.md +++ b/README.md @@ -98,9 +98,46 @@ export function SignatureField() { | `clear()` | Remove every stroke. | | `getStrokes()` | Get the strokes as a plain object you can store as JSON. | | `setStrokes(doc)` | Replace the drawing with strokes from `getStrokes()`. | -| `toImage({ format, quality, scale, trim, background, base64 })` | Export a PNG or JPEG. Resolves to `{ uri, width, height, base64? }`. On web, `uri` is a `blob:` URL. | +| `toImage({ format, quality, scale, maxSize, trim, background, base64 })` | Export a PNG or JPEG. `maxSize` caps the longest side in pixels. Resolves to `{ uri, width, height, base64? }`. On web, `uri` is a `blob:` URL. | | `toSVG({ trim, background })` | Export an SVG string. It links the background image by URI. | +### Render without a canvas + +`renderImage(doc, options)` and `renderSVG(doc, options)` turn a document from `getStrokes()` into an image or an SVG string without a mounted `InkCanvas`. Use them for thumbnails and lists. + +| Function | Returns | Options | +| --- | --- | --- | +| `renderImage(doc, options)` | `Promise<{ uri, width, height, base64? }>`, the same result as `toImage`. | The `toImage` options, except `background` is `{ color, image, fit }` like the prop. | +| `renderSVG(doc, options)` | An SVG string, synchronously. | `{ trim, background }`, with the same `background`. | + +A document has no background, so the default is transparent. `maxSize` is the longest side in pixels. It lowers `scale` for an image that would be bigger and never raises it, and a value below 1 is ignored. + +```tsx +import { renderImage } from 'react-native-inkpad'; + +const thumb = await renderImage(doc, { + maxSize: 256, + trim: { padding: 8 }, + background: { color: '#FFFFFF' }, +}); +``` + +`renderImage` rejects and `renderSVG` throws an `InkpadError`. `renderImage` fails with `E_EXPORT_FAILED` if the native module is missing, so rebuild the app. + +#### On a server + +The `react-native-inkpad/svg` entry exports `renderSVG`, `validateDocument`, `InkpadError` and `ErrorCode`, and doesn't load React Native. + +```js +import { renderSVG } from 'react-native-inkpad/svg'; + +const svg = renderSVG(doc, { trim: { padding: 8 }, background: { color: 'hsl(0 0% 100%)' } }); +``` + +Its `background` is `{ color?, image?: { uri }, fit? }`. `color` takes a hex, `rgb()`, `hsl()`, `hwb()` or named color, and one it can't parse throws `E_EXPORT_FAILED`. The SVG links the background image by URI. + +npm 7+ installs the `react` and `react-native` peers on the server anyway, though nothing loads them. + ### Errors Failed calls throw an `InkpadError`. Its `code` is one of: @@ -109,11 +146,11 @@ Failed calls throw an `InkpadError`. Its `code` is one of: | --- | --- | | `E_NOT_MOUNTED` | The canvas isn't mounted, or it unmounted before the call finished. | | `E_TIMEOUT` | The native view didn't answer within 15 seconds. | -| `E_INVALID_DOCUMENT` | `setStrokes()` got a malformed document. | -| `E_UNSUPPORTED_VERSION` | The document was saved by a newer version of the library. | -| `E_EMPTY` | `trim` was set but the canvas is empty. | +| `E_INVALID_DOCUMENT` | `setStrokes()`, `renderImage()` or `renderSVG()` got a malformed document. | +| `E_UNSUPPORTED_VERSION` | `setStrokes()`, `renderImage()` or `renderSVG()` got a document saved by a newer version of the library. | +| `E_EMPTY` | `trim` was set but the canvas, or the document given to `renderImage()` or `renderSVG()`, has no strokes. | | `E_EXPORT_FAILED` | The image couldn't be created or saved. | -| `E_IMAGE_LOAD` | The background image couldn't be loaded. It goes to `onError`. | +| `E_IMAGE_LOAD` | The background image couldn't be loaded, or `renderImage()` or `renderSVG()` got an image with no usable URI, such as a numeric `require()` asset on web. On the canvas it goes to `onError`. | | `E_NATIVE` | Any other native error. | ## Migrating from react-native-signature-canvas @@ -148,6 +185,10 @@ From 1.0, releases follow [semver](https://semver.org): - [x] 0.3: Web - [x] 0.4: Background images, stylus-only mode and `onError` - [x] 1.0: First stable release +- [x] 1.1: Render a document without a canvas +- [ ] 1.2: Zoom and pan +- [ ] 1.3: Point eraser and stylus extras +- [ ] 1.4: Lasso select and move ## Contributing From f61b9280ba3abdfe68e49b225734c986ef435d8e Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Wed, 4 Nov 2026 20:54:53 +0100 Subject: [PATCH 10/17] fix(svg): clamp negative trim padding --- src/__tests__/toSVG.test.ts | 6 ++++++ src/svg/toSVG.ts | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/src/__tests__/toSVG.test.ts b/src/__tests__/toSVG.test.ts index 4a1d595..a35c906 100644 --- a/src/__tests__/toSVG.test.ts +++ b/src/__tests__/toSVG.test.ts @@ -36,6 +36,12 @@ describe('toSVG', () => { ); }); + it('treats negative padding as none', () => { + expect(toSVG(doc([line]), { trim: { padding: -30 } })).toBe( + toSVG(doc([line]), { trim: { padding: 0 } }), + ); + }); + it('draws the background color under the strokes', () => { expect(toSVG(doc([]), { backgroundColor: '#FFFFFFFF' })).toContain( '', diff --git a/src/svg/toSVG.ts b/src/svg/toSVG.ts index 2fdbfc2..842617e 100644 --- a/src/svg/toSVG.ts +++ b/src/svg/toSVG.ts @@ -28,7 +28,7 @@ export function toSVG(doc: InkDocument, options: SvgRenderOptions = {}): string if (options.trim) { const bounds = boundsOf(strokes.flatMap((s) => s.points)); if (!bounds) throw new InkpadError(ErrorCode.EMPTY, 'nothing to trim: the canvas is empty'); - const padding = typeof options.trim === 'object' ? options.trim.padding : 0; + const padding = typeof options.trim === 'object' ? Math.max(0, options.trim.padding) : 0; x = bounds.minX - padding; y = bounds.minY - padding; width = bounds.maxX - bounds.minX + padding * 2; From 895d12e43e828b5be931d95342ee57dffde301f9 Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Wed, 4 Nov 2026 20:55:41 +0100 Subject: [PATCH 11/17] fix(web): report malformed background URIs as E_IMAGE_LOAD --- src/__tests__/imageSource.test.ts | 31 ++++++++++++++++++++++++++++++- src/render/resolveImage.web.ts | 5 +++-- src/web/imageSource.ts | 8 ++++++++ 3 files changed, 41 insertions(+), 3 deletions(-) diff --git a/src/__tests__/imageSource.test.ts b/src/__tests__/imageSource.test.ts index 5521b72..5df2a8b 100644 --- a/src/__tests__/imageSource.test.ts +++ b/src/__tests__/imageSource.test.ts @@ -1,5 +1,34 @@ import { describe, expect, it } from 'vitest'; -import { uriOf } from '../web/imageSource'; +import { renderSvgWith } from '../render/core'; +import { resolveImage } from '../render/resolveImage.web'; +import { absoluteUri, uriOf } from '../web/imageSource'; + +describe('absoluteUri', () => { + it('resolves a relative URI against the base', () => { + expect(absoluteUri('/assets/a.png', 'https://x.test/app/')).toBe('https://x.test/assets/a.png'); + expect(absoluteUri('a.png', 'https://x.test/app/')).toBe('https://x.test/app/a.png'); + }); + + it('keeps an absolute URI without a base', () => { + expect(absoluteUri('https://x.test/a.png', undefined)).toBe('https://x.test/a.png'); + }); + + it('has no URI for one that does not parse', () => { + expect(absoluteUri('http://[', 'https://x.test/')).toBeUndefined(); + expect(absoluteUri('a.png', undefined)).toBeUndefined(); + }); +}); + +describe('web resolveImage', () => { + it('turns a malformed URI into E_IMAGE_LOAD', () => { + const doc = { version: 1, size: { width: 10, height: 10 }, strokes: [] }; + const resolvers = { color: () => undefined, image: resolveImage }; + const options = { background: { image: { uri: 'http://[' } } }; + expect(() => renderSvgWith(doc, options, resolvers)).toThrow( + expect.objectContaining({ code: 'E_IMAGE_LOAD' }), + ); + }); +}); describe('uriOf', () => { it('reads every source shape a web app passes', () => { diff --git a/src/render/resolveImage.web.ts b/src/render/resolveImage.web.ts index 3ee6dfe..584b34e 100644 --- a/src/render/resolveImage.web.ts +++ b/src/render/resolveImage.web.ts @@ -1,7 +1,8 @@ import type { ImageSourcePropType } from 'react-native'; -import { uriOf } from '../web/imageSource'; +import { absoluteUri, uriOf } from '../web/imageSource'; export function resolveImage(source: ImageSourcePropType): string | undefined { const uri = uriOf(source); - return uri ? new URL(uri, document.baseURI).href : undefined; + const base = typeof document === 'undefined' ? undefined : document.baseURI; + return uri ? absoluteUri(uri, base) : undefined; } diff --git a/src/web/imageSource.ts b/src/web/imageSource.ts index 0b7c9d3..a7beea8 100644 --- a/src/web/imageSource.ts +++ b/src/web/imageSource.ts @@ -14,3 +14,11 @@ export function uriOf(source: unknown): string | undefined { } return undefined; } + +export function absoluteUri(uri: string, base: string | undefined): string | undefined { + try { + return new URL(uri, base).href; + } catch { + return undefined; + } +} From 0e5244d2e35599eb7e2207c9d7514697532842ac Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Wed, 4 Nov 2026 20:56:41 +0100 Subject: [PATCH 12/17] test: cover the root renderSVG adapter and the capped trimmed transform --- src/__tests__/exportImage.test.ts | 11 +++++++++++ src/__tests__/renderSVG.test.ts | 26 ++++++++++++++++++++++++++ src/__tests__/svgEntry.test.ts | 2 +- 3 files changed, 38 insertions(+), 1 deletion(-) create mode 100644 src/__tests__/renderSVG.test.ts diff --git a/src/__tests__/exportImage.test.ts b/src/__tests__/exportImage.test.ts index 92f2a2f..db7fccc 100644 --- a/src/__tests__/exportImage.test.ts +++ b/src/__tests__/exportImage.test.ts @@ -148,6 +148,17 @@ describe('exportImage', () => { expect(d).toBeCloseTo(160 / 300); }); + it('offsets a capped trimmed export by the scaled origin', async () => { + await exportImage(doc([line]), opts({ trim: true, scale: 2, maxSize: 60 }), undefined, deps); + const scale = 60 / 44; + const args = calls.find((call) => call.op === 'setTransform')?.args ?? []; + const expected = [scale, 0, 0, scale, -8 * scale, -8 * scale]; + expect(args).toHaveLength(6); + expected.forEach((value, i) => { + expect(args[i]).toBeCloseTo(value); + }); + }); + it('rejects when the browser cannot encode', async () => { await expect(exportImage(doc([line]), opts({}), undefined, failingDeps)).rejects.toMatchObject({ code: 'E_EXPORT_FAILED', diff --git a/src/__tests__/renderSVG.test.ts b/src/__tests__/renderSVG.test.ts new file mode 100644 index 0000000..8cc8d41 --- /dev/null +++ b/src/__tests__/renderSVG.test.ts @@ -0,0 +1,26 @@ +import { describe, expect, it, vi } from 'vitest'; +import type { InkDocument } from '../document'; +import { renderSVG } from '../render/renderSVG'; + +const PAPER = 7; + +vi.mock('react-native', () => ({ + processColor: (color: unknown) => (color === '#FF0000' ? 0xffff0000 : undefined), + Image: { + resolveAssetSource: (source: unknown) => + source === PAPER ? { uri: 'file:///paper.png', width: 20, height: 10, scale: 1 } : source, + }, +})); + +const doc: InkDocument = { version: 1, size: { width: 10, height: 10 }, strokes: [] }; + +describe('renderSVG', () => { + it('resolves the color and image through React Native', () => { + expect(renderSVG(doc, { background: { color: '#FF0000', image: PAPER, fit: 'cover' } })).toBe( + '' + + '' + + '' + + '', + ); + }); +}); diff --git a/src/__tests__/svgEntry.test.ts b/src/__tests__/svgEntry.test.ts index cc7daf4..7f3f136 100644 --- a/src/__tests__/svgEntry.test.ts +++ b/src/__tests__/svgEntry.test.ts @@ -78,7 +78,7 @@ describe('react-native-inkpad/svg', () => { ); }); - it('matches the root renderSVG', async () => { + it('matches renderSvgWith with stub resolvers', async () => { const { renderSVG } = await import('../svg'); const options = { trim: true, From 8ba6c2a5c9f2f17f80eed41bde93c24d2a4e5a4a Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Wed, 4 Nov 2026 20:57:37 +0100 Subject: [PATCH 13/17] fix: warn when a background color can't be resolved for rendering --- src/__tests__/renderSVG.test.ts | 35 +++++++++++++++++++++++++++++++-- src/render/resolvers.ts | 8 +++++++- 2 files changed, 40 insertions(+), 3 deletions(-) diff --git a/src/__tests__/renderSVG.test.ts b/src/__tests__/renderSVG.test.ts index 8cc8d41..0f54715 100644 --- a/src/__tests__/renderSVG.test.ts +++ b/src/__tests__/renderSVG.test.ts @@ -1,11 +1,16 @@ -import { describe, expect, it, vi } from 'vitest'; +import type { ColorValue } from 'react-native'; +import { afterEach, describe, expect, it, vi } from 'vitest'; import type { InkDocument } from '../document'; import { renderSVG } from '../render/renderSVG'; const PAPER = 7; +// processColor gives an object for PlatformColor and DynamicColorIOS. vi.mock('react-native', () => ({ - processColor: (color: unknown) => (color === '#FF0000' ? 0xffff0000 : undefined), + processColor(color: unknown) { + if (color === '#FF0000') return 0xffff0000; + return typeof color === 'object' ? { semantic: ['label'] } : undefined; + }, Image: { resolveAssetSource: (source: unknown) => source === PAPER ? { uri: 'file:///paper.png', width: 20, height: 10, scale: 1 } : source, @@ -13,6 +18,14 @@ vi.mock('react-native', () => ({ })); const doc: InkDocument = { version: 1, size: { width: 10, height: 10 }, strokes: [] }; +const blank = + ''; +const platformColor = { semantic: ['label'] } as unknown as ColorValue; + +afterEach(() => { + vi.unstubAllGlobals(); + vi.restoreAllMocks(); +}); describe('renderSVG', () => { it('resolves the color and image through React Native', () => { @@ -23,4 +36,22 @@ describe('renderSVG', () => { '', ); }); + + it('leaves out a color with no concrete value and warns in development', () => { + vi.stubGlobal('__DEV__', true); + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}); + expect(renderSVG(doc, { background: { color: platformColor } })).toBe(blank); + expect(warn).toHaveBeenCalledWith( + 'react-native-inkpad: background.color has no concrete value, so the render leaves it out. Pass a concrete color (hex, rgb() or a named color).', + ); + }); + + it('stays quiet for a concrete color and in production', () => { + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}); + vi.stubGlobal('__DEV__', true); + renderSVG(doc, { background: { color: '#FF0000' } }); + vi.stubGlobal('__DEV__', false); + renderSVG(doc, { background: { color: platformColor } }); + expect(warn).not.toHaveBeenCalled(); + }); }); diff --git a/src/render/resolvers.ts b/src/render/resolvers.ts index 9e7ac57..2809aee 100644 --- a/src/render/resolvers.ts +++ b/src/render/resolvers.ts @@ -6,7 +6,13 @@ import { resolveImage } from './resolveImage'; export const appResolvers: BackgroundResolvers = { color(value) { const processed = processColor(value); - return typeof processed === 'number' ? argbToHex(processed) : undefined; + if (typeof processed === 'number') return argbToHex(processed); + if (__DEV__) { + console.warn( + 'react-native-inkpad: background.color has no concrete value, so the render leaves it out. Pass a concrete color (hex, rgb() or a named color).', + ); + } + return undefined; }, image: resolveImage, }; From 8e1d85f7d9a46d136b8522006794ec0a5d8db44e Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Wed, 4 Nov 2026 20:59:24 +0100 Subject: [PATCH 14/17] test(ios): render a document over a background image --- src/__tests__/native/ios_render_check.m | 75 +++++++++++++++++++++---- 1 file changed, 64 insertions(+), 11 deletions(-) diff --git a/src/__tests__/native/ios_render_check.m b/src/__tests__/native/ios_render_check.m index 481d7aa..7e91381 100644 --- a/src/__tests__/native/ios_render_check.m +++ b/src/__tests__/native/ios_render_check.m @@ -2,6 +2,7 @@ #import #import +#import "../../../ios/INKBackgroundLoader.h" #import "../../../ios/INKColor.h" #import "../../../ios/INKDocumentRenderer.h" #import "../../../ios/INKImageExporter.h" @@ -128,12 +129,14 @@ static void compare(NSString *name, NSString *result, NSString *_Nullable expect printf("ok %s\n", name.UTF8String); } -// The canvas exports what setStrokes installed, at its own size and color, so the reference is the exporter itself. +// The canvas exports what setStrokes installed with its size and background, so the reference is the exporter. static void canvasCase(NSString *name, NSString *document, NSDictionary *overrides, INKInspect inspect) { NSString *optionsJSON = options(overrides); NSDictionary *size = parse(document)[@"size"]; NSString *color = overrides[@"backgroundColor"]; + NSString *uri = overrides[@"backgroundImageUri"]; + BOOL cover = [overrides[@"backgroundFit"] isEqual:@"cover"]; [INKDocumentRenderer renderDocument:document options:optionsJSON completion:track(^(NSString *result, NSString *code, NSString *message) { @@ -146,19 +149,52 @@ static void canvasCase(NSString *name, NSString *document, NSDictionary *overrid INKDecodedDrawing *decoded = [INKStrokeCodec decode:document errorCode:&decodeCode message:&decodeMessage]; - [INKImageExporter exportDrawing:decoded.drawing - canvasSize:CGSizeMake([size[@"width"] doubleValue], - [size[@"height"] doubleValue]) - canvasColor:color ? INKColorFromHex(color) : UIColor.clearColor - backgroundImage:nil - cover:NO - optionsJSON:optionsJSON - completion:track(^(NSString *expected, NSString *c, NSString *m) { - compare(name, result, expected, inspect); - })]; + INKExportCompletion done = track(^(NSString *expected, NSString *c, NSString *m) { + compare(name, result, expected, inspect); + }); + void (^reference)(UIImage *) = ^(UIImage *image) { + [INKImageExporter + exportDrawing:decoded.drawing + canvasSize:CGSizeMake([size[@"width"] doubleValue], [size[@"height"] doubleValue]) + canvasColor:color ? INKColorFromHex(color) : UIColor.clearColor + backgroundImage:image + cover:cover + optionsJSON:optionsJSON + completion:done]; + }; + if (uri == nil) { + reference(nil); + return; + } + [INKBackgroundLoader loadURI:uri + completion:^(UIImage *image, NSString *loadMessage) { + reference(image); + }]; })]; } +// A 90x30 PNG, red on the left half and blue on the right, wider than the 360x440 sample. +static NSString *stripesURI(void) +{ + UIGraphicsImageRendererFormat *format = [UIGraphicsImageRendererFormat preferredFormat]; + format.scale = 1; + format.preferredRange = UIGraphicsImageRendererFormatRangeStandard; + UIGraphicsImageRenderer *renderer = [[UIGraphicsImageRenderer alloc] initWithSize:CGSizeMake(90, 30) + format:format]; + NSData *png = [renderer PNGDataWithActions:^(UIGraphicsImageRendererContext *context) { + [UIColor.redColor setFill]; + [context fillRect:CGRectMake(0, 0, 45, 30)]; + [UIColor.blueColor setFill]; + [context fillRect:CGRectMake(45, 0, 45, 30)]; + }]; + return [@"data:image/png;base64," stringByAppendingString:[png base64EncodedStringWithOptions:0]]; +} + +static BOOL near(const uint8_t *pixel, uint8_t r, uint8_t g, uint8_t b, uint8_t a) +{ + return abs(pixel[0] - r) <= 2 && abs(pixel[1] - g) <= 2 && abs(pixel[2] - b) <= 2 && pixel[3] == a; +} + static void errorCase(NSString *name, NSString *document, NSDictionary *overrides, NSString *code, NSString *prefix) { [INKDocumentRenderer renderDocument:document @@ -202,6 +238,23 @@ int main(int argc, char **argv) ? nil : [NSString stringWithFormat:@"the longest side is %zu", MAX(width, height)]; }); + NSString *stripes = stripesURI(); + canvasCase(@"canvas image contain", sample, @{@"backgroundImageUri" : stripes, @"backgroundFit" : @"contain"}, + ^NSString *(size_t width, size_t height, const uint8_t *rgba) { + const uint8_t *left = rgba + (height / 2 * width + 3) * 4; + const uint8_t *right = rgba + (height / 2 * width + width - 4) * 4; + return rgba[3] == 0 && near(left, 0xFF, 0, 0, 0xFF) && near(right, 0, 0, 0xFF, 0xFF) + ? nil + : @"the image is not centered with bands above and below"; + }); + canvasCase(@"canvas image cover", sample, @{@"backgroundImageUri" : stripes, @"backgroundFit" : @"cover"}, + ^NSString *(size_t width, size_t height, const uint8_t *rgba) { + const uint8_t *left = rgba + (3 * width + 3) * 4; + const uint8_t *right = rgba + (3 * width + width - 4) * 4; + return near(left, 0xFF, 0, 0, 0xFF) && near(right, 0, 0, 0xFF, 0xFF) + ? nil + : @"the image does not fill the canvas"; + }); NSString *empty = @"{\"version\":1,\"size\":{\"width\":320,\"height\":240},\"strokes\":[]}"; [INKDocumentRenderer renderDocument:empty From 489ec48f8bdc6155e32e95c8da3f08491124aa07 Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Wed, 4 Nov 2026 21:00:12 +0100 Subject: [PATCH 15/17] fix(example): give thumbnails the canvas background, revoke blob URLs --- example/src/DrawScreen.tsx | 17 +++++++++++++---- example/src/ExportSheet.tsx | 32 ++++++++++++++++++++++++++------ 2 files changed, 39 insertions(+), 10 deletions(-) diff --git a/example/src/DrawScreen.tsx b/example/src/DrawScreen.tsx index 84209b6..9433080 100644 --- a/example/src/DrawScreen.tsx +++ b/example/src/DrawScreen.tsx @@ -1,6 +1,6 @@ -import { type RefObject, useState } from 'react'; +import { type RefObject, useMemo, useState } from 'react'; import { StyleSheet, View } from 'react-native'; -import { InkCanvas, type InkCanvasRef, type InkState } from 'react-native-inkpad'; +import { type Background, InkCanvas, type InkCanvasRef, type InkState } from 'react-native-inkpad'; import { brushFor, COLORS, type Tool } from './controls'; import { Dock } from './Dock'; import { ExportSheet } from './ExportSheet'; @@ -22,6 +22,10 @@ export function DrawScreen({ canvas, paper, pencilOnly, onChange, onError }: Pro const [color, setColor] = useState(COLORS[0]?.value ?? '#000000'); const [size, setSize] = useState(4); const [exporting, setExporting] = useState(false); + const background = useMemo( + () => ({ color: '#FFFFFF', image: paper ? PAPER : undefined, fit: 'cover' }), + [paper], + ); return ( @@ -30,7 +34,7 @@ export function DrawScreen({ canvas, paper, pencilOnly, onChange, onError }: Pro testID="canvas" tool={tool === 'eraser' ? 'erase' : 'draw'} brush={brushFor(tool, color, size)} - background={{ color: '#FFFFFF', image: paper ? PAPER : undefined, fit: 'cover' }} + background={background} inputMode={pencilOnly ? 'stylus' : 'any'} onError={(error) => onError(error.code)} style={[styles.canvas, { borderColor: theme.separator }]} @@ -45,7 +49,12 @@ export function DrawScreen({ canvas, paper, pencilOnly, onChange, onError }: Pro onSize={setSize} onExport={() => setExporting(true)} /> - setExporting(false)} /> + setExporting(false)} + /> ); } diff --git a/example/src/ExportSheet.tsx b/example/src/ExportSheet.tsx index a031ec5..a02923d 100644 --- a/example/src/ExportSheet.tsx +++ b/example/src/ExportSheet.tsx @@ -4,20 +4,35 @@ import SegmentedControl from '@expo/ui/community/segmented-control'; import * as Sharing from 'expo-sharing'; import { type RefObject, useEffect, useRef, useState } from 'react'; import { Image, PixelRatio, Platform, Share, StyleSheet, Text, View } from 'react-native'; -import { type ImageResult, type InkCanvasRef, renderImage } from 'react-native-inkpad'; +import { + type Background, + type ImageResult, + type InkCanvasRef, + renderImage, +} from 'react-native-inkpad'; import { useTheme } from './theme'; const FORMATS = ['PNG', 'SVG', 'JSON'] as const; type Format = (typeof FORMATS)[number]; -type Props = { canvas: RefObject; open: boolean; onClose(): void }; +type Props = { + canvas: RefObject; + background: Background; + open: boolean; + onClose(): void; +}; const kb = (text: string) => `${(text.length / 1024).toFixed(1)} KB`; // Enough to fill the preview; the full text would also become one huge accessibility label. const PREVIEW_CHARS = 700; -export function ExportSheet({ canvas, open, onClose }: Props) { +// On web, renderImage gives a blob: URL that holds the image until it is revoked. +const revoke = (result: ImageResult | null) => { + if (Platform.OS === 'web' && result?.uri.startsWith('blob:')) URL.revokeObjectURL(result.uri); +}; + +export function ExportSheet({ canvas, background, open, onClose }: Props) { const theme = useTheme(); const sheet = useRef(null); const [format, setFormat] = useState('PNG'); @@ -39,8 +54,11 @@ export function ExportSheet({ canvas, open, onClose }: Props) { if (format === 'PNG') { const result = await ink.toImage({ trim: { padding: 8 } }); const doc = await ink.getStrokes(); - const thumb = await renderImage(doc, { maxSize: 160, trim: { padding: 8 } }); - if (!live) return; + const thumb = await renderImage(doc, { maxSize: 160, trim: { padding: 8 }, background }); + if (!live) { + revoke(thumb); + return; + } setImage(result); setThumbnail(thumb); setStatus(`PNG · ${result.width} x ${result.height} px`); @@ -63,7 +81,9 @@ export function ExportSheet({ canvas, open, onClose }: Props) { return () => { live = false; }; - }, [canvas, open, format]); + }, [canvas, background, open, format]); + + useEffect(() => () => revoke(thumbnail), [thumbnail]); const reload = async () => { const ink = canvas.current; From c586d9ca3aba9c6b6c6050d50f319a3b20b4841b Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Wed, 4 Nov 2026 21:01:18 +0100 Subject: [PATCH 16/17] docs: note that image request headers aren't sent --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e4353e4..60bd9ae 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ export function SignatureField() { | `tool` | `'draw' \| 'erase'` | `'draw'` | The eraser removes whole strokes. | | `inputMode` | `'any' \| 'stylus'` | `'any'` | With `'stylus'`, only a pen draws and fingers go to the parent. | | `editable` | `boolean` | `true` | Set to `false` to turn drawing off. | -| `background` | `{ color, image, fit }` | transparent | Canvas color and an image under the ink, both exported. `image` takes an image source, `fit` is `'contain'` or `'cover'`. On web, an image from another origin needs CORS headers. | +| `background` | `{ color, image, fit }` | transparent | Canvas color and an image under the ink, both exported. `image` takes an image source, `fit` is `'contain'` or `'cover'`. On web, an image from another origin needs CORS headers. Request `headers` on the image source aren't sent. | | `onStrokeStart` | `() => void` | | Called when a stroke starts. | | `onStrokeEnd` | `() => void` | | Called when a stroke ends. | | `onChange` | `(state) => void` | | Called after every change with `{ strokeCount, canUndo, canRedo }`. | From 3430d335efde737eb2d96841221ffb812c01d04f Mon Sep 17 00:00:00 2001 From: Rayen Sbai Date: Wed, 4 Nov 2026 22:28:57 +0100 Subject: [PATCH 17/17] fix(example): keep the PNG export when the thumbnail fails --- example/src/ExportSheet.tsx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/example/src/ExportSheet.tsx b/example/src/ExportSheet.tsx index a02923d..991cdb5 100644 --- a/example/src/ExportSheet.tsx +++ b/example/src/ExportSheet.tsx @@ -54,14 +54,20 @@ export function ExportSheet({ canvas, background, open, onClose }: Props) { if (format === 'PNG') { const result = await ink.toImage({ trim: { padding: 8 } }); const doc = await ink.getStrokes(); - const thumb = await renderImage(doc, { maxSize: 160, trim: { padding: 8 }, background }); + let thumb: ImageResult | null = null; + let thumbError = ''; + try { + thumb = await renderImage(doc, { maxSize: 160, trim: { padding: 8 }, background }); + } catch (error) { + thumbError = ` · no thumbnail: ${(error as Error).message}`; + } if (!live) { revoke(thumb); return; } setImage(result); setThumbnail(thumb); - setStatus(`PNG · ${result.width} x ${result.height} px`); + setStatus(`PNG · ${result.width} x ${result.height} px${thumbError}`); } else if (format === 'SVG') { const svg = await ink.toSVG({ trim: true }); if (!live) return;