figdiff 0.0.0-stage → 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 figdiff contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,261 @@
-# Temporary Holding Version
+# figdiff
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Review design changes the way you review code.**
+
+`figdiff` compares two versions of a [FigCraft](https://github.com/storytold/figcraft) design file (`.figcraft`) and explains what changed, both as a readable list of changes and as before/after images.
+
+> **Status: early development (pre-alpha).** Phase 0 is in progress. The parser and a basic text diff exist (build with `npm run build`, then run `node dist/cli.js a.figcraft b.figcraft`); the HTML report, visual diff and GitHub Action are still planned. Commands in the usage section below are the intended interface and may change. Feedback is very welcome: please open an issue.
+
+> **Not affiliated.** figdiff is an independent community project. It is not made by, endorsed by, or connected to the FigCraft / ArtCraft authors. FigCraft is a trademark of its respective owners.
+
+---
+
+## Table of contents
+
+- [The problem](#the-problem)
+- [The idea](#the-idea)
+- [Planned usage](#planned-usage)
+- [How it will work](#how-it-will-work)
+- [Who is it for](#who-is-it-for)
+- [Roadmap](#roadmap)
+- [Risks and open questions](#risks-and-open-questions)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## The problem
+
+A `.figcraft` file is a zip archive. When it changes in a Git repository, GitHub and `git diff` can only say "binary file changed". A reviewer has no way to tell whether a designer moved one button or rebuilt a whole screen, short of opening the file in FigCraft and comparing by eye.
+
+Code has diffs, pull request comments, and review tools. Design files, stored in the same repositories, have none of that.
+
+## The idea
+
+figdiff gives design files the same review workflow as code:
+
+- **Semantic diff.** A list of changes in plain language, for example:
+  `Frame "Login" › Button "Sign in": fill #2563EB → #1D4ED8`
+- **Visual diff.** Before, after, and highlighted-difference images for every frame that changed.
+- **Automatic pull request comments.** A GitHub Action that posts both of the above on every pull request that touches a design file.
+
+## Planned usage
+
+> These commands are the intended interface and may change.
+
+**Compare two files locally**
+
+```sh
+npx figdiff before.figcraft after.figcraft
+```
+
+```text
+Page "App"
+  Frame "Components"
+    - Landscape › Time=Day › Sun (ellipse)
+    ~ Chip › Selected=On › Label: characters All trails → All routes
+  Frame "Home — Light"
+    ~ Status bar › Indicators › Signal › Bar 1: fills #0F172A → #E6172A
+    ~ Status bar › Indicators › Signal › Bar 1: width 3 → 15
+
+4 changes in 2 frames (1 removed, 3 property changes)
+```
+
+Useful flags: `--json` prints the summary and every change as JSON, and `--exit-code` exits with 1 when the files differ, so it can fail a CI step.
+
+**Generate a shareable report**
+
+```sh
+npx figdiff before.figcraft after.figcraft --html report.html
+```
+
+One self-contained HTML file with before/after images, a slider, and the list of changes. No server needed, so it can be sent by email or chat to a developer or client.
+
+**Compare against another Git branch**
+
+```sh
+npx figdiff design/app.figcraft --against main
+```
+
+**Run on every pull request**
+
+```yaml
+# .github/workflows/design-diff.yml
+name: Design diff
+on: pull_request
+
+jobs:
+  diff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: bintangyoga/figdiff@v1
+        with:
+          files: "design/**/*.figcraft"
+```
+
+## How it will work
+
+```text
+before.figcraft ─┐                    ┌─ semantic diff (changes as text/JSON)
+                 ├─► parse + match ──►┤
+after.figcraft  ─┘                    └─ visual diff (render + compare images)
+```
+
+1. **Parser.** Opens the `.figcraft` archive and reads its `document.json` into an internal model. This is the only part that depends on the file format, so it is isolated and versioned.
+2. **Differ.** Matches nodes between the two versions (by id, with fallbacks) and produces a list of added, removed, moved, and modified nodes.
+3. **Renderer.** Uses FigCraft's own headless CLI (`figcraft-cli`) to render the changed frames to images, then compares them pixel by pixel.
+4. **Reporters.** Terminal output, JSON, a self-contained HTML report, and a GitHub pull request comment.
+
+Design principles:
+
+- **Independent.** A separate project. It reads the public file format and uses the public CLI; it does not modify FigCraft.
+- **Local-first.** Runs on your machine or in your CI. No accounts, no servers, no telemetry.
+- **Resilient to format changes.** FigCraft is in alpha and its format may change. The parser is kept separate from the diff logic and tested against files from multiple FigCraft versions.
+- **Useful without Git.** The CLI and HTML report work on any two files.
+
+## Who is it for
+
+- **Developers** who receive design files and want to know what changed since the last version.
+- **Design engineers and designers who use Git**, and want design changes reviewed in pull requests.
+- **Freelancers and agencies** who exchange versions with clients and need a clear "what changed since last time" report.
+
+---
+
+## Roadmap
+
+Estimated timeline: about 18 weeks to v1.0, assuming one maintainer at roughly 10 hours per week. Each phase ends with a usable release, and the next phase starts only after the exit criteria are met.
+
+| Phase | Weeks | Goal | Release |
+| --- | --- | --- | --- |
+| 0 | 1–2 | Research and setup | n/a |
+| 1 | 3–6 | Semantic diff in the CLI | v0.1.0 |
+| 2 | 7–10 | HTML report and visual diff | v0.2.0 |
+| 3 | 11–14 | GitHub Action | v0.3.0 |
+| 4 | 15–18 | Public launch | v1.0.0 |
+| 5 | After v1.0 | Driven by user demand | n/a |
+
+### Phase 0: Research and setup (weeks 1–2)
+
+Confirm that FigCraft's file format and CLI are stable enough to build on, before writing product code.
+
+- [x] Download sample files from FigCraft's `examples/` folder, unzip them, and study the structure of `document.json`
+- [x] Document the node schema: id, type, name, parent, position, size, fills, strokes, text, auto layout, components, variables
+- [ ] Verify that node ids stay stable when a file is saved again (critical for matching nodes between versions)
+- [ ] Test `figcraft-cli render`, `export --node`, and `convert` on headless Linux
+- [ ] Check whether `figcraft-cli` is available as a prebuilt binary or must be built with Cargo
+- [ ] Check name availability on npm and GitHub; choose a fallback name if needed
+- [x] Set up the repository: TypeScript, tests, CI
+- [ ] Add linting and formatting (ESLint, Prettier)
+
+**Deliverables:** format notes (`docs/format-notes.md`), 5–10 before/after sample file pairs, a working project skeleton.
+
+**Exit criteria:** the `document.json` schema is understood and node ids are proven stable, or a fallback matching strategy is designed.
+
+### Phase 1: Semantic diff in the CLI (weeks 3–6)
+
+Deliver `figdiff a.figcraft b.figcraft` printing a correct list of changes in the terminal. No images yet.
+
+- [x] Parser for core properties: type, name, hierarchy, position, size, fills, strokes, corner radius, text, font
+- [ ] Node matching by id, with fallback to name and hierarchy path
+- [x] Detect added, removed, reparented, and modified nodes
+- [x] Group results by page and top-level frame so output is easy to read
+- [x] Summary line (for example, "12 changes in 3 frames")
+- [x] `--json` output for use by other tools
+- [x] `--exit-code` flag and stable exit codes (0 ok, 1 differences, 2 error)
+- [x] Detect changes in layer order
+- [ ] Tests using the sample file pairs from Phase 0
+
+**Release:** `v0.1.0` on npm, usable with `npx figdiff`.
+
+**Exit criteria:** on every sample pair, the list of changes is complete and contains no false changes.
+
+### Phase 2: HTML report and visual diff (weeks 7–10)
+
+Deliver a self-contained HTML report that anyone can open, including designers who do not use Git.
+
+- [ ] Render changed frames from both versions with `figcraft-cli export --node` at 1x and 2x
+- [ ] Pixel comparison with highlighted changed areas
+- [ ] Per-frame views: side by side, swipe slider, and difference overlay
+- [ ] Semantic change list next to the images; clicking a change highlights its location
+- [ ] A single `report.html` with embedded images and no server
+- [ ] Graceful fallback when `figcraft-cli` is unavailable: semantic diff only, with a clear message
+- [ ] `git difftool` integration and `--against <branch>` support
+
+**Release:** `v0.2.0`, with the first demo GIF in this README.
+
+**Exit criteria:** 3–5 people outside the project open the report and understand the changes without extra explanation.
+
+### Phase 3: GitHub Action (weeks 11–14)
+
+Deliver an automatic comment on every pull request that changes a `.figcraft` file, set up with one workflow file.
+
+- [ ] Detect changed `.figcraft` files in a pull request and check out both the base and head versions
+- [ ] Install `figcraft-cli` on the runner, with caching
+- [ ] Pull request comment with a summary, per-frame changes, and before/after images
+- [ ] Host images via workflow artifacts or a dedicated branch (GitHub comments need image URLs)
+- [ ] Update a single comment on each push instead of posting new ones
+- [ ] Configuration options: file patterns, render scale, frame limit, comment language
+- [ ] Public example repository that uses the Action as a live demo
+
+**Release:** `v0.3.0` and a listing on GitHub Marketplace.
+
+**Exit criteria:** the Action runs reliably on the example repository and on at least one real project.
+
+### Phase 4: Public launch (weeks 15–18)
+
+Deliver a project that other people can use and contribute to, then announce it.
+
+- [ ] Support for advanced properties: components and instances, variants, variables and tokens, effects, prototyping, images
+- [ ] Performance testing on large files (thousands of nodes); target a diff in a few seconds
+- [ ] Compatibility table of tested FigCraft versions, updated with each FigCraft release
+- [ ] Documentation: CLI guide, Action guide, contributor guide
+- [ ] `good first issue` labels to welcome contributors
+- [ ] Announcement: FigCraft community, Show HN, Reddit, and design communities
+
+**Release:** `v1.0.0`, with a stable CLI and JSON output format.
+
+### Phase 5: After v1.0
+
+Direction will follow user demand. Candidates:
+
+- **Three-way merge** of design files from different branches, with conflict markers
+- **Token and consistency checks** that warn in a pull request about colors or spacing outside the design system
+- **Other platforms:** GitLab CI, Gitea, Forgejo
+- **MCP server**, so AI agents can ask "what changed in this design?"
+- **Automatic design changelog** generated from Git tags
+- **Upstream collaboration:** open a diff report directly in FigCraft, if the maintainers are interested
+
+---
+
+## Risks and open questions
+
+| Risk | Impact | Mitigation |
+| --- | --- | --- |
+| The `.figcraft` format changes (FigCraft is alpha) | Parser breaks on new FigCraft releases | Isolated parser, compatibility table, tests on files from each version |
+| Node ids are not stable between saves | Diffs full of false changes | Fallback matching by name and path, validated in Phase 0 |
+| `figcraft-cli` is hard to install in CI | Slow or failing GitHub Action | Cache the binary; fall back to semantic diff only |
+| FigCraft adds its own diff feature | Less reason to use figdiff | Focus on review in Git and pull requests; talk to the maintainers early |
+| Small FigCraft user base | Slow adoption | Start from real needs; keep the core model usable for other formats later |
+
+Open questions:
+
+- Is the project name `figdiff` available on npm and GitHub?
+- Does `figcraft-cli` ship as a downloadable binary for Linux, macOS, and Windows?
+- How much of FigCraft's built-in `versions/` and `branches/` data is useful to reuse?
+
+## Contributing
+
+Contributions are welcome, even at this early stage. The most useful things right now:
+
+- Feedback on the plan: open an issue with your use case
+- Sample `.figcraft` file pairs (before/after) that you are allowed to share
+- Notes on the file format, once Phase 0 begins
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { run } from "./run.js";
+const result = run(process.argv.slice(2));
+process.stdout.write(result.stdout);
+process.stderr.write(result.stderr);
+process.exitCode = result.code;
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACpC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACpC,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC"}

package/dist/diff/diff.d.ts

@@ -0,0 +1,11 @@
+import type { Change, DesignNode } from "./types.js";
+/**
+ * Compare two design trees and list what changed.
+ *
+ * Nodes are matched by id. Fallback matching by name and path is planned
+ * for later, once id stability across saves is verified (see docs/format-notes.md).
+ *
+ * Changes come out in document order of the old tree, followed by added nodes
+ * in document order of the new tree.
+ */
+export declare function diffTrees(before: DesignNode, after: DesignNode): Change[];

package/dist/diff/diff.js

@@ -0,0 +1,68 @@
+const SEP = " › ";
+function index(root) {
+    const map = new Map();
+    const walk = (node, trail, parentId) => {
+        map.set(node.id, { node, trail, path: [root.name, ...trail].join(SEP), parentId });
+        for (const child of node.children)
+            walk(child, [...trail, child.name], node.id);
+    };
+    walk(root, [], null);
+    return map;
+}
+function sameValue(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+function diffProps(a, b) {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    const changes = [];
+    for (const prop of [...keys].sort()) {
+        if (!sameValue(a[prop], b[prop]))
+            changes.push({ prop, from: a[prop], to: b[prop] });
+    }
+    return changes;
+}
+/** True when children present in both versions appear in a different order. */
+function childOrderChanged(old, now) {
+    const inNow = new Set(now.children.map((c) => c.id));
+    const inOld = new Set(old.children.map((c) => c.id));
+    const orderBefore = old.children.map((c) => c.id).filter((id) => inNow.has(id));
+    const orderAfter = now.children.map((c) => c.id).filter((id) => inOld.has(id));
+    return orderBefore.join(",") !== orderAfter.join(",");
+}
+/**
+ * Compare two design trees and list what changed.
+ *
+ * Nodes are matched by id. Fallback matching by name and path is planned
+ * for later, once id stability across saves is verified (see docs/format-notes.md).
+ *
+ * Changes come out in document order of the old tree, followed by added nodes
+ * in document order of the new tree.
+ */
+export function diffTrees(before, after) {
+    const a = index(before);
+    const b = index(after);
+    const changes = [];
+    for (const [id, old] of a) {
+        const now = b.get(id);
+        if (!now) {
+            changes.push({ kind: "removed", id, path: old.path, trail: old.trail, type: old.node.type });
+            continue;
+        }
+        const base = { id, path: now.path, trail: now.trail };
+        if (old.parentId !== now.parentId) {
+            changes.push({ ...base, kind: "moved", fromTrail: old.trail });
+        }
+        const props = diffProps({ name: old.node.name, type: old.node.type, ...old.node.props }, { name: now.node.name, type: now.node.type, ...now.node.props });
+        if (props.length > 0)
+            changes.push({ ...base, kind: "modified", props });
+        if (childOrderChanged(old.node, now.node))
+            changes.push({ ...base, kind: "reordered" });
+    }
+    for (const [id, now] of b) {
+        if (!a.has(id)) {
+            changes.push({ kind: "added", id, path: now.path, trail: now.trail, type: now.node.type });
+        }
+    }
+    return changes;
+}
+//# sourceMappingURL=diff.js.map

package/dist/diff/diff.js.map

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

package/dist/diff/summary.d.ts

@@ -0,0 +1,3 @@
+import type { Change, Summary } from "./types.js";
+/** Count what changed. A "frame" is a direct child of a page that contains at least one change. */
+export declare function summarize(changes: Change[]): Summary;

package/dist/diff/summary.js

@@ -0,0 +1,40 @@
+/** Count what changed. A "frame" is a direct child of a page that contains at least one change. */
+export function summarize(changes) {
+    const s = {
+        changes: 0,
+        frames: 0,
+        added: 0,
+        removed: 0,
+        moved: 0,
+        reordered: 0,
+        modifiedNodes: 0,
+        propertyChanges: 0,
+    };
+    const frames = new Set();
+    for (const c of changes) {
+        if (c.trail.length >= 2)
+            frames.add(`${c.trail[0]}\u0000${c.trail[1]}`);
+        switch (c.kind) {
+            case "added":
+                s.added++;
+                break;
+            case "removed":
+                s.removed++;
+                break;
+            case "moved":
+                s.moved++;
+                break;
+            case "reordered":
+                s.reordered++;
+                break;
+            case "modified":
+                s.modifiedNodes++;
+                s.propertyChanges += c.props.length;
+                break;
+        }
+    }
+    s.frames = frames.size;
+    s.changes = s.added + s.removed + s.moved + s.reordered + s.propertyChanges;
+    return s;
+}
+//# sourceMappingURL=summary.js.map

package/dist/diff/summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../src/diff/summary.ts"],"names":[],"mappings":"AAEA,mGAAmG;AACnG,MAAM,UAAU,SAAS,CAAC,OAAiB;IACzC,MAAM,CAAC,GAAY;QACjB,OAAO,EAAE,CAAC;QACV,MAAM,EAAE,CAAC;QACT,KAAK,EAAE,CAAC;QACR,OAAO,EAAE,CAAC;QACV,KAAK,EAAE,CAAC;QACR,SAAS,EAAE,CAAC;QACZ,aAAa,EAAE,CAAC;QAChB,eAAe,EAAE,CAAC;KACnB,CAAC;IACF,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IAEjC,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACxE,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;YACf,KAAK,OAAO;gBACV,CAAC,CAAC,KAAK,EAAE,CAAC;gBACV,MAAM;YACR,KAAK,SAAS;gBACZ,CAAC,CAAC,OAAO,EAAE,CAAC;gBACZ,MAAM;YACR,KAAK,OAAO;gBACV,CAAC,CAAC,KAAK,EAAE,CAAC;gBACV,MAAM;YACR,KAAK,WAAW;gBACd,CAAC,CAAC,SAAS,EAAE,CAAC;gBACd,MAAM;YACR,KAAK,UAAU;gBACb,CAAC,CAAC,aAAa,EAAE,CAAC;gBAClB,CAAC,CAAC,eAAe,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;gBACpC,MAAM;QACV,CAAC;IACH,CAAC;IAED,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC;IACvB,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,eAAe,CAAC;IAC5E,OAAO,CAAC,CAAC;AACX,CAAC"}

package/dist/diff/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * figdiff's internal, format-independent model of a design.
+ * The FigCraft-specific parsing lives in src/parser/.
+ */
+export interface DesignNode {
+    /** Stable identifier of the node within the file. */
+    id: string;
+    /** Node type, for example "frame", "text", "rectangle". */
+    type: string;
+    /** Layer name shown in the editor. */
+    name: string;
+    /** Visual and layout properties: fills, strokes, size, position, and so on. */
+    props: Record<string, unknown>;
+    /** Children in layer order. */
+    children: DesignNode[];
+}
+export interface PropChange {
+    prop: string;
+    from: unknown;
+    to: unknown;
+}
+interface ChangeBase {
+    /** Id of the node the change is about. */
+    id: string;
+    /** Names from the page down to the node (the document name is not included). */
+    trail: string[];
+    /** `trail` joined with " › ", prefixed by the document name. */
+    path: string;
+}
+export type Change = (ChangeBase & {
+    kind: "added";
+    type: string;
+}) | (ChangeBase & {
+    kind: "removed";
+    type: string;
+}) | (ChangeBase & {
+    kind: "moved";
+    fromTrail: string[];
+}) | (ChangeBase & {
+    kind: "modified";
+    props: PropChange[];
+}) | (ChangeBase & {
+    kind: "reordered";
+});
+export interface Summary {
+    /** Total changes: added + removed + moved + reordered nodes + changed properties. */
+    changes: number;
+    /** Number of distinct top-level frames that contain at least one change. */
+    frames: number;
+    added: number;
+    removed: number;
+    moved: number;
+    reordered: number;
+    /** Number of nodes with at least one changed property. */
+    modifiedNodes: number;
+    /** Number of changed properties across all nodes. */
+    propertyChanges: number;
+}
+export {};

package/dist/diff/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/diff/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/diff/types.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { diffTrees } from "./diff/diff.js";
+export { summarize } from "./diff/summary.js";
+export { parseFigcraft, readDocumentJson, documentToTree } from "./parser/index.js";
+export { formatText, formatSummary, formatValue } from "./report.js";
+export { run } from "./run.js";
+export type { Change, DesignNode, PropChange, Summary } from "./diff/types.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { diffTrees } from "./diff/diff.js";
+export { summarize } from "./diff/summary.js";
+export { parseFigcraft, readDocumentJson, documentToTree } from "./parser/index.js";
+export { formatText, formatSummary, formatValue } from "./report.js";
+export { run } from "./run.js";
+//# 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,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC"}

package/dist/parser/document.d.ts

@@ -0,0 +1,12 @@
+import type { DesignNode } from "../diff/types.js";
+/**
+ * Convert the contents of a `.figcraft` file's `document.json` into figdiff's tree.
+ *
+ * Format (observed in FigCraft's example files, document version 1):
+ * - `nodes` is a flat map from node id (a string key) to the node
+ * - each node lists child ids in `children`; the root of the tree is each page in `pages`
+ * - numeric ids; `next_id` is the id counter
+ *
+ * See docs/format-notes.md.
+ */
+export declare function documentToTree(doc: unknown): DesignNode;

package/dist/parser/document.js

@@ -0,0 +1,71 @@
+/** Keys that describe structure rather than appearance; they are not diffed as props. */
+const STRUCTURAL_KEYS = new Set(["id", "name", "type", "children", "parent"]);
+/** Number of decimals kept when comparing numbers (absorbs float noise like 8.000000000000002). */
+const PRECISION = 10_000;
+function normalize(value) {
+    if (typeof value === "number")
+        return Math.round(value * PRECISION) / PRECISION;
+    if (Array.isArray(value))
+        return value.map(normalize);
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = normalize(v);
+        return out;
+    }
+    return value;
+}
+/**
+ * Convert the contents of a `.figcraft` file's `document.json` into figdiff's tree.
+ *
+ * Format (observed in FigCraft's example files, document version 1):
+ * - `nodes` is a flat map from node id (a string key) to the node
+ * - each node lists child ids in `children`; the root of the tree is each page in `pages`
+ * - numeric ids; `next_id` is the id counter
+ *
+ * See docs/format-notes.md.
+ */
+export function documentToTree(doc) {
+    if (doc === null || typeof doc !== "object")
+        throw new Error("document.json is not an object");
+    const d = doc;
+    if (d.format !== "figcraft") {
+        throw new Error(`Not a FigCraft document (format: ${JSON.stringify(d.format)})`);
+    }
+    const nodes = d.nodes;
+    const pages = d.pages;
+    if (!nodes || typeof nodes !== "object" || !Array.isArray(pages)) {
+        throw new Error("document.json has no `nodes` map or `pages` list");
+    }
+    const seen = new Set();
+    const build = (id) => {
+        const key = String(id);
+        const raw = nodes[key];
+        if (!raw)
+            throw new Error(`Node ${key} is referenced but missing from document.json`);
+        if (seen.has(key))
+            throw new Error(`Node ${key} appears more than once in the tree`);
+        seen.add(key);
+        const props = {};
+        for (const [k, v] of Object.entries(raw)) {
+            if (!STRUCTURAL_KEYS.has(k))
+                props[k] = normalize(v);
+        }
+        const children = Array.isArray(raw.children) ? raw.children.map(build) : [];
+        return {
+            id: key,
+            type: String(raw.type ?? "unknown"),
+            name: String(raw.name ?? ""),
+            props,
+            children,
+        };
+    };
+    return {
+        id: "document",
+        type: "document",
+        name: String(d.name ?? "Untitled"),
+        props: {},
+        children: pages.map(build),
+    };
+}
+//# sourceMappingURL=document.js.map

package/dist/parser/document.js.map

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

package/dist/parser/index.d.ts

@@ -0,0 +1,10 @@
+import type { DesignNode } from "../diff/types.js";
+export { documentToTree } from "./document.js";
+/**
+ * Read a .figcraft archive and return its parsed `document.json`.
+ *
+ * The archive is a zip containing `document.json`, and optionally
+ * `thumbnail.png`, `images/`, `versions/`, `branches/` and `library/`.
+ */
+export declare function readDocumentJson(path: string): unknown;
+export declare function parseFigcraft(path: string): DesignNode;

package/dist/parser/index.js

@@ -0,0 +1,21 @@
+import { readFileSync } from "node:fs";
+import { unzipSync, strFromU8 } from "fflate";
+import { documentToTree } from "./document.js";
+export { documentToTree } from "./document.js";
+/**
+ * Read a .figcraft archive and return its parsed `document.json`.
+ *
+ * The archive is a zip containing `document.json`, and optionally
+ * `thumbnail.png`, `images/`, `versions/`, `branches/` and `library/`.
+ */
+export function readDocumentJson(path) {
+    const files = unzipSync(new Uint8Array(readFileSync(path)));
+    const entry = files["document.json"];
+    if (!entry)
+        throw new Error(`${path}: no document.json found. Is this a .figcraft file?`);
+    return JSON.parse(strFromU8(entry));
+}
+export function parseFigcraft(path) {
+    return documentToTree(readDocumentJson(path));
+}
+//# sourceMappingURL=index.js.map

package/dist/parser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/parser/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,KAAK,CAAC,eAAe,CAAC,CAAC;IACrC,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,qDAAqD,CAAC,CAAC;IAC1F,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,cAAc,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC;AAChD,CAAC"}

package/dist/report.d.ts

@@ -0,0 +1,7 @@
+import type { Change, Summary } from "./diff/types.js";
+/** Render a property value for humans: colors as hex, paints in short form, everything else as JSON. */
+export declare function formatValue(value: unknown): string;
+/** One line, for example "12 changes in 3 frames (2 added, 1 removed, 9 property changes)". */
+export declare function formatSummary(s: Summary): string;
+/** Human-readable report, grouped by page and top-level frame. */
+export declare function formatText(changes: Change[]): string;

package/dist/report.js

@@ -0,0 +1,109 @@
+import { summarize } from "./diff/summary.js";
+const hex = (n) => Math.round(Math.min(1, Math.max(0, Number(n))) * 255)
+    .toString(16)
+    .padStart(2, "0")
+    .toUpperCase();
+function isColor(v) {
+    return typeof v === "object" && v !== null && "r" in v && "g" in v && "b" in v;
+}
+function colorToHex(c) {
+    const alpha = c.a === undefined ? 1 : Number(c.a);
+    return `#${hex(c.r)}${hex(c.g)}${hex(c.b)}${alpha < 1 ? hex(alpha) : ""}`;
+}
+function describePaint(p) {
+    if (typeof p !== "object" || p === null)
+        return undefined;
+    const paint = p;
+    const hidden = paint.visible === false ? " (hidden)" : "";
+    if (paint.type === "solid" && isColor(paint.color))
+        return colorToHex(paint.color) + hidden;
+    if (paint.type === "gradient") {
+        const stops = Array.isArray(paint.stops) ? paint.stops.length : 0;
+        return `${String(paint.kind ?? "")} gradient, ${stops} stops${hidden}`.trim();
+    }
+    if (typeof paint.type === "string")
+        return `${paint.type}${hidden}`;
+    return undefined;
+}
+/** Render a property value for humans: colors as hex, paints in short form, everything else as JSON. */
+export function formatValue(value) {
+    if (value === undefined || value === null)
+        return "(none)";
+    if (typeof value === "string")
+        return value;
+    if (isColor(value))
+        return colorToHex(value);
+    if (Array.isArray(value) && value.length > 0) {
+        const paints = value.map(describePaint);
+        if (paints.every((p) => p !== undefined))
+            return paints.join(", ");
+    }
+    if (Array.isArray(value) && value.length === 0)
+        return "(none)";
+    return JSON.stringify(value);
+}
+const SEP = " › ";
+const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+/** One line, for example "12 changes in 3 frames (2 added, 1 removed, 9 property changes)". */
+export function formatSummary(s) {
+    const parts = [];
+    if (s.added)
+        parts.push(`${s.added} added`);
+    if (s.removed)
+        parts.push(`${s.removed} removed`);
+    if (s.moved)
+        parts.push(`${s.moved} moved`);
+    if (s.reordered)
+        parts.push(`${s.reordered} reordered`);
+    if (s.propertyChanges)
+        parts.push(plural(s.propertyChanges, "property change"));
+    const where = s.frames > 0 ? ` in ${plural(s.frames, "frame")}` : "";
+    return `${plural(s.changes, "change")}${where} (${parts.join(", ")})`;
+}
+function describe(c, label) {
+    switch (c.kind) {
+        case "added":
+            return [`+ ${label} (${c.type})`];
+        case "removed":
+            return [`- ${label} (${c.type})`];
+        case "moved":
+            return [`> ${label}: moved from ${c.fromTrail.join(SEP) || "(root)"}`];
+        case "reordered":
+            return [`~ ${label}: layer order changed`];
+        case "modified":
+            return c.props.map((p) => `~ ${label}: ${p.prop} ${formatValue(p.from)} → ${formatValue(p.to)}`);
+    }
+}
+/** Human-readable report, grouped by page and top-level frame. */
+export function formatText(changes) {
+    if (changes.length === 0)
+        return "No changes.\n";
+    // page -> frame ("" for changes on the page itself) -> changes, in first-seen order
+    const pages = new Map();
+    for (const c of changes) {
+        const page = c.trail[0] ?? "(document)";
+        const frame = c.trail[1] ?? "";
+        const frames = pages.get(page) ?? new Map();
+        frames.set(frame, [...(frames.get(frame) ?? []), c]);
+        pages.set(page, frames);
+    }
+    const lines = [];
+    for (const [page, frames] of pages) {
+        lines.push(`Page "${page}"`);
+        for (const [frame, group] of frames) {
+            if (frame === "") {
+                for (const c of group)
+                    lines.push(...describe(c, "(page)").map((l) => `  ${l}`));
+                continue;
+            }
+            lines.push(`  Frame "${frame}"`);
+            for (const c of group) {
+                const label = c.trail.length > 2 ? c.trail.slice(2).join(SEP) : "(frame itself)";
+                lines.push(...describe(c, label).map((l) => `    ${l}`));
+            }
+        }
+    }
+    lines.push("", formatSummary(summarize(changes)));
+    return lines.join("\n") + "\n";
+}
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

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

package/dist/run.d.ts

@@ -0,0 +1,8 @@
+export declare const USAGE = "figdiff (pre-alpha)\n\nUsage:\n  figdiff <before.figcraft> <after.figcraft> [options]\n\nOptions:\n  --json        Print summary and changes as JSON\n  --exit-code   Exit with 1 when the files differ (0 when identical)\n  --help        Show this help\n\nExit codes: 0 ok, 1 differences found (only with --exit-code), 2 error.\n";
+export interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/** Run the CLI. Pure with respect to process state, so it can be tested. */
+export declare function run(argv: string[]): RunResult;

package/dist/run.js

@@ -0,0 +1,44 @@
+import { parseFigcraft } from "./parser/index.js";
+import { diffTrees } from "./diff/diff.js";
+import { summarize } from "./diff/summary.js";
+import { formatText } from "./report.js";
+export const USAGE = `figdiff (pre-alpha)
+
+Usage:
+  figdiff <before.figcraft> <after.figcraft> [options]
+
+Options:
+  --json        Print summary and changes as JSON
+  --exit-code   Exit with 1 when the files differ (0 when identical)
+  --help        Show this help
+
+Exit codes: 0 ok, 1 differences found (only with --exit-code), 2 error.
+`;
+const KNOWN_FLAGS = new Set(["--json", "--exit-code", "--help"]);
+/** Run the CLI. Pure with respect to process state, so it can be tested. */
+export function run(argv) {
+    const files = argv.filter((a) => !a.startsWith("--"));
+    const flags = new Set(argv.filter((a) => a.startsWith("--")));
+    if (flags.has("--help"))
+        return { code: 0, stdout: USAGE, stderr: "" };
+    const unknown = [...flags].filter((f) => !KNOWN_FLAGS.has(f));
+    if (unknown.length > 0) {
+        return { code: 2, stdout: "", stderr: `figdiff: unknown option ${unknown.join(", ")}\n\n${USAGE}` };
+    }
+    if (files.length !== 2) {
+        return { code: 2, stdout: "", stderr: `figdiff: expected two files\n\n${USAGE}` };
+    }
+    try {
+        const [beforePath, afterPath] = files;
+        const changes = diffTrees(parseFigcraft(beforePath), parseFigcraft(afterPath));
+        const stdout = flags.has("--json")
+            ? JSON.stringify({ summary: summarize(changes), changes }, null, 2) + "\n"
+            : formatText(changes);
+        const code = flags.has("--exit-code") && changes.length > 0 ? 1 : 0;
+        return { code, stdout, stderr: "" };
+    }
+    catch (err) {
+        return { code: 2, stdout: "", stderr: `figdiff: ${err instanceof Error ? err.message : String(err)}\n` };
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,CAAC,MAAM,KAAK,GAAG;;;;;;;;;;;CAWpB,CAAC;AAQF,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEjE,4EAA4E;AAC5E,MAAM,UAAU,GAAG,CAAC,IAAc;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAE9D,IAAI,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IAEvE,MAAM,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,2BAA2B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,EAAE,EAAE,CAAC;IACtG,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,kCAAkC,KAAK,EAAE,EAAE,CAAC;IACpF,CAAC;IAED,IAAI,CAAC;QACH,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,GAAG,KAAyB,CAAC;QAC1D,MAAM,OAAO,GAAG,SAAS,CAAC,aAAa,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC;QAC/E,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC;YAChC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI;YAC1E,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACxB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACtC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,YAAY,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3G,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "figdiff",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.0",
+  "description": "Review FigCraft design changes like code: semantic and visual diffs for .figcraft files.",
+  "author": "bintangyoga",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "figdiff": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bintangyoga/figdiff.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bintangyoga/figdiff/issues"
+  },
+  "homepage": "https://github.com/bintangyoga/figdiff#readme",
+  "keywords": [
+    "figcraft",
+    "design",
+    "diff",
+    "github-action",
+    "design-systems"
+  ],
+  "dependencies": {
+    "fflate": "^0.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}