Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .claude/skills/verify-brushkit/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: verify-brushkit
description: Drive the brushkit library the way a downstream Rust consumer does and capture proof. Builds a probe crate that calls the public `brushkit` facade (parse_abr*, preview_abr/brush/brushset, *_first_available, preview with keep_going, contact sheets, procreate::Zip, descriptor dump) on real or synthetic brush files and writes JSON summaries and PNGs. Use to prove a reader or renderer change works on real files, beyond `cargo test`.
description: Drive the brushkit library the way a downstream Rust consumer does and capture proof. Builds a probe crate that calls the public `brushkit` facade (parse_abr*, preview_abr/brush/brushset, *_first_available, preview with keep_going, contact sheets, procreate::Zip, typed brush descriptors, descriptor dump) on real or synthetic brush files and writes JSON summaries and PNGs. Use to prove a reader or renderer change works on real files, beyond `cargo test`.
---

# verify-brushkit
Expand Down Expand Up @@ -60,7 +60,7 @@ The helper appends `--out <evidence dir>` itself. Commands:

| Command | Public API called | Flags |
|---|---|---|
| `parse` | `abr::parse_abr` or a deferred variant, then `DeferredPack::decode_tip` per brush and `up_front_decoded_len`, and `preview::synthesized_tip_side` per computed preset | `--mode eager\|deferred\|deferred-no-patterns\|all-deferred` (default `eager`) |
| `parse` | `abr::parse_abr` or a deferred variant, then `DeferredPack::decode_tip` per brush and `up_front_decoded_len`, and `preview::synthesized_tip_side` per computed preset. Each brush and computed preset carries its `BrushDescriptor` as `Debug` text | `--mode eager\|deferred\|deferred-no-patterns\|all-deferred` (default `eager`) |
| `preview` | `preview::preview_abr`, `preview_brush` or `preview_brushset`, or the `_first_available` twin with `--first`, or `preview::preview` with a counting `keep_going` with `--stop-after`, then `generate_preview_png` per tip and `generate_contact_sheet_png` | `--kind abr\|brush\|brushset` (default from the file extension, required for extensionless fuzz seeds), `--max-cell N` (default 128), `--first N`, `--stop-after N` |
| `zip` | `preview::procreate::Zip::open`, `names`, `members_in_zip_order`, `conflicting_names`, and with `--read` `read_entry` or `read_entry_within` | `--read NAME`, `--limit N` |
| `dump` | `abr::parse_abr`, then `abr::dump::dump_descriptors` on `raw_desc_block`, serialized by serde | none |
Expand Down
2 changes: 2 additions & 0 deletions .claude/skills/verify-brushkit/features/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,5 +62,7 @@ consumer-visible behavior, then exactly four H2 sections in this order:
- [Parse an .abr pack](./parse-abr.md) covers the four `parse_abr*` entry
points, unavailable brushes, uuids, up-front decoding, patterns,
diagnostics and malformed input.
- [Brush descriptor](./brush-descriptor.md) covers the typed
`BrushDescriptor` of each sampled brush and computed preset.
- [Descriptor dump](./descriptor-dump.md) covers `dump::dump_descriptors` with
the `serde` feature.
46 changes: 46 additions & 0 deletions .claude/skills/verify-brushkit/features/brush-descriptor.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Brush descriptor

A consumer reads the Photoshop settings of each `.abr` preset as a typed
`BrushDescriptor`: spacing, diameter, computed geometry, the Shape Dynamics,
Scatter, Texture, Dual Brush, Transfer and Color Dynamics panels, the tool
settings saved with the preset and the tip's Intr flag. A readable sampled
brush and a computed preset each carry one. A field is `None` when the file
carries no value for it.

## Sub-features

- `desc-sampled` gives each readable sampled brush the descriptor of its preset in `AbrBrush::descriptor`.
- `desc-computed` gives each computed preset its descriptor in `ComputedPreset::descriptor`, with `computed` always `Some`.
- `desc-default` gives `BrushDescriptor::default()` to a brush with no preset: a v1/v2 pack, a pack without a `desc` block, or an unpaired record on the fallback path.
- `desc-gating` leaves a panel's fields `None` when the panel's `use*` flag (`useTipDynamics`, `useScatter`, `usePaintDynamics`, `useTexture`, `useColorDynamics`, `useDualBrush`) is false.
- `desc-tool-options` reads `toolOptions` into `ToolOptions`, with opacity and blend mode from `MdSl` when the top level lacks them.
- `desc-modes` gives the same descriptors in all four parse modes.

## How to get to it (user POV)

- `brushkit::abr::parse_abr(&bytes)?.brushes[i].descriptor` and `.computed_presets[i].descriptor`, or the same fields of `DeferredPack::pack`.
- `brushkit::abr::BrushDescriptor`, `ToolOptions`, `DualBrush` and `ComputedGeometry`. They derive `Debug`, `Clone`, `Default` and `PartialEq`, not serde.
- An unavailable brush (`UnavailableBrush`) and an unsupported preset (`UnsupportedTipPresetDetail`) carry no descriptor.

## Driving it with verify-brushkit

Preconditions:

- Baseline preconditions from the index hold.
- The probe's `parse` command writes each descriptor as its `Debug` text in `.result.pack.brushes[].descriptor` and `.result.pack.computed_presets[].descriptor`. Assert on it with jq `test`, for example `test("tilt_scale_pct: Some")`.

- **Seed sampled brush.** Run `$H run seed-desc parse fuzz/corpus/preview_abr/unavailable_tips`. Brush `A` at `preset_index` `1` has the all-default descriptor, which starts `BrushDescriptor { spacing_pct: None, computed: None, diameter_px: None,` and ends `tool_options: None, interpolation: None }`, because its preset writes only `Nm ` and `sampledData`. `.result.pack.sampled_brushes[].unavailable` has no `descriptor` key.
- **Seed computed preset.** The same run's `computed_presets[0].descriptor` contains `computed: Some(ComputedGeometry { diameter_px: Some(30.0), hardness_pct: None, angle_deg: None, roundness_pct: None })` and `diameter_px: Some(30.0)`.
- **Default.** Run `$H run seed-v2 parse fuzz/corpus/preview_abr/zero_area_tip` and `$H run seed-nodesc parse fuzz/corpus/preview_abr/sampled_tip`. Every brush's `descriptor` equals brush `A`'s from `seed-desc`, and its `preset_index` is `null`.
- **Mode parity.** Run a real pack with `--mode eager`, `deferred`, `deferred-no-patterns` and `all-deferred`. `[.result.pack.brushes[].descriptor, .result.pack.computed_presets[].descriptor]` is identical across the four runs.
- **Real tool options.** On a v10 corpus pack, `.result.pack.brushes[].descriptor` contains `tool_options: Some(ToolOptions { tool: "<class>"` exactly where `dump` preset `preset_index` has a `toolOptions` item, and `<class>` is that item's `.value.objc.class_id`.
- **Real gating.** On the same pack, every preset whose `dump` item `useTipDynamics` is `{"bool":false}` has `size_jitter_pct: None`, `tilt_scale_pct: None` and `minimum_diameter_pct: None`.
- **Corpus-wide values.** Run `BRUSHKIT_CORPUS_DIR=... cargo test -p brushkit-abr --test corpus_smoke -- corpus_sets_a_nonzero_control_on_every_brvr_panel corpus_sets_a_non_default_value_for_every_tool_setting_and_intr corpus_sets_a_non_default_tilt_scale_on_size_on_pen_tilt every_corpus_mdsl_preset_reads_its_blend_mode_and_opacity`. Four tests pass. They prove the `bVTy` controls, the tool settings, Intr, Tilt Scale and the `MdSl` fallback on real files.

## Gotchas

- The `Debug` text is long. Query it with `test` or `capture` instead of reading it.
- With `BRUSHKIT_CORPUS_DIR` unset, the corpus tests print `skip:` and pass, which proves nothing.
- The seeds carry no panel, tool or Intr values. Dual brush, texture, color and the `MdSl` fallback order have only synthetic proof in the unit tests of `crates/abr/src/descriptor.rs`, beyond the corpus tests above.
- `interpolation` is the main tip's `Brsh/Intr`. The dual brush's own Intr is not read.
- `Opct` counts only as wire type `long`. A `doub` gives `opacity_pct: None`.
10 changes: 5 additions & 5 deletions .claude/skills/verify-brushkit/features/parse-abr.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,20 +32,20 @@ Preconditions:
- Baseline preconditions from the index hold.
- The probe prints `up_front_decoded_len` in `.result.pack` for the three deferred modes only.

- **Eager.** Run `$H run parse-eager parse "$BRUSHKIT_CORPUS_DIR/<pack>.abr"`. Exit `0`. `.result.pack.version` is `v6`, `v7` or `v10` for a corpus pack (the library also reads `v1`, `v2` and `v9`), every `.result.pack.brushes[].uuid` is a string, and every `.result.pack.brushes[].tip` has `width`, `height`, `depth` 8 or 16 and `data_len` equal to `width*height*depth/8`.
- **Eager.** Run `$H run parse-eager parse "$BRUSHKIT_CORPUS_DIR/<pack>.abr"`. Exit `0`. `.result.pack.version` is one of `v1`, `v2`, `v6`, `v7`, `v9` and `v10`, all present in the corpus. Every `.result.pack.brushes[].uuid` is a string on a v6 or later pack and `null` on v1/v2, and every `.result.pack.brushes[].tip` has `width`, `height`, `depth` 8 or 16 and `data_len` equal to `width*height*depth/8`.
- **Mode parity.** Run the same file with `--mode deferred`, `--mode deferred-no-patterns` and `--mode all-deferred` under three labels. `.result.pack.brushes` is identical across all four runs.
- **Unavailable brushes.** Run `$H run seed-unavail parse fuzz/corpus/preview_abr/unavailable_tips`. Exit `0`. `.result.pack.brushes` holds only `A` at `preset_index` `1` with `uuid` `a1b2c3d4-e5f6-7890-abcd-ef1234567890`, and `.result.pack.computed_presets` holds `Round` at `2` with `diameter_px` `30`. `.result.pack.sampled_brushes` is `B` at `preset_index` `0` with `.unavailable.cause` `{"unreadable":"no bitmap header found"}`, then `{"readable":0}`, then `C` at `preset_index` `3` with `.unavailable.cause` `{"missing":{"uuid":...}}` and the same uuid as its `id` and `uuid`. The other three modes give the same `sampled_brushes`, because `B` fails in its header.
- **Patterns.** Run `$H run seed-patt parse fuzz/corpus/preview_abr/wellformed_v6_patt`. `.result.pack.patterns` is one 2x2 pattern named `tex`, mode `2`. The same seed with `--mode deferred-no-patterns` returns an empty `patterns`.
- **Dropped pattern.** Run `$H run seed-dropped parse fuzz/corpus/preview_abr/patt_oversized_channel`. Exit `0` with `.result.pack.diagnostics.dropped_pattern_count` `1`.
- **Dual-brush drops.** Find a corpus pack with a nonzero `dropped_samp_count` by running `--mode all-deferred` over the corpus. At least one v7 pack has `5`. `.result.pack.brushes` still lists every user-facing brush. `.result.pack.diagnostics.dropped_tip_details` lists one entry per dropped tip with `uuid`, `width`, `height` and `owners`, the presets that use it as their dual brush, one entry per preset with `preset_index` and `name`. When records share a uuid, only the record the uuid resolves to lists owners. The details are identical in `eager` and `all-deferred`.
- **Up-front bytes.** On that v7 pack, `.result.pack.up_front_decoded_len` is the same in the three deferred modes and equals `[.result.pack.diagnostics.dropped_tip_details[] | .width*.height] | add` for 8-bit tips. A pack with no dropped tips has `0`. The v2 seed `zero_area_tip` with `--mode all-deferred` has `1`, because v1/v2 tips are always decoded up front.
- **Unreadable unused records.** `.result.pack.diagnostics.unreadable_tip_details` lists each samp record that no sampled brush uses and whose tip does not parse, with `uuid`, `message` and `owners`, each entry with `preset_index` and `name`. No corpus pack or fuzz seed has one, so it is `[]`. To get one, copy the v7 pack outside the repo and zero the bytes that follow the `$` and the uuid in one dropped tip's samp entry, keeping the entry length. The copy lists that uuid with `message` `"no bitmap header found"` and the same `owners` as its dropped tip detail, and `dropped_samp_count` is one lower. Zeroing the uuid too removes the record instead.
- **Dual-brush drops.** Find a corpus pack with a nonzero `dropped_samp_count` by running `--mode all-deferred` over the corpus. Many v6, v9 and v10 packs have one, up to `34`. `.result.pack.brushes` still lists every user-facing brush. `.result.pack.diagnostics.dropped_tip_details` lists one entry per dropped tip with `uuid`, `width`, `height` and `owners`, the presets that use it as their dual brush, one entry per preset with `preset_index` and `name`. When records share a uuid, only the record the uuid resolves to lists owners. The details are identical in `eager` and `all-deferred`.
- **Up-front bytes.** On that pack, `.result.pack.up_front_decoded_len` is the same in the three deferred modes and at least `[.result.pack.diagnostics.dropped_tip_details[] | .width*.height] | add`. It is more when a dropped tip is 16-bit or when several samp records share a uuid, because those records are decoded up front too, so a pack with no dropped tips can still report more than `0`. A v1/v2 pack always does. The v2 seed `zero_area_tip` with `--mode all-deferred` has `1`. `all-deferred` decodes nothing, but the value is the same in every deferred mode, and the other two decode v1/v2 tips up front.
- **Unreadable unused records.** `.result.pack.diagnostics.unreadable_tip_details` lists each samp record that no sampled brush uses and whose tip does not parse, with `uuid`, `message` and `owners`, each entry with `preset_index` and `name`. No corpus pack or fuzz seed has one, so it is `[]`. To get one, copy a pack with dropped tips outside the repo and zero the bytes that follow the `$` and the uuid in one dropped tip's samp entry, keeping the entry length. The copy lists that uuid with `message` `"no bitmap header found"` and the same `owners` as its dropped tip detail, and `dropped_samp_count` is one lower. Zeroing the uuid too removes the record instead.
- **Malformed.** Run `$H run seed-bad parse fuzz/corpus/preview_abr/tip_bitmap_dim_overflow`. Exit `1` with `.result.error` `"malformed block at offset 125: bitmap dimensions out of range"`. `v2_rle_overflow` gives `"malformed block at offset 48: samp entry length exceeds buffer"` and `v2_rle_underflow` gives `"malformed block at offset 48: samp entry length shorter than header"`, both exit `1`.

## Gotchas

- `eager` and `deferred` read patterns, the other two modes skip them, so `patterns` is empty there by design.
- The corpus and the fuzz seeds other than `unavailable_tips` have no computed presets. `computed_presets` stays empty unless the user supplies a pack with computed tips.
- Of the fuzz seeds, only `unavailable_tips` has a computed preset. Many v6 and v10 corpus packs have them.
- A tip whose header parses but whose pixels do not decode is `unreadable` in `sampled_brushes` only where it is decoded up front. A v6/v7/v9/v10 tip is decoded up front in `eager`, and in `deferred` and `deferred-no-patterns` only when it is a dual-brush tip or shares its uuid with another record. A v1/v2 RLE entry is `unreadable` in every mode but `all-deferred`. Where it is not `unreadable`, it is `readable` with the error in its `brushes[i].tip.error`. On such a pack `sampled_brushes` and `brushes` differ across modes by design. An unused v6/v7/v9/v10 record is in `unreadable_tip_details` in `eager`, `deferred` and `deferred-no-patterns`, and in `dropped_tip_details` in `all-deferred`.
- Exit `101` means a panic inside the library, which is a bug on any input.
- Eager parsing of a 30 MB pack holds every decoded tip in memory. Prefer `all-deferred` for corpus sweeps.
Loading
Loading