react-native-tgfx 0.0.0 → 0.0.2-alpha.0

package/lib/compiler/transform.js

@@ -0,0 +1,11 @@
+// React-Native-style transform arrays of single-key objects, composed left to right natively.
+export function toRadians(v) {
+    if (typeof v === 'number') {
+        return v;
+    }
+    const s = v.trim();
+    if (s.endsWith('deg')) {
+        return (parseFloat(s) * Math.PI) / 180;
+    }
+    return parseFloat(s);
+}

package/lib/compiler/values.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Reanimated value interop used by the compiler.
+ *
+ * A value passed to a drawing prop can be a plain JS value or a Reanimated
+ * `SharedValue`. SharedValues are detected structurally (the same brand check
+ * Reanimated and react-native-skia use) so this package never has to import
+ * Reanimated, keeping it an optional peer dependency.
+ *
+ * In the static compile path here we read `.value` to take a snapshot. The
+ * zero-JS-per-frame animation path (the Reanimated driver) instead has the
+ * scene writer allocate a value slot for each SharedValue, which the native
+ * engine patches on the UI thread.
+ */
+export interface MaybeSharedValue<T> {
+    value: T;
+    _isReanimatedSharedValue?: true;
+}
+export declare function isSharedValue(v: unknown): v is MaybeSharedValue<unknown>;
+/** Unwrap a possibly-shared value to its current concrete value. */
+export declare function resolveValue<T>(v: T | MaybeSharedValue<T>): T;
+/** Unwrap to a finite number, falling back to `fallback` for nullish input. */
+export declare function resolveNumber(v: unknown, fallback?: number): number;

package/lib/compiler/values.js

@@ -0,0 +1,22 @@
+export function isSharedValue(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        v._isReanimatedSharedValue ===
+            true);
+}
+/** Unwrap a possibly-shared value to its current concrete value. */
+export function resolveValue(v) {
+    if (isSharedValue(v)) {
+        return v.value;
+    }
+    return v;
+}
+/** Unwrap to a finite number, falling back to `fallback` for nullish input. */
+export function resolveNumber(v, fallback = 0) {
+    const raw = isSharedValue(v) ? v.value : v;
+    if (raw == null) {
+        return fallback;
+    }
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : fallback;
+}

package/lib/compiler/writer.d.ts

@@ -0,0 +1,70 @@
+import type { NodeHandle } from '../imperative';
+import { type MaybeSharedValue } from './values';
+/**
+ * Writer for the binary draw-program the native engine consumes.
+ *
+ * The program is a flat `Float64Array` written in tree preorder, so compiling a
+ * scene is a run of stores into one reused buffer — no intermediate objects and
+ * no JSON. Strings (path data, text, image sources, shader source) are rare and
+ * variable-width, so they travel beside the buffer in a string table and the
+ * buffer holds their indices.
+ *
+ * Layout, in words:
+ *
+ *     [0] VERSION
+ *     [1] total word count
+ *     [2] first word of the slot-patch table
+ *     [3..] node stream
+ *     [patch table] count, then (wordIndex, slotIndex) pairs
+ *
+ * A field backed by a Reanimated SharedValue is written as 0 and recorded in the
+ * patch table, so the engine knows which words to resolve against the live value
+ * array each frame.
+ */
+export declare const SCENE_VERSION = 16;
+/**
+ * Encode a string table as a delta against the one the engine already holds:
+ * element 0 is the number of leading entries it keeps, the rest replaces
+ * everything after them. Entries carry the payloads that scale with content
+ * rather than node count — path data, text, shader source — and they are
+ * byte-identical across commits, so re-sending them costs a Nitro marshal, a
+ * UTF-8 conversion and a full hash scan per commit for nothing. Images are not
+ * among them: they travel as an integer handle.
+ * Decoded by applyStringTable() in cpp/SceneStrings.hpp.
+ */
+export declare function packStringTable(prev: string[], next: string[]): string[];
+export declare const Kind: {
+    readonly Group: 0;
+    readonly Rect: 1;
+    readonly RRect: 2;
+    readonly Oval: 3;
+    readonly Circle: 4;
+    readonly Line: 5;
+    readonly Path: 6;
+    readonly Image: 7;
+    readonly Text: 8;
+    readonly Fill: 9;
+    readonly TextPath: 10;
+    readonly CameraFrame: 11;
+    readonly Glyphs: 12;
+};
+export declare class SceneWriter {
+    private words;
+    private n;
+    private readonly patches;
+    readonly strings: string[];
+    private readonly stringIds;
+    readonly values: MaybeSharedValue<unknown>[];
+    readonly refs: NodeHandle[];
+    reseed: boolean;
+    private readonly slots;
+    reset(): void;
+    push(value: number): void;
+    pushAnim(value: unknown, fallback?: number): void;
+    reserve(): number;
+    patch(at: number, value: number): void;
+    pushString(value: string): void;
+    hasSlot(value: MaybeSharedValue<unknown>): boolean;
+    private slot;
+    finish(): ArrayBuffer;
+}

package/lib/compiler/writer.js

@@ -0,0 +1,142 @@
+import { isSharedValue, resolveNumber } from './values';
+/**
+ * Writer for the binary draw-program the native engine consumes.
+ *
+ * The program is a flat `Float64Array` written in tree preorder, so compiling a
+ * scene is a run of stores into one reused buffer — no intermediate objects and
+ * no JSON. Strings (path data, text, image sources, shader source) are rare and
+ * variable-width, so they travel beside the buffer in a string table and the
+ * buffer holds their indices.
+ *
+ * Layout, in words:
+ *
+ *     [0] VERSION
+ *     [1] total word count
+ *     [2] first word of the slot-patch table
+ *     [3..] node stream
+ *     [patch table] count, then (wordIndex, slotIndex) pairs
+ *
+ * A field backed by a Reanimated SharedValue is written as 0 and recorded in the
+ * patch table, so the engine knows which words to resolve against the live value
+ * array each frame.
+ */
+// Every version and what it broke: docs/wire-format.md.
+export const SCENE_VERSION = 16;
+/**
+ * Encode a string table as a delta against the one the engine already holds:
+ * element 0 is the number of leading entries it keeps, the rest replaces
+ * everything after them. Entries carry the payloads that scale with content
+ * rather than node count — path data, text, shader source — and they are
+ * byte-identical across commits, so re-sending them costs a Nitro marshal, a
+ * UTF-8 conversion and a full hash scan per commit for nothing. Images are not
+ * among them: they travel as an integer handle.
+ * Decoded by applyStringTable() in cpp/SceneStrings.hpp.
+ */
+export function packStringTable(prev, next) {
+    let kept = 0;
+    while (kept < prev.length &&
+        kept < next.length &&
+        prev[kept] === next[kept]) {
+        kept++;
+    }
+    const packed = [String(kept)];
+    for (let i = kept; i < next.length; i++) {
+        packed.push(next[i]);
+    }
+    return packed;
+}
+export const Kind = {
+    Group: 0,
+    Rect: 1,
+    RRect: 2,
+    Oval: 3,
+    Circle: 4,
+    Line: 5,
+    Path: 6,
+    Image: 7,
+    Text: 8,
+    Fill: 9,
+    TextPath: 10,
+    CameraFrame: 11,
+    Glyphs: 12,
+};
+const HEADER_WORDS = 3;
+export class SceneWriter {
+    words = new Float64Array(4096);
+    n = HEADER_WORDS;
+    patches = [];
+    strings = [];
+    stringIds = new Map();
+    values = [];
+    refs = [];
+    reseed = true;
+    slots = new Map();
+    reset() {
+        this.n = HEADER_WORDS;
+        this.patches.length = 0;
+        this.strings.length = 0;
+        this.stringIds.clear();
+        this.values.length = 0;
+        this.refs.length = 0;
+        this.slots.clear();
+    }
+    push(value) {
+        if (this.n === this.words.length) {
+            const grown = new Float64Array(this.words.length * 2);
+            grown.set(this.words);
+            this.words = grown;
+        }
+        this.words[this.n++] = value;
+    }
+    pushAnim(value, fallback = 0) {
+        if (isSharedValue(value)) {
+            this.patches.push(this.n, this.slot(value));
+            // The literal is what native resolves against until the first setValues.
+            this.push(resolveNumber(value, fallback));
+            return;
+        }
+        const n = Number(value ?? fallback);
+        this.push(Number.isFinite(n) ? n : fallback);
+    }
+    reserve() {
+        const at = this.n;
+        this.push(0);
+        return at;
+    }
+    patch(at, value) {
+        this.words[at] = value;
+    }
+    pushString(value) {
+        let index = this.stringIds.get(value);
+        if (index === undefined) {
+            index = this.strings.length;
+            this.strings.push(value);
+            this.stringIds.set(value, index);
+        }
+        this.push(index);
+    }
+    hasSlot(value) {
+        return this.slots.has(value);
+    }
+    slot(sv) {
+        const existing = this.slots.get(sv);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const index = this.values.length;
+        this.values.push(sv);
+        this.slots.set(sv, index);
+        return index;
+    }
+    finish() {
+        const patchStart = this.n;
+        this.push(this.patches.length / 2);
+        for (const value of this.patches) {
+            this.push(value);
+        }
+        this.words[0] = SCENE_VERSION;
+        this.words[1] = this.n;
+        this.words[2] = patchStart;
+        return this.words.buffer;
+    }
+}

package/lib/components/Canvas.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+import type { CanvasProps } from '../types';
+/**
+ * The declarative tgfx canvas. Children (`<Rect>`, `<Circle>`, `<Path>`,
+ * `<Image>`, `<Text>`, `<Group>`, ...) are reconciled into an immutable node
+ * tree, compiled to a binary draw program (with live slots for any Reanimated
+ * SharedValue props), and handed to the native GPU view. When the scene has
+ * animated values, the {@link AnimationDriver} pushes them on the UI thread.
+ */
+export declare function Canvas({ children, style, composite, opaque, ref, }: CanvasProps): React.ReactElement;

package/lib/components/Canvas.js

@@ -0,0 +1,139 @@
+import React, { useEffect, useImperativeHandle, useRef, useState } from 'react';
+import { callback } from 'react-native-nitro-modules';
+import { packStringTable } from '../compiler/writer';
+import { AnimationDriver } from '../reanimated/AnimationDriver';
+import { isLive } from '../reanimated/liveValue';
+import { TgfxRoot } from '../reconciler/Reconciler';
+import { directNodes } from '../reconciler/directNodes';
+import { TgfxNativeView } from '../views/TgfxNativeView';
+let warnedNoDriver = false;
+function nativeOptions(options = {}) {
+    const rect = options.rect;
+    const scale = options.scale ?? 1;
+    // Rejected rather than clamped: natively this surfaces as a GPU allocation failure.
+    if (!Number.isFinite(scale) || scale <= 0) {
+        throw new Error(`[tgfx] snapshot: scale must be a positive finite number, got ${String(options.scale)}`);
+    }
+    if (rect != null &&
+        !(Number.isFinite(rect.x) &&
+            Number.isFinite(rect.y) &&
+            Number.isFinite(rect.width) &&
+            Number.isFinite(rect.height))) {
+        throw new Error('[tgfx] snapshot: rect must have four finite numbers');
+    }
+    return {
+        format: options.format ?? 'png',
+        // Documented as 1–100; an out-of-range value reaches ImageCodec::Encode raw.
+        quality: Math.min(100, Math.max(1, Math.round(options.quality ?? 100))),
+        x: rect?.x ?? 0,
+        y: rect?.y ?? 0,
+        width: rect?.width ?? 0,
+        height: rect?.height ?? 0,
+        scale,
+    };
+}
+function sameValueSet(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * The declarative tgfx canvas. Children (`<Rect>`, `<Circle>`, `<Path>`,
+ * `<Image>`, `<Text>`, `<Group>`, ...) are reconciled into an immutable node
+ * tree, compiled to a binary draw program (with live slots for any Reanimated
+ * SharedValue props), and handed to the native GPU view. When the scene has
+ * animated values, the {@link AnimationDriver} pushes them on the UI thread.
+ */
+export function Canvas({ children, style, composite = 'layer', opaque = false, ref, }) {
+    const [values, setValues] = useState([]);
+    const [view, setView] = useState(null);
+    const rootRef = useRef(null);
+    const viewRef = useRef(null);
+    const scene = useRef(null);
+    const prevValues = useRef([]);
+    const sentStrings = useRef([]);
+    const hybridRef = useRef(null);
+    if (hybridRef.current == null) {
+        hybridRef.current = callback((ref) => {
+            viewRef.current = ref;
+            sentStrings.current = [];
+            if (scene.current != null) {
+                const strings = scene.current.strings;
+                ref.setScene(scene.current.buffer, packStringTable([], strings));
+                sentStrings.current = strings.slice();
+                // A write before the view existed only moved its slot; the program carries the literals.
+                rootRef.current?.container.pushValues();
+            }
+            setView(ref);
+        });
+    }
+    const hybrid = hybridRef.current;
+    if (rootRef.current == null) {
+        // Straight to the hybrid object: as a prop it would ride a React and a Fabric commit per frame.
+        rootRef.current = new TgfxRoot((buffer, strings, vals) => {
+            scene.current = { buffer, strings };
+            if (viewRef.current != null) {
+                viewRef.current.setScene(buffer, packStringTable(sentStrings.current, strings));
+                sentStrings.current = strings.slice();
+            }
+            if (!sameValueSet(prevValues.current, vals)) {
+                prevValues.current = vals.slice();
+                setValues(prevValues.current);
+            }
+        });
+        rootRef.current.container.onValues = (vals) => viewRef.current?.setValues(vals);
+    }
+    useImperativeHandle(ref, () => ({
+        snapshot: async (options) => {
+            const view = viewRef.current;
+            if (view == null) {
+                throw new Error('[tgfx] snapshot: the canvas is not mounted yet');
+            }
+            const snap = await view.snapshot(nativeOptions(options));
+            return { ...snap, format: snap.format };
+        },
+        save: async (path, options) => {
+            const view = viewRef.current;
+            if (view == null) {
+                throw new Error('[tgfx] save: the canvas is not mounted yet');
+            }
+            await view.save(path, nativeOptions(options));
+        },
+        redraw: () => {
+            viewRef.current?.invalidate();
+        },
+    }), []);
+    useEffect(() => {
+        const root = rootRef.current;
+        if (root == null) {
+            return;
+        }
+        const direct = directNodes(children);
+        if (direct !== null) {
+            root.setDirect(direct);
+            return;
+        }
+        root.render(React.createElement(React.Fragment, null, children));
+    }, [children]);
+    useEffect(() => {
+        return () => {
+            rootRef.current?.unmount();
+        };
+    }, []);
+    // Slots this package writes need no driver, so they are not evidence Reanimated is missing.
+    if (AnimationDriver == null &&
+        !warnedNoDriver &&
+        values.some((value) => !isLive(value))) {
+        warnedNoDriver = true;
+        console.warn('[tgfx] SharedValue props need react-native-reanimated, which is not installed: they stay frozen at their last committed value.');
+    }
+    return (React.createElement(React.Fragment, null,
+        React.createElement(TgfxNativeView, { inHierarchy: composite === 'texture', opaque: opaque, style: style, hybridRef: hybrid }),
+        AnimationDriver != null && view != null && values.length > 0 ? (React.createElement(AnimationDriver, { view: view, values: values })) : null));
+}

package/lib/components/Group.d.ts

@@ -0,0 +1,7 @@
+import type { FC } from 'react';
+import type { GroupProps } from '../types';
+/**
+ * Groups children under a shared transform / opacity and supplies inherited
+ * paint defaults (color, style, strokeWidth, ...) to descendants.
+ */
+export declare const Group: FC<GroupProps>;

package/lib/components/Group.js

@@ -0,0 +1,6 @@
+import { NodeType } from '../reconciler/types';
+/**
+ * Groups children under a shared transform / opacity and supplies inherited
+ * paint defaults (color, style, strokeWidth, ...) to descendants.
+ */
+export const Group = NodeType.Group;

package/lib/components/Paint.d.ts

@@ -0,0 +1,45 @@
+import type { FC } from 'react';
+import type { BlendColorProps, BlurProps, ColorMatrixProps, DropShadowProps, ImageShaderProps, LinearGradientProps, NoiseProps, PaintComponentProps, RadialGradientProps, ShaderProps, SweepGradientProps } from '../types';
+/**
+ * Declarative paint. As a child of a shape it overrides that shape's paint; as
+ * a child of a `<Group>` it sets the inherited default paint for descendants. A
+ * gradient child (`<LinearGradient>` / `<RadialGradient>`) sets its shader.
+ */
+export declare const Paint: FC<PaintComponentProps>;
+/** Linear gradient shader; use inside a shape or `<Paint>`. */
+export declare const LinearGradient: FC<LinearGradientProps>;
+/** Radial gradient shader; use inside a shape or `<Paint>`. */
+export declare const RadialGradient: FC<RadialGradientProps>;
+/** Sweep (conic) gradient shader. `start`/`end` are in degrees, as in Skia. */
+export declare const SweepGradient: FC<SweepGradientProps>;
+/** Diamond gradient shader, drawn from the center to the diamond's vertices. */
+export declare const DiamondGradient: FC<RadialGradientProps>;
+/** Perlin fractal-noise shader. */
+export declare const FractalNoise: FC<NoiseProps>;
+/**
+ * A runtime shader. `source` is SkSL (the subset tgfx can translate); `uniforms`
+ * supplies a value per declared uniform.
+ */
+export declare const Shader: FC<ShaderProps>;
+/** Perlin turbulence shader — like fractal noise but with sharper patterns. */
+export declare const Turbulence: FC<NoiseProps>;
+/**
+ * An image as a paint source: textured fills, image-backed masks, tiled
+ * patterns. Use it wherever a gradient goes — inside a shape or a `<Paint>`.
+ */
+export declare const ImageShader: FC<ImageShaderProps>;
+/**
+ * A 4x5 colour matrix — saturation, hue rotation, greyscale, channel swaps.
+ * A paint child, like a gradient. Cheap: it is one more stage in the fragment
+ * shader, with no offscreen and no bounds change.
+ */
+export declare const ColorMatrix: FC<ColorMatrixProps>;
+/** Blends a constant colour into the drawing's own colours — a tint. */
+export declare const BlendColor: FC<BlendColorProps>;
+/**
+ * Gaussian blur. An *image* filter: the drawing goes through an offscreen layer
+ * and grows past its geometry, so it costs a render target per drawing.
+ */
+export declare const Blur: FC<BlurProps>;
+/** Drop shadow under the drawing. Same offscreen cost as `<Blur>`. */
+export declare const DropShadow: FC<DropShadowProps>;

package/lib/components/Paint.js

@@ -0,0 +1,44 @@
+import { NodeType } from '../reconciler/types';
+/**
+ * Declarative paint. As a child of a shape it overrides that shape's paint; as
+ * a child of a `<Group>` it sets the inherited default paint for descendants. A
+ * gradient child (`<LinearGradient>` / `<RadialGradient>`) sets its shader.
+ */
+export const Paint = NodeType.Paint;
+/** Linear gradient shader; use inside a shape or `<Paint>`. */
+export const LinearGradient = NodeType.LinearGradient;
+/** Radial gradient shader; use inside a shape or `<Paint>`. */
+export const RadialGradient = NodeType.RadialGradient;
+/** Sweep (conic) gradient shader. `start`/`end` are in degrees, as in Skia. */
+export const SweepGradient = NodeType.SweepGradient;
+/** Diamond gradient shader, drawn from the center to the diamond's vertices. */
+export const DiamondGradient = NodeType.DiamondGradient;
+/** Perlin fractal-noise shader. */
+export const FractalNoise = NodeType.FractalNoise;
+/**
+ * A runtime shader. `source` is SkSL (the subset tgfx can translate); `uniforms`
+ * supplies a value per declared uniform.
+ */
+export const Shader = NodeType.Shader;
+/** Perlin turbulence shader — like fractal noise but with sharper patterns. */
+export const Turbulence = NodeType.Turbulence;
+/**
+ * An image as a paint source: textured fills, image-backed masks, tiled
+ * patterns. Use it wherever a gradient goes — inside a shape or a `<Paint>`.
+ */
+export const ImageShader = NodeType.ImageShader;
+/**
+ * A 4x5 colour matrix — saturation, hue rotation, greyscale, channel swaps.
+ * A paint child, like a gradient. Cheap: it is one more stage in the fragment
+ * shader, with no offscreen and no bounds change.
+ */
+export const ColorMatrix = NodeType.ColorMatrix;
+/** Blends a constant colour into the drawing's own colours — a tint. */
+export const BlendColor = NodeType.BlendColor;
+/**
+ * Gaussian blur. An *image* filter: the drawing goes through an offscreen layer
+ * and grows past its geometry, so it costs a render target per drawing.
+ */
+export const Blur = NodeType.Blur;
+/** Drop shadow under the drawing. Same offscreen cost as `<Blur>`. */
+export const DropShadow = NodeType.DropShadow;

package/lib/components/drawings.d.ts

@@ -0,0 +1,56 @@
+import type { FC } from 'react';
+import type { CameraFrameProps, CircleProps, ImageProps, LineProps, OvalProps, PaintComponentProps, PathProps, RectProps, RoundedRectProps, GlyphsProps, SpanProps, TextPathProps, TextProps } from '../types';
+/** Axis-aligned rectangle. */
+export declare const Rect: FC<RectProps>;
+/** Rounded rectangle (`r`, or independent `rx`/`ry`). */
+export declare const RoundedRect: FC<RoundedRectProps>;
+/** Ellipse inscribed in the given rectangle. */
+export declare const Oval: FC<OvalProps>;
+/** Circle centered at (`cx`, `cy`) with radius `r`. */
+export declare const Circle: FC<CircleProps>;
+/** Straight line from (`x1`, `y1`) to (`x2`, `y2`). */
+export declare const Line: FC<LineProps>;
+/** Vector path from SVG path data. */
+export declare const Path: FC<PathProps>;
+/**
+ * One styled stretch inside a `<Text>` or `<TextPath>`. Spans lay out as one
+ * paragraph — they wrap and align together — and each draws with the face and
+ * colour it overrides. A `<Text>` with spans ignores its own `text` prop.
+ */
+export declare const Span: FC<SpanProps>;
+/**
+ * Glyphs you positioned yourself, drawn in one run. See {@link GlyphsProps}: no
+ * shaping and no fallback, which is the point — `<Text>` does all of that.
+ */
+export declare const Glyphs: FC<GlyphsProps>;
+/** Bitmap image drawn into the destination rect with the given `fit`. */
+export declare const Image: FC<ImageProps>;
+/**
+ * Text with its first baseline at (`x`, `y`). Breaks at `\n`, and wraps inside
+ * `width` when one is given.
+ */
+export declare const Text: FC<TextProps>;
+/** Text laid along an SVG path, one glyph per tangent. */
+export declare const TextPath: FC<TextPathProps>;
+/**
+ * Fills the whole canvas, so a runtime shader does not need to be told the
+ * canvas size to cover it. The tgfx counterpart of Skia's `<Fill>`.
+ *
+ * Coverage comes from the device-space clip, so a transform on an enclosing
+ * `<Group>` moves the paint but not the area filled, as it does in Skia.
+ */
+export declare const Fill: FC<PaintComponentProps>;
+/**
+ * A live camera frame, scaled to cover the canvas, with the scene drawn over it.
+ *
+ * Its children are laid out in **frame pixel** coordinates and share the one
+ * matrix that places the frame, so an overlay derived from the frame — a
+ * detector's box, a face contour — cannot drift from the image whatever the
+ * canvas size is. Pass detector output through unchanged; do not scale it.
+ *
+ * The frame arrives as a hardware-buffer handle
+ * (`imageFromNativeBuffer` + `image.setNativeBuffer`), which is imported
+ * straight to a GPU texture: the pixels are never copied, never encoded and
+ * never touched by the CPU.
+ */
+export declare const CameraFrame: FC<CameraFrameProps>;

package/lib/components/drawings.js

@@ -0,0 +1,55 @@
+import { NodeType } from '../reconciler/types';
+/** Axis-aligned rectangle. */
+export const Rect = NodeType.Rect;
+/** Rounded rectangle (`r`, or independent `rx`/`ry`). */
+export const RoundedRect = NodeType.RoundedRect;
+/** Ellipse inscribed in the given rectangle. */
+export const Oval = NodeType.Oval;
+/** Circle centered at (`cx`, `cy`) with radius `r`. */
+export const Circle = NodeType.Circle;
+/** Straight line from (`x1`, `y1`) to (`x2`, `y2`). */
+export const Line = NodeType.Line;
+/** Vector path from SVG path data. */
+export const Path = NodeType.Path;
+/**
+ * One styled stretch inside a `<Text>` or `<TextPath>`. Spans lay out as one
+ * paragraph — they wrap and align together — and each draws with the face and
+ * colour it overrides. A `<Text>` with spans ignores its own `text` prop.
+ */
+export const Span = NodeType.Span;
+/**
+ * Glyphs you positioned yourself, drawn in one run. See {@link GlyphsProps}: no
+ * shaping and no fallback, which is the point — `<Text>` does all of that.
+ */
+export const Glyphs = NodeType.Glyphs;
+/** Bitmap image drawn into the destination rect with the given `fit`. */
+export const Image = NodeType.Image;
+/**
+ * Text with its first baseline at (`x`, `y`). Breaks at `\n`, and wraps inside
+ * `width` when one is given.
+ */
+export const Text = NodeType.Text;
+/** Text laid along an SVG path, one glyph per tangent. */
+export const TextPath = NodeType.TextPath;
+/**
+ * Fills the whole canvas, so a runtime shader does not need to be told the
+ * canvas size to cover it. The tgfx counterpart of Skia's `<Fill>`.
+ *
+ * Coverage comes from the device-space clip, so a transform on an enclosing
+ * `<Group>` moves the paint but not the area filled, as it does in Skia.
+ */
+export const Fill = NodeType.Fill;
+/**
+ * A live camera frame, scaled to cover the canvas, with the scene drawn over it.
+ *
+ * Its children are laid out in **frame pixel** coordinates and share the one
+ * matrix that places the frame, so an overlay derived from the frame — a
+ * detector's box, a face contour — cannot drift from the image whatever the
+ * canvas size is. Pass detector output through unchanged; do not scale it.
+ *
+ * The frame arrives as a hardware-buffer handle
+ * (`imageFromNativeBuffer` + `image.setNativeBuffer`), which is imported
+ * straight to a GPU texture: the pixels are never copied, never encoded and
+ * never touched by the CPU.
+ */
+export const CameraFrame = NodeType.CameraFrame;

package/lib/hooks/source.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The three ways bytes reach native. Images and fonts both have exactly these,
+ * so the routing below — which of the three a given source needs — is written
+ * once rather than once per asset kind.
+ */
+export interface SourceReader<T> {
+    fromFile(path: string): Promise<T>;
+    fromBytes(bytes: ArrayBuffer): Promise<T>;
+    fromBase64(data: string): Promise<T>;
+}
+/**
+ * Load a `require()`d asset, a URI or a raw base64 string through `api`.
+ *
+ * A local file is opened natively, so its bytes never enter JS at all. Only a
+ * remote or Metro-served URI still goes through `fetch`, and then as an
+ * `ArrayBuffer` — nothing is ever base64-encoded on the JS thread.
+ */
+export declare function loadSource<T>(source: number | string, api: SourceReader<T>, signal?: AbortSignal): Promise<T>;