@akesson/figma-explorer 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -7,6 +7,109 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-09-23
+
+### Fixed
+
+- **`cache prefetch` now backfills a missing `.full.json.gz` sidecar.** A file
+  first cached by opening it via URL (`ls <url>`, `node-info <url>`, …) has a
+  payload but no full sidecar, and prefetch used to count it as up to date
+  forever — so `node-info --cache-only` never worked offline for it. Prefetch
+  now refetches an unchanged file whose full sidecar is missing or stamped
+  with another schema version (unless `--no-full`).
+- **Root `ls` no longer lists folders with no cached files.** A folder dropped
+  from `FIGMA_PROJECTS_IDS` keeps its `proj:N` id (synthetic ids are stable),
+  and root `ls` rendered it as an empty project named by its raw folder id
+  (e.g. `proj:3 "571382610"`). Such folders are now omitted; `ls proj:N` still
+  works, and `cache prefetch --folder-ids <id>` brings a folder back with its
+  real name.
+- **`cache prefetch`, root `ls` refresh and `ls proj:N` refresh no longer 403
+  with a Figma token created after 2026-08-03.** Figma renamed projects to
+  folders; new personal access tokens carry `folders:read` instead of
+  `projects:read`, and the deprecated `GET /v1/projects/{id}/files` rejects
+  them (`Invalid scope … requires the file_read or files:read or projects:read
+  scope`). Listings now use `GET /v2/folders/{id}/files`. Folder ids are the
+  old project ids, so `FIGMA_PROJECTS_IDS`, `proj:N` and existing cache metas
+  are unchanged; `--project-ids` gained a `--folder-ids` alias. A 403 from v2
+  falls back to v1 once (pre-rename tokens are documented to keep working
+  there) and prints a hint to regenerate the token. `figma-api` was
+  regenerated from the 2026-08-11 upstream spec, which adds `folders_api`;
+  `figma-get` gained `folder-files`, `folder-folders`, `folder-meta` and
+  `team-folders`, and marks `project-files` / `team-projects` deprecated.
+
+### Changed
+
+- **`node-info` output is ~4–5× smaller with nothing implementation-relevant
+  dropped.** Measured on a 475-node screen: 634 KB → 141 KB YAML. What changed
+  in the curated view (`--raw` is untouched):
+  - Hidden (`visible: false`) children are pruned and listed on the parent as
+    `hidden_children: [{id, name, type}]` — they were 65% of the output and,
+    worse, their descendants were indistinguishable from visible nodes.
+    `--include-hidden` restores them; a hidden target is always rendered, and
+    so is a hidden layer inside a COMPONENT definition whose visibility is
+    wired to a BOOLEAN property (its `property_refs` are the wiring an
+    implementer needs). A comment anchored to a pruned node is tagged
+    `anchor_rendered: false`.
+  - Defaults are elided: `constraints: LEFT/TOP`, `layout.wrap: NO_WRAP`,
+    axis `sizing: AUTO` / `align: MIN`, text alignment LEFT/TOP,
+    `line_height_unit: PIXELS`.
+  - `bounds` is parent-relative on descendants; flow children of an
+    auto-layout parent carry only `width`/`height`. A CANVAS has no box, so
+    a page's children are relative to the canvas origin (Figma's absolute
+    coordinates). `size` appears only when it differs from the bounding box
+    (rotation).
+  - Colors are `hex` only; the float channels are gone from fills, strokes,
+    gradient stops and effects.
+  - Text style drops `font_post_script_name`, `line_height_percent`,
+    `line_height_percent_font_size` (all restate other fields).
+  - `layout_child.sizing` is one `"H/V"` string; padding is one number when
+    uniform, else `[top, right, bottom, left]`.
+  - `component.component_properties` is split into `variants` and
+    `properties` with plain scalar values and Figma's `#n:m` name suffixes
+    stripped (kept when stripping would collide). An INSTANCE_SWAP prop keeps
+    its allowed swap targets as `preferred`. `property_refs` is emitted on
+    the target and inside component definitions only.
+  - Geometry leaves below the target (VECTOR, BOOLEAN_OPERATION, STAR, LINE,
+    REGULAR_POLYGON) drop only the layout block that cannot apply to them —
+    `constraints` when they are flow children of an auto-layout parent,
+    `layout_child` when the parent has no auto-layout — so a FILL-width
+    divider LINE keeps its sizing; fills and strokes stay so icon color
+    tokens remain visible.
+  - Bound variables are referenced by short handles (`v1`, `v2`, … in
+    first-seen order). The top-level `variables` block is keyed by handle and
+    always carries the raw `id`, plus name/values when the Variables sidecar
+    is available. The 60-character `VariableID:` strings no longer repeat
+    per use.
+  - Node-level `bound_variables` no longer repeats `fills[i]`/`strokes[i]`
+    entries that the paint itself already carries as `bound_variable` (half
+    of the map on a real screen). Entries the paints don't mirror are kept.
+  - Floats are rounded to 3 decimals (`14.40007495880127` → `14.4`): Figma
+    stores f32 and the REST API prints it as f64. The top-level `variables`
+    block gets the same treatment.
+  - `--no-variables` once again omits the `variables` block entirely; when a
+    sidecar is present but some handles point at library-owned variables, a
+    `variables_note` says how many could not be resolved locally.
+- **YAML output uses flow style for leaf containers** (`bounds: {width: 24,
+  height: 24}`, `padding: [0, 12, 0, 12]`, one record per row in lists)
+  instead of `serde_yaml`'s all-block rendering, via the new `yaml_out`
+  printer. Still standard YAML; a `node-info` view goes from 4,564 to 2,464
+  lines and 31.3k to 27.8k tokens. Non-ASCII keys are no longer escaped
+  (`💠 Before Icon`, not `\u{1f4a0} Before Icon`) and integral floats print
+  as `12`, not `12.0`. Multi-line text renders as a `|-` literal block.
+  Quoting is conservative enough for YAML 1.1 parsers (PyYAML, Psych):
+  `687:45` and `10:5` are quoted (base 60 would read them as integers),
+  `1,000` and `2026-9-5` too, large floats print as `1.5e+20`, a leading
+  `:`/`?` is quoted inside `{}`/`[]`, and U+2028/U+2029, NEL, DEL and the C1
+  range are `\uXXXX`-escaped rather than written raw (libyaml refuses the
+  whole document otherwise — Shift+Enter in a Figma text layer produces
+  U+2028). Applies to every command's YAML output.
+- **`--json` is compact**, not pretty-printed. Pretty JSON was the most
+  token-expensive rendering of all (37% more than the YAML default on the
+  same view); `jq` does not care.
+- `scripts/node_info_lossless.py` — checks a curated view against `--raw` for
+  the same target (node set, hidden listing, bounds reconstruction, paints,
+  layout, text, component props, variable handles).
+
 ## [0.2.2] - 2026-08-22
 
 ### Fixed

package/README.md

@@ -5,7 +5,7 @@ A command-line tool for navigating, inspecting, and exporting from Figma files v
 ## What it does
 
 - **`ls`** / **`find`** — navigate projects, files, and node trees by name or visible text without copy-pasting node ids. `find` speaks web-search syntax: `"exact phrases"`, uppercase `OR`, `-exclusion`.
-- **`node-info`** — single-target view with layout, fills, strokes, effects, text, bound variables, comments, and a ready-made figma.com `url:`. Designed to be pasted into an agent prompt.
+- **`node-info`** — single-target view with layout, fills, strokes, effects, text, bound variables, comments, and a ready-made figma.com `url:`. Hidden subtrees are pruned (listed as `hidden_children`), defaults elided, and variables referenced by short handles, so a full screen is a few dozen KB rather than hundreds. Designed to be pasted into an agent prompt.
 - **`comments`** — list a file's comment threads (replies inline, newest first), threads under a node, or a single thread; filter with `--unresolved` / `--since` / `--grep`.
 - **`mark`** — curated keyword→node bookmarks (`mark add key file:N:x:y --alias …`); `find` and `library search` surface matching marks ahead of their own hits, and `mark:key` resolves anywhere an id is accepted.
 - **`library search`** — fuzzy search across a team's published component library (components, component sets, styles).
@@ -59,7 +59,7 @@ export FIGMA_TOKEN=figd_...
 
 Optional environment variables:
 
-- `FIGMA_PROJECTS_IDS` — comma-separated project ids; needed by `cache prefetch`.
+- `FIGMA_PROJECTS_IDS` — comma-separated Figma folder ids (Figma renamed "projects" to "folders" in August 2026; the numeric ids are unchanged, so existing values keep working); needed by `cache prefetch`.
 - `FIGMA_TEAM_ID` — needed by `library search` and for the catalog warm in `cache prefetch`.
 - `FIGMA_EXPLORER_CACHE_DIR` — override the cache location (default: OS cache dir).
 
@@ -99,7 +99,7 @@ figma-explorer cache prefetch
 
 ## Output
 
-YAML by default (terse, agent-friendly). Pass `--json` for full pretty JSON suitable for `jq` pipelines.
+YAML by default (terse, agent-friendly: block style for the tree, flow style `{k: v}` for leaf maps and short lists). Pass `--json` for compact JSON suitable for `jq` pipelines.
 
 ## Cache
 

package/npm-shrinkwrap.json

@@ -19,7 +19,7 @@
       "hasInstallScript": true,
       "license": "MIT",
       "name": "@akesson/figma-explorer",
-      "version": "0.2.2"
+      "version": "0.2.3"
     },
     "node_modules/detect-libc": {
       "engines": {
@@ -48,5 +48,5 @@
     }
   },
   "requires": true,
-  "version": "0.2.2"
+  "version": "0.2.3"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/akesson/figma-explorer/releases/download/v0.2.2"
+    "https://github.com/akesson/figma-explorer/releases/download/v0.2.3"
   ],
   "bin": {
     "figma-explorer": "run-figma-explorer.js"
@@ -95,7 +95,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.2.2",
+  "version": "0.2.3",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"