Add .xircuits minifier, zoom/background controls, bump to v0.2.0

Author: MFA-X-AI

xircuits-graph-viewer/__tests__/minify.test.ts

@@ -0,0 +1,166 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import { parse } from '../packages/core/src/parser/parse.js';
+import {
+  minify,
+  minifyWithStats,
+} from '../packages/core/src/minifier/index.js';
+
+const fixtureDir = resolve(__dirname, 'fixtures');
+
+function loadFixture(name: string): unknown {
+  return JSON.parse(readFileSync(resolve(fixtureDir, name), 'utf-8'));
+}
+
+function collectIds(obj: unknown, out: Set<string> = new Set()): Set<string> {
+  if (obj && typeof obj === 'object') {
+    if (!Array.isArray(obj)) {
+      const o = obj as Record<string, unknown>;
+      if (typeof o.id === 'string') out.add(o.id);
+      for (const v of Object.values(o)) collectIds(v, out);
+    } else {
+      for (const v of obj) collectIds(v, out);
+    }
+  }
+  return out;
+}
+
+describe('minify (safe mode)', () => {
+  const input = loadFixture('HelloXircuits.xircuits');
+
+  it('produces valid .xircuits JSON that parse() accepts', () => {
+    const out = minify(input);
+    const reparsed = JSON.parse(out);
+    expect(() => parse(reparsed)).not.toThrow();
+  });
+
+  it('preserves every original ID byte-for-byte', () => {
+    const out = minify(input);
+    const reparsed = JSON.parse(out);
+    const originalIds = collectIds(input);
+    const outputIds = collectIds(reparsed);
+    for (const id of originalIds) {
+      expect(outputIds.has(id)).toBe(true);
+    }
+  });
+
+  it('strips selected and locked keys throughout', () => {
+    const out = minify(input);
+    expect(out).not.toMatch(/"selected":/);
+    expect(out).not.toMatch(/"locked":/);
+  });
+
+  it('rounds coordinates to the requested precision', () => {
+    const out = minify(input, { precision: 0 });
+    const reparsed = JSON.parse(out) as Record<string, unknown>;
+    const layers = reparsed.layers as Array<Record<string, unknown>>;
+    const nodeLayer = layers.find(l => l.type === 'diagram-nodes')!;
+    for (const node of Object.values(nodeLayer.models as Record<string, Record<string, unknown>>)) {
+      expect(Number.isInteger(node.x)).toBe(true);
+      expect(Number.isInteger(node.y)).toBe(true);
+    }
+  });
+
+  it('honors non-zero precision', () => {
+    const out = minify(input, { precision: 1 });
+    const reparsed = JSON.parse(out) as Record<string, unknown>;
+    const layers = reparsed.layers as Array<Record<string, unknown>>;
+    const nodeLayer = layers.find(l => l.type === 'diagram-nodes')!;
+    for (const node of Object.values(nodeLayer.models as Record<string, Record<string, unknown>>)) {
+      const x = node.x as number;
+      expect(Math.abs(x * 10 - Math.round(x * 10))).toBeLessThan(1e-9);
+    }
+  });
+
+  it('reports consistent stats', () => {
+    const { output, stats } = minifyWithStats(input);
+    expect(stats.outputBytes).toBe(new TextEncoder().encode(output).length);
+    expect(stats.mode).toBe('safe');
+    expect(stats.nodes).toBeGreaterThan(0);
+    expect(stats.edges).toBeGreaterThan(0);
+    expect(stats.ports).toBeGreaterThan(0);
+  });
+});
+
+describe('minify (aggressive mode)', () => {
+  const input = loadFixture('HelloXircuits.xircuits');
+
+  it('produces valid .xircuits JSON that parse() accepts', () => {
+    const out = minify(input, { aggressive: true });
+    const reparsed = JSON.parse(out);
+    expect(() => parse(reparsed)).not.toThrow();
+  });
+
+  it('replaces every original ID with a short form', () => {
+    const out = minify(input, { aggressive: true });
+    const reparsed = JSON.parse(out);
+    const originalIds = collectIds(input);
+    const outputIds = collectIds(reparsed);
+    for (const id of originalIds) {
+      expect(outputIds.has(id)).toBe(false);
+    }
+    for (const id of outputIds) {
+      expect(id === 'g' || /^[nep]\d+$/.test(id)).toBe(true);
+    }
+  });
+
+  it('still resolves every link endpoint to a real node + port', () => {
+    const out = minify(input, { aggressive: true });
+    const graph = parse(JSON.parse(out));
+    const nodeIds = new Set(graph.nodes.map(n => n.id));
+    const portIds = new Set(graph.nodes.flatMap(n => [...n.portsIn, ...n.portsOut]).map(p => p.id));
+
+    for (const edge of graph.edges) {
+      expect(nodeIds.has(edge.sourceNodeId)).toBe(true);
+      expect(nodeIds.has(edge.targetNodeId)).toBe(true);
+      expect(portIds.has(edge.sourcePortId)).toBe(true);
+      expect(portIds.has(edge.targetPortId)).toBe(true);
+    }
+  });
+
+  it('preserves port ordering after rename', () => {
+    const src = input as Record<string, unknown>;
+    const origLayers = src.layers as Array<Record<string, unknown>>;
+    const origNodeLayer = origLayers.find(l => l.type === 'diagram-nodes')!;
+    const origModels = origNodeLayer.models as Record<string, Record<string, unknown>>;
+
+    const out = minify(input, { aggressive: true });
+    const reparsed = JSON.parse(out) as Record<string, unknown>;
+    const newLayers = reparsed.layers as Array<Record<string, unknown>>;
+    const newNodeLayer = newLayers.find(l => l.type === 'diagram-nodes')!;
+    const newModels = newNodeLayer.models as Record<string, Record<string, unknown>>;
+
+    const origNodes = Object.values(origModels);
+    const newNodes = Object.values(newModels);
+    expect(newNodes.length).toBe(origNodes.length);
+
+    for (let i = 0; i < origNodes.length; i++) {
+      const origInCount = (origNodes[i].portsInOrder as string[]).length;
+      const origOutCount = (origNodes[i].portsOutOrder as string[]).length;
+      expect((newNodes[i].portsInOrder as string[]).length).toBe(origInCount);
+      expect((newNodes[i].portsOutOrder as string[]).length).toBe(origOutCount);
+    }
+  });
+
+  it('strips viewer-unused fields', () => {
+    const out = minify(input, { aggressive: true });
+    expect(out).not.toMatch(/"curvyness":/);
+    expect(out).not.toMatch(/"selectedColor":/);
+    expect(out).not.toMatch(/"isSvg":/);
+    expect(out).not.toMatch(/"transformed":/);
+    expect(out).not.toMatch(/"alignment":/);
+    expect(out).not.toMatch(/"parentNode":/);
+  });
+
+  it('beats safe mode on size', () => {
+    const safe = minify(input, { aggressive: false });
+    const aggr = minify(input, { aggressive: true });
+    expect(aggr.length).toBeLessThan(safe.length);
+  });
+
+  it('tags stats as aggressive', () => {
+    const { stats } = minifyWithStats(input, { aggressive: true });
+    expect(stats.mode).toBe('aggressive');
+  });
+});

xircuits-graph-viewer/packages/core/README.md

@@ -51,6 +51,33 @@ import { getCanvasStyle } from '@xpressai/xircuits-viewer';
 container.style.cssText = getCanvasStyle('dark');
 ```
 
+## Minifier
+
+`.xircuits` files from the Xircuits editor carry full UUIDs and high-precision coordinates that the viewer doesn't need. A bundled minifier cuts file size 57–85% so workflows load faster over the network.
+
+### CLI
+
+```bash
+# Safe mode (best-effort compatible with the JupyterLab editor)
+npx xircuits-minify MyWorkflow.xircuits
+
+# Viewer-only; shortens UUIDs and strips cosmetic fields
+npx xircuits-minify MyWorkflow.xircuits --aggressive
+
+# Tune coordinate precision (default 0 = integer pixels)
+npx xircuits-minify MyWorkflow.xircuits --precision 1
+```
+
+### Library
+
+```js
+import { minify, minifyWithStats } from '@xpressai/xircuits-viewer';
+
+const compact = minify(workflowJson, { aggressive: true });
+const { output, stats } = minifyWithStats(workflowJson);
+// stats: { inputBytes, outputBytes, ratio, nodes, edges, ports, mode, precision }
+```
+
 ## API
 
 | Function | Description |
@@ -63,6 +90,8 @@ container.style.cssText = getCanvasStyle('dark');
 | `validate(json)` | Validate without parsing |
 | `getCanvasStyle(theme?)` | CSS string for the dot-grid container background |
 | `attachPanZoom(svg, options?)` | Add pan/zoom, returns `{ destroy, zoomBy, fitView }` |
+| `minify(json, options?)` | Minify a `.xircuits` JSON, returns compact string |
+| `minifyWithStats(json, options?)` | Same, plus size/counts stats |
 
 ### RenderOptions
 

xircuits-graph-viewer/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpressai/xircuits-viewer",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -14,12 +14,18 @@
       "import": "./dist/interaction/panZoom.js"
     }
   },
-  "files": ["dist"],
+  "bin": {
+    "xircuits-minify": "./dist/minifier/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && chmod +x ./dist/minifier/cli.js",
     "dev": "tsc --watch"
   },
   "devDependencies": {
+    "@types/node": "^25.6.0",
     "typescript": "^5.8.3"
   }
 }

xircuits-graph-viewer/packages/core/src/index.ts

@@ -23,6 +23,10 @@ export { computeViewBox } from './layout/viewBox.js';
 // Renderer
 export { renderToString, renderToElement } from './render/renderGraph.js';
 
+// Minifier
+export { minify, minifyWithStats } from './minifier/index.js';
+export type { MinifyOptions, MinifyStats } from './minifier/index.js';
+
 // Convenience: one-shot parse + render
 export { renderXircuits } from './render/renderGraph.js';
 

xircuits-graph-viewer/packages/core/src/minifier/cli.ts

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, extname, join } from 'node:path';
+import { validate } from '../parser/validate.js';
+import { minifyWithStats } from './index.js';
+
+function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / 1024 / 1024).toFixed(2)} MB`;
+}
+
+function printUsage() {
+  process.stderr.write(
+    [
+      'Usage: xircuits-minify <input.xircuits> [-o <output>] [--precision N] [--aggressive]',
+      '',
+      'Options:',
+      '  -o, --output <path>   Output path (default: <input>.min.xircuits)',
+      '      --precision N     Coordinate decimal places (default: 0)',
+      '      --aggressive      Shorten IDs and strip viewer-unused fields (viewer-only)',
+      '  -h, --help            Show this help',
+      '',
+    ].join('\n')
+  );
+}
+
+interface Args {
+  input?: string;
+  output?: string;
+  precision: number;
+  aggressive: boolean;
+  help: boolean;
+}
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = { precision: 0, aggressive: false, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') {
+      args.help = true;
+    } else if (a === '-o' || a === '--output') {
+      args.output = argv[++i];
+    } else if (a === '--precision') {
+      args.precision = Number(argv[++i]);
+      if (!Number.isFinite(args.precision) || args.precision < 0) {
+        throw new Error(`Invalid --precision value: must be a non-negative number`);
+      }
+    } else if (a === '--aggressive') {
+      args.aggressive = true;
+    } else if (a.startsWith('-')) {
+      throw new Error(`Unknown flag: ${a}`);
+    } else if (!args.input) {
+      args.input = a;
+    } else {
+      throw new Error(`Unexpected positional argument: ${a}`);
+    }
+  }
+  return args;
+}
+
+function defaultOutput(input: string): string {
+  const ext = extname(input);
+  const base = basename(input, ext);
+  return join(dirname(input), `${base}.min${ext || '.xircuits'}`);
+}
+
+function main() {
+  let args: Args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (e) {
+    process.stderr.write(`Error: ${(e as Error).message}\n\n`);
+    printUsage();
+    process.exit(1);
+  }
+
+  if (args.help || !args.input) {
+    printUsage();
+    process.exit(args.help ? 0 : 1);
+  }
+
+  const inputPath = args.input;
+  const outputPath = args.output ?? defaultOutput(inputPath);
+
+  let raw: string;
+  try {
+    raw = readFileSync(inputPath, 'utf8');
+  } catch (e) {
+    process.stderr.write(`Error reading ${inputPath}: ${(e as Error).message}\n`);
+    process.exit(1);
+  }
+
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch (e) {
+    process.stderr.write(`Error parsing ${inputPath}: ${(e as Error).message}\n`);
+    process.exit(1);
+  }
+
+  const { valid, errors } = validate(json);
+  if (!valid) {
+    process.stderr.write(`Invalid .xircuits file: ${errors.join(', ')}\n`);
+    process.exit(1);
+  }
+
+  const { output, stats } = minifyWithStats(json, {
+    precision: args.precision,
+    aggressive: args.aggressive,
+  });
+
+  writeFileSync(outputPath, output, 'utf8');
+
+  const onDiskInputBytes = Buffer.byteLength(raw, 'utf8');
+  const savings = onDiskInputBytes - stats.outputBytes;
+  const pct = onDiskInputBytes === 0 ? 0 : (1 - stats.outputBytes / onDiskInputBytes) * 100;
+  const inName = basename(inputPath);
+  const outName = basename(outputPath);
+  const pad = Math.max(inName.length, outName.length);
+
+  process.stderr.write(
+    [
+      `Input:    ${inName.padEnd(pad)}   ${formatBytes(onDiskInputBytes)}`,
+      `Output:   ${outName.padEnd(pad)}   ${formatBytes(stats.outputBytes)}`,
+      `Savings:  ${formatBytes(savings)}  (${pct.toFixed(1)}% reduction)`,
+      '',
+      `Mode:     ${stats.mode}`,
+      `Nodes:    ${stats.nodes}     Edges: ${stats.edges}     Ports: ${stats.ports}`,
+      `Precision: ${stats.precision} decimals`,
+      '',
+    ].join('\n')
+  );
+}
+
+main();