@arcblock/did-connect-service 4.1.55 → 4.1.57

package/dist/og/tree.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Runtime-neutral half of the tree renderer (`renderOgTree`, ArcBlock/did#300).
+ *
+ * A caller hands in a plain satori object tree (the same `{ type, props }`
+ * shape `templates.ts` builds). Before anything is parsed or rasterized, this
+ * module walks the whole tree and enforces the image contract:
+ *
+ *  - every image reference (`src`, `href`, any `url(...)` in a style or other
+ *    prop) must be a `data:` URI — anything else rejects the WHOLE render and
+ *    no request is ever made (keeps did#220's no-remote-media stance);
+ *  - the bytes must be PNG / JPEG / SVG by magic bytes, matching the declared
+ *    MIME type;
+ *  - hard limits are read from the image headers (never by decoding):
+ *    PNG/JPEG ≤ 1.5 MP and ≤ 1 MB each, SVG ≤ 256 KB, the whole tree
+ *    ≤ 2.5 MP and ≤ 2 MB of raw image bytes. Nothing is resized; an
+ *    over-limit tree is refused with a code that names the reason.
+ *
+ * Both runtime entries (`worker.ts` → `og-worker`, `tree-node.ts` → `og-node`)
+ * call {@link validateOgTree} and share {@link createSerialQueue}.
+ */
+import { OgValidationError } from "./types.js";
+/** Font weights a tree may declare. Fonts are loaded by the renderer per locale. */
+export type OgTreeWeight = 400 | 700;
+/** A satori node: `{ type, props }`, children under `props.children`. */
+export interface OgTreeNode {
+    type: string;
+    props?: Record<string, unknown>;
+}
+export interface OgTreeRenderOptions {
+    /** Plain satori object tree. Only `data:` image URIs are accepted. */
+    tree: OgTreeNode;
+    width: number;
+    height: number;
+    /** BCP-47-ish locale; selects the font family (normalized like og.png). */
+    locale: string;
+    /** Weights the tree uses. Defaults to `[400]`. Regular is always loaded. */
+    weights?: readonly OgTreeWeight[];
+}
+/** Font family name trees should use in `fontFamily` (same as the templates). */
+export declare const OG_TREE_FONT_FAMILY = "Noto";
+export declare const OG_TREE_LIMITS: {
+    /** PNG/JPEG: max pixels per image. */
+    readonly maxImagePixels: 1500000;
+    /** PNG/JPEG: max raw bytes per image. */
+    readonly maxImageBytes: 1000000;
+    /** SVG: max raw bytes per image. */
+    readonly maxSvgBytes: number;
+    /** Sum of PNG/JPEG pixels over every image occurrence in the tree. */
+    readonly maxTotalPixels: 2500000;
+    /** Sum of raw image bytes (all types) over every image occurrence. */
+    readonly maxTotalBytes: 2000000;
+    /** Image occurrences per tree. */
+    readonly maxImages: 32;
+    /** Output canvas. */
+    readonly maxCanvasDimension: 2400;
+    readonly maxCanvasPixels: 1000000;
+    /** Tree shape. */
+    readonly maxDepth: 64;
+    readonly maxNodes: 5000;
+    /** Characters per text string (satori lays out every glyph). */
+    readonly maxStringChars: 2000;
+    /** Characters of text over the whole tree. */
+    readonly maxTextChars: 10000;
+    /** Characters per non-image prop string; inline `<svg>` props (path data) get more. */
+    readonly maxPropStringChars: 2000;
+    readonly maxSvgPropStringChars: 16384;
+    /** Characters over all non-image prop strings in the tree. */
+    readonly maxPropChars: 65536;
+    /** box-shadow / text-shadow: entries per value; |offset| per entry, in px. */
+    readonly maxShadows: 4;
+    readonly maxShadowLengthPx: 100;
+    /** Blur radius and spread for shadows, drop-shadow() and blur(), in px — blur drives render cost. */
+    readonly maxBlurPx: 16;
+    readonly maxSpreadPx: 16;
+    /** CSS filter: functions per value. */
+    readonly maxFilterFunctions: 4;
+    /**
+     * Tree-wide effect budget, in units. Render cost of a shadow or filter
+     * follows the AREA it covers, not its blur radius (measured on the Worker
+     * stack: a full-canvas box-shadow ≈ 0.4 s, a CSS filter on a full-canvas
+     * group ≈ 1.6 s at blur 4px and 16px alike). An element's area unit count
+     * is ceil(width × height / 250,000) from numeric px `width`/`height` in its
+     * style, or the whole canvas when either is not a number. Charges:
+     * - each boxShadow entry: 1 × area units;
+     * - each CSS filter function: 1 × area units, `blur()` 4 × area units (so a
+     *   blur fits only on an element ≤ 250,000 px); filters are allowed only on
+     *   elements without children (a filtered group rasterizes its whole,
+     *   possibly overflowing, subtree: 6–8 s measured);
+     * - each textShadow entry: 1 per started 250 characters of every text
+     *   string it reaches (textShadow is inherited, so a declaration on a
+     *   container is paid for every text node below it).
+     * `drop-shadow()` is refused (use boxShadow).
+     */
+    readonly maxEffects: 4;
+    readonly effectAreaUnitPx: 250000;
+    readonly effectCostBlur: 4;
+    readonly textShadowCharsPerUnit: 250;
+    /** Inline <svg>: nodes and prop characters per tree (paths are costly to rasterize). */
+    readonly maxSvgNodes: 500;
+    readonly maxSvgChars: 16384;
+};
+export declare const OG_TREE_ERROR_CODES: {
+    readonly treeInvalid: "OG_TREE_INVALID";
+    readonly canvasInvalid: "OG_TREE_CANVAS_INVALID";
+    readonly weightsInvalid: "OG_TREE_WEIGHTS_INVALID";
+    readonly imageNotDataUri: "OG_IMAGE_NOT_DATA_URI";
+    readonly imageUnsupportedType: "OG_IMAGE_UNSUPPORTED_TYPE";
+    readonly imageUnreadable: "OG_IMAGE_UNREADABLE";
+    readonly imageTooManyPixels: "OG_IMAGE_TOO_MANY_PIXELS";
+    readonly imageTooLarge: "OG_IMAGE_TOO_LARGE";
+    readonly svgTooLarge: "OG_SVG_TOO_LARGE";
+    readonly svgUnsafe: "OG_SVG_UNSAFE";
+    readonly treeTooManyImages: "OG_TREE_TOO_MANY_IMAGES";
+    readonly treeTooManyPixels: "OG_TREE_TOO_MANY_PIXELS";
+    readonly treeTooManyBytes: "OG_TREE_TOO_MANY_BYTES";
+    readonly svgFilterForbidden: "OG_SVG_FILTER_FORBIDDEN";
+    readonly shadowLimit: "OG_TREE_SHADOW_LIMIT";
+    readonly cssFilterLimit: "OG_TREE_FILTER_LIMIT";
+    readonly textTooLong: "OG_TREE_TEXT_TOO_LONG";
+    /** satori/resvg failed on a tree that passed validation (generic; no input echoed). */
+    readonly renderFailed: "OG_TREE_RENDER_FAILED";
+};
+export type OgTreeErrorCode = (typeof OG_TREE_ERROR_CODES)[keyof typeof OG_TREE_ERROR_CODES];
+/** Rejection of a tree render. `statusCode` 400 (inherited): the input is at fault. */
+export declare class OgTreeRenderError extends OgValidationError {
+    readonly code: OgTreeErrorCode;
+    constructor(code: OgTreeErrorCode, message: string);
+}
+export declare const OG_RENDER_UNAVAILABLE_CODES: {
+    /** A font read did not finish within the timeout; the cached slot was dropped. */
+    readonly fontTimeout: "OG_FONT_TIMEOUT";
+    /** The render waited in the isolate/process queue past its deadline. */
+    readonly queueTimeout: "OG_QUEUE_TIMEOUT";
+};
+export type OgRenderUnavailableCode = (typeof OG_RENDER_UNAVAILABLE_CODES)[keyof typeof OG_RENDER_UNAVAILABLE_CODES];
+/** The renderer is temporarily unable to serve (font storage hung, queue backed up). Retryable: 503. */
+export declare class OgRenderUnavailableError extends Error {
+    readonly statusCode = 503;
+    readonly code: OgRenderUnavailableCode;
+    constructor(code: OgRenderUnavailableCode, message: string);
+}
+/** Rejects with `onTimeout()` if `promise` has not settled within `ms`. */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, onTimeout: () => Error): Promise<T>;
+export type OgImageKind = "png" | "jpeg" | "svg";
+/** Detects PNG / JPEG / SVG from the bytes themselves; anything else is `undefined`. */
+export declare function sniffOgImageKind(bytes: Uint8Array): OgImageKind | undefined;
+export declare function ogImageMime(kind: OgImageKind): string;
+export interface OgTreeImageStats {
+    imageCount: number;
+    totalPixels: number;
+    totalBytes: number;
+}
+/**
+ * Validates a tree render request without rendering. Throws an
+ * {@link OgTreeRenderError} naming the first violated rule; never performs I/O.
+ */
+export declare function validateOgTree(options: OgTreeRenderOptions): OgTreeImageStats;
+/** Validation for the renderers: returns the snapshot that was validated — render exactly this. */
+export declare function prepareOgTree(options: OgTreeRenderOptions): OgTreeNode;
+export type OgImageInspection = {
+    kind: OgImageKind;
+    width: number | null;
+    height: number | null;
+    bytes: number;
+} | {
+    code: OgTreeErrorCode;
+};
+/**
+ * Checks ONE image data: URI against the per-image rules (type, bytes, pixels,
+ * SVG safety) without rendering, so a caller can drop an image before building
+ * a tree. `width`/`height` are null for SVG. Tree-wide totals are not applied.
+ */
+export declare function inspectOgImage(dataUri: string): OgImageInspection;
+export declare function wantsBold(weights: readonly OgTreeWeight[] | undefined): boolean;
+export interface SerialTaskInfo {
+    /** Milliseconds the task waited in the queue before starting. */
+    queueMs: number;
+}
+export type SerialQueue = <T>(task: (info: SerialTaskInfo) => Promise<T>, options?: {
+    maxWaitMs?: number;
+}) => Promise<T>;
+/**
+ * A FIFO mutex: a task starts only after every previously queued task has
+ * settled (fulfilled or rejected). One queue per isolate/process keeps
+ * satori's per-render font parse and resvg's wasm heap from stacking.
+ *
+ * `maxWaitMs`: a task still waiting when the deadline passes is rejected with
+ * an {@link OgRenderUnavailableError} (`OG_QUEUE_TIMEOUT`) and never runs, so a
+ * wedged predecessor cannot pile up callers forever.
+ */
+export declare function createSerialQueue(): SerialQueue;
+//# sourceMappingURL=tree.d.ts.map

package/dist/og/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../../src/og/tree.ts"],"names":[],"mappings":"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"}