@flighthq/shape-formats 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './shapeJson';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './shapeJson';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/shapeJson.d.ts

@@ -0,0 +1,13 @@
+import type { ImageResource, Shape } from '@flighthq/types';
+export interface ShapeBitmapReference {
+    index: number;
+}
+export interface ShapeJsonFormatOptions {
+    space?: number | string;
+}
+export interface ShapeJsonParseOptions {
+    resolveBitmap?: (reference: Readonly<ShapeBitmapReference>) => ImageResource | null;
+}
+export declare function formatShapeJson(shape: Readonly<Shape>, options?: Readonly<ShapeJsonFormatOptions>): string;
+export declare function parseShapeJson(text: string, options?: Readonly<ShapeJsonParseOptions>): Shape | null;
+//# sourceMappingURL=shapeJson.d.ts.map

package/dist/shapeJson.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shapeJson.d.ts","sourceRoot":"","sources":["../src/shapeJson.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAO5D,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,sBAAsB;IAErC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IAIpC,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,oBAAoB,CAAC,KAAK,aAAa,GAAG,IAAI,CAAC;CACrF;AAMD,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,sBAAsB,CAAC,GAAG,MAAM,CA+B1G;AAMD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GAAG,KAAK,GAAG,IAAI,CAqCpG"}

package/dist/shapeJson.js

@@ -0,0 +1,157 @@
+import { createMatrix } from '@flighthq/geometry';
+import { appendShapeBeginBitmapFill, appendShapeBeginFill, appendShapeBeginGradientFill, appendShapeCircle, appendShapeCubicCurveTo, appendShapeCurveTo, appendShapeDrawTriangles, appendShapeEllipse, appendShapeEndFill, appendShapeLineBitmapStyle, appendShapeLineGradientStyle, appendShapeLineStyle, appendShapeLineTo, appendShapeMoveTo, appendShapePath, appendShapeRectangle, appendShapeRoundRectangle, createShape, } from '@flighthq/shape';
+// Serializes a shape's full drawing-command stream to a native JSON string that `parseShapeJson`
+// restores losslessly. Every non-bitmap command round-trips exactly; `beginBitmapFill`/
+// `lineBitmapStyle` resources serialize as an ordinal `ShapeBitmapReference` (see the type) rather
+// than the live `ImageResource`.
+export function formatShapeJson(shape, options) {
+    const commands = shape.data.commands;
+    const entries = [];
+    let bitmapOrdinal = 0;
+    let i = 0;
+    while (i < commands.length) {
+        const key = commands[i];
+        const argCount = commands[i + 1];
+        const base = i + 2;
+        const args = [];
+        for (let a = 0; a < argCount; a++) {
+            const value = commands[base + a];
+            if (value === null) {
+                // An omitted fill/line matrix, or absent triangle indices/uv data.
+                args.push(null);
+            }
+            else if (isMatrixValue(value)) {
+                args.push({ a: value.a, b: value.b, c: value.c, d: value.d, tx: value.tx, ty: value.ty });
+            }
+            else if (isSerializableScalarOrArray(value)) {
+                // Numbers, strings (enum keywords), booleans, and numeric arrays (colors/ratios, path
+                // data/commands, triangle vertices) serialize verbatim through JSON.
+                args.push(value);
+            }
+            else {
+                // The only remaining object arg in the command registry is a live `ImageResource` bitmap;
+                // it has no serializable id, so it becomes an ordinal reference resolved on parse.
+                args.push({ bitmap: { index: bitmapOrdinal++ } });
+            }
+        }
+        entries.push({ key, args });
+        i += argCount + 2;
+    }
+    return JSON.stringify({ shapeFormat: SHAPE_JSON_FORMAT, commands: entries }, null, options?.space);
+}
+// Restores a `Shape` from a `formatShapeJson` string by replaying each command through the matching
+// `appendShape*` builder. Returns `null` for malformed JSON, a missing/mismatched `shapeFormat`
+// version tag, a non-array `commands` field, a malformed command entry, an unknown command key, or a
+// malformed argument. Bitmap-bearing commands whose reference cannot be resolved are dropped.
+export function parseShapeJson(text, options) {
+    let root;
+    try {
+        root = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!isPlainObject(root))
+        return null;
+    if (root.shapeFormat !== SHAPE_JSON_FORMAT)
+        return null;
+    const rawCommands = root.commands;
+    if (!Array.isArray(rawCommands))
+        return null;
+    const resolveBitmap = options?.resolveBitmap;
+    const shape = createShape();
+    for (const entry of rawCommands) {
+        if (!isPlainObject(entry))
+            return null;
+        const key = entry.key;
+        const rawArgs = entry.args;
+        if (typeof key !== 'string' || !Array.isArray(rawArgs))
+            return null;
+        const appender = SHAPE_COMMAND_APPENDERS[key];
+        if (appender === undefined)
+            return null;
+        const args = [];
+        let drop = false;
+        for (const raw of rawArgs) {
+            const reconstructed = reconstructShapeCommandArg(raw, resolveBitmap);
+            if (reconstructed === MALFORMED_ARG)
+                return null;
+            if (reconstructed === DROP_COMMAND) {
+                drop = true;
+                break;
+            }
+            args.push(reconstructed);
+        }
+        if (drop)
+            continue;
+        appender(shape, ...args);
+    }
+    return shape;
+}
+// Rebuilds a single command argument from its serialized form. Returns `MALFORMED_ARG` for an
+// unrecognized object shape and `DROP_COMMAND` when a bitmap reference cannot be resolved.
+function reconstructShapeCommandArg(value, resolveBitmap) {
+    if (value === null)
+        return null;
+    const type = typeof value;
+    if (type === 'number' || type === 'string' || type === 'boolean')
+        return value;
+    if (Array.isArray(value))
+        return value;
+    if (!isPlainObject(value))
+        return MALFORMED_ARG;
+    if (isPlainObject(value.bitmap) && typeof value.bitmap.index === 'number') {
+        const resolved = resolveBitmap?.({ index: value.bitmap.index }) ?? null;
+        return resolved === null ? DROP_COMMAND : resolved;
+    }
+    if (typeof value.a === 'number' &&
+        typeof value.b === 'number' &&
+        typeof value.c === 'number' &&
+        typeof value.d === 'number' &&
+        typeof value.tx === 'number' &&
+        typeof value.ty === 'number') {
+        return createMatrix(value.a, value.b, value.c, value.d, value.tx, value.ty);
+    }
+    return MALFORMED_ARG;
+}
+function isMatrixValue(value) {
+    return (isPlainObject(value) &&
+        typeof value.a === 'number' &&
+        typeof value.b === 'number' &&
+        typeof value.c === 'number' &&
+        typeof value.d === 'number' &&
+        typeof value.tx === 'number' &&
+        typeof value.ty === 'number');
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isSerializableScalarOrArray(value) {
+    const type = typeof value;
+    return type === 'number' || type === 'string' || type === 'boolean' || Array.isArray(value);
+}
+// Sentinel returned when a command argument is structurally invalid; parse aborts to `null`.
+const MALFORMED_ARG = Symbol('shapeFormats.malformedArg');
+// Sentinel returned when a bitmap reference cannot be resolved; the owning command is dropped.
+const DROP_COMMAND = Symbol('shapeFormats.dropCommand');
+const SHAPE_JSON_FORMAT = 1;
+const SHAPE_COMMAND_APPENDERS = {
+    beginBitmapFill: appendShapeBeginBitmapFill,
+    beginFill: appendShapeBeginFill,
+    beginGradientFill: appendShapeBeginGradientFill,
+    cubicCurveTo: appendShapeCubicCurveTo,
+    curveTo: appendShapeCurveTo,
+    drawCircle: appendShapeCircle,
+    drawEllipse: appendShapeEllipse,
+    drawPath: appendShapePath,
+    drawRectangle: appendShapeRectangle,
+    drawRoundRectangle: appendShapeRoundRectangle,
+    drawTriangles: appendShapeDrawTriangles,
+    endFill: appendShapeEndFill,
+    lineBitmapStyle: appendShapeLineBitmapStyle,
+    lineGradientStyle: appendShapeLineGradientStyle,
+    lineStyle: appendShapeLineStyle,
+    lineTo: appendShapeLineTo,
+    moveTo: appendShapeMoveTo,
+};
+//# sourceMappingURL=shapeJson.js.map

package/dist/shapeJson.js.map

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

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@flighthq/shape-formats",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/geometry": "0.1.0",
+    "@flighthq/shape": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Tree-shakable shape serialization codecs for @flighthq/shape (native command-stream JSON)",
+  "sideEffects": false
+}

package/src/shapeJson.test.ts

@@ -0,0 +1,164 @@
+import { createMatrix } from '@flighthq/geometry';
+import {
+  appendShapeBeginBitmapFill,
+  appendShapeBeginFill,
+  appendShapeBeginGradientFill,
+  appendShapeCubicCurveTo,
+  appendShapeCurveTo,
+  appendShapeEndFill,
+  appendShapeLineStyle,
+  appendShapeLineTo,
+  appendShapeMoveTo,
+  appendShapePath,
+  createShape,
+  getShapeCommandCount,
+} from '@flighthq/shape';
+import type { ImageResource } from '@flighthq/types';
+
+import { formatShapeJson, parseShapeJson } from './shapeJson';
+
+function createEveryNonBitmapCommandShape() {
+  const shape = createShape();
+  appendShapeBeginFill(shape, 0xff0000ff, 1);
+  appendShapeBeginGradientFill(
+    shape,
+    'linear',
+    [0xff0000ff, 0x0000ffff],
+    [1, 0.5],
+    [0, 255],
+    createMatrix(1, 0, 0, 1, 10, 20),
+    'pad',
+    'rgb',
+    0,
+  );
+  appendShapeLineStyle(shape, 2, 0x00ff00ff, 1, false, 'normal', 'round', 'miter', 3);
+  appendShapeMoveTo(shape, 0, 0);
+  appendShapeLineTo(shape, 100, 0);
+  appendShapeCurveTo(shape, 150, 50, 100, 100);
+  appendShapeCubicCurveTo(shape, 10, 10, 20, 20, 30, 30);
+  appendShapePath(shape, [1, 2], [0, 0, 50, 50], 'evenOdd');
+  appendShapeEndFill(shape);
+  return shape;
+}
+
+// A minimal stand-in for a live ImageResource; the codec never inspects resource internals, only
+// swaps the object for an ordinal reference and back.
+function createFakeBitmap(): ImageResource {
+  return { width: 4, height: 4 } as unknown as ImageResource;
+}
+
+describe('formatShapeJson', () => {
+  it('wraps the command stream in a versioned top-level object', () => {
+    const shape = createShape();
+    appendShapeBeginFill(shape, 0x112233ff, 1);
+    const parsed = JSON.parse(formatShapeJson(shape));
+    expect(parsed.shapeFormat).toBe(1);
+    expect(Array.isArray(parsed.commands)).toBe(true);
+    expect(parsed.commands[0]).toEqual({ key: 'beginFill', args: [0x112233ff, 1] });
+  });
+
+  it('serializes a matrix argument as its {a,b,c,d,tx,ty} fields', () => {
+    const shape = createShape();
+    appendShapeBeginGradientFill(shape, 'radial', [0], [1], [0], createMatrix(2, 0, 0, 3, 5, 7), 'pad', 'rgb', 0);
+    const parsed = JSON.parse(formatShapeJson(shape));
+    expect(parsed.commands[0].args[4]).toEqual({ a: 2, b: 0, c: 0, d: 3, tx: 5, ty: 7 });
+  });
+
+  it('serializes a bitmap resource as an ordinal reference, never the resource', () => {
+    const shape = createShape();
+    appendShapeBeginBitmapFill(shape, createFakeBitmap(), null, true, false);
+    const parsed = JSON.parse(formatShapeJson(shape));
+    expect(parsed.commands[0].args[0]).toEqual({ bitmap: { index: 0 } });
+    expect(parsed.commands[0].args[1]).toBeNull();
+    expect(parsed.commands[0].args[2]).toBe(true);
+    expect(parsed.commands[0].args[3]).toBe(false);
+  });
+
+  it('honors the space option for pretty-printing', () => {
+    const shape = createShape();
+    appendShapeEndFill(shape);
+    expect(formatShapeJson(shape, { space: 2 })).toContain('\n');
+  });
+});
+
+describe('parseShapeJson', () => {
+  it('round-trips every non-bitmap command losslessly', () => {
+    const shape = createEveryNonBitmapCommandShape();
+    const json = formatShapeJson(shape);
+    const restored = parseShapeJson(json);
+    expect(restored).not.toBeNull();
+    expect(getShapeCommandCount(restored!)).toBe(getShapeCommandCount(shape));
+    expect(formatShapeJson(restored!)).toBe(json);
+  });
+
+  it('returns null for malformed JSON', () => {
+    expect(parseShapeJson('{ not json')).toBeNull();
+  });
+
+  it('returns null for a missing version tag', () => {
+    expect(parseShapeJson(JSON.stringify({ commands: [] }))).toBeNull();
+  });
+
+  it('returns null for a mismatched version tag', () => {
+    expect(parseShapeJson(JSON.stringify({ shapeFormat: 2, commands: [] }))).toBeNull();
+  });
+
+  it('returns null when the top level is not an object', () => {
+    expect(parseShapeJson(JSON.stringify([]))).toBeNull();
+  });
+
+  it('returns null for an unknown command key', () => {
+    const json = JSON.stringify({ shapeFormat: 1, commands: [{ key: 'notACommand', args: [] }] });
+    expect(parseShapeJson(json)).toBeNull();
+  });
+
+  it('returns null for a malformed argument object', () => {
+    const json = JSON.stringify({ shapeFormat: 1, commands: [{ key: 'beginFill', args: [{ nonsense: true }, 1] }] });
+    expect(parseShapeJson(json)).toBeNull();
+  });
+
+  it('round-trips a bitmap fill through the resolver', () => {
+    const bitmap = createFakeBitmap();
+    const shape = createShape();
+    appendShapeBeginBitmapFill(shape, bitmap, createMatrix(1, 0, 0, 1, 3, 4), true, false);
+    appendShapeMoveTo(shape, 5, 6);
+
+    const seen: number[] = [];
+    const restored = parseShapeJson(formatShapeJson(shape), {
+      resolveBitmap: (reference) => {
+        seen.push(reference.index);
+        return bitmap;
+      },
+    });
+
+    expect(restored).not.toBeNull();
+    expect(seen).toEqual([0]);
+    expect(getShapeCommandCount(restored!)).toBe(2);
+    expect(restored!.data.commands[0]).toBe('beginBitmapFill');
+    expect(restored!.data.commands[2]).toBe(bitmap);
+  });
+
+  it('drops a bitmap fill when no resolver is supplied and keeps the rest intact', () => {
+    const shape = createShape();
+    appendShapeBeginFill(shape, 0xffffffff, 1);
+    appendShapeBeginBitmapFill(shape, createFakeBitmap(), null, true, false);
+    appendShapeLineTo(shape, 9, 9);
+
+    const restored = parseShapeJson(formatShapeJson(shape));
+    expect(restored).not.toBeNull();
+    expect(getShapeCommandCount(restored!)).toBe(2);
+    expect(restored!.data.commands[0]).toBe('beginFill');
+    expect(restored!.data.commands[4]).toBe('lineTo');
+  });
+
+  it('drops a bitmap fill when the resolver returns null', () => {
+    const shape = createShape();
+    appendShapeBeginBitmapFill(shape, createFakeBitmap(), null, true, false);
+    appendShapeEndFill(shape);
+
+    const restored = parseShapeJson(formatShapeJson(shape), { resolveBitmap: () => null });
+    expect(restored).not.toBeNull();
+    expect(getShapeCommandCount(restored!)).toBe(1);
+    expect(restored!.data.commands[0]).toBe('endFill');
+  });
+});