internationalcolorconsortium/iccdev/ios-clut-editor

iOS CLUT Editor Workflow

Use this skill when changing examples/ios-clut-editor/**, its documentation, or its local build helper.

Start Gate

1. Confirm the branch is intended for branch-local grooming, not PR publication.
2. Read AGENTS.md, .github/copilot-instructions.md,

.github/instructions/build-system.instructions.md, and docs/governance/UPSTREAM_PR_READINESS.md.

1. Review prior iOS examples before editing:

examples/ios-apply-preview, examples/ios-benchapply, Build/AppleMobile, and .github/scripts/iccdev-apple-simulator-smoke.sh.

1. Inventory active and suppressed review findings if this branch already has a

PR. Do not repair comment-by-comment.

Required Invariants

• IccClutEditorPOC, ICCDEV_CLUTEDITOR_BUNDLE_IDENTIFIER, README commands,

and build-ios.sh must refer to the same app and bundle ID.

• The app consumes matching iOS or Mac Catalyst static core builds; it must not

depend on desktop tools, CTest executables, libtiff, wxWidgets, signing files, or generated Xcode output.

• Keep CMAKE_OSX_DEPLOYMENT_TARGET, CMake Xcode attributes, helper defaults,

and README examples aligned.

• Keep CMM and CLUT application on a background queue and update UIKit only on

the main queue.

• Remove stale Documents/clut-editor-report.json before writing the latest

accepted render's report; stale background renders must not overwrite it.

• Keep simulator launch repeatable with

simctl launch --console-pty --terminate-running-process.

• Keep device launch repeatable with

devicectl device process launch --console --terminate-existing --timeout.

• Keep Mac Catalyst runnable on Apple Silicon Macs through

build-ios.sh maccatalyst using a matching Mac Catalyst core archive, not an iOS device or simulator archive.

• Fail before building device targets when physical-device signing inputs still

contain placeholder team or bundle values; unsigned simulator and Mac Catalyst runs must not be blocked by a device-only signing placeholder and should ignore a globally exported placeholder bundle ID.

• Keep edited-image export available through the native share sheet.
• Disable report and edited-image sharing while a render is pending so exports

cannot use stale controls.

• Keep the profile-chain CMM interpolation fixed and make the UI selector apply

only to the editable CLUT unless the report and docs explicitly say otherwise.

• Keep the light/dark/system appearance toggle available as an educational

visual comparison tool.

• Keep the compact iPhone layout tuned for visible controls: half-height

logo/banner, short action labels, and two-column preview rows; do not regress the current iPad/Mac wide dashboard layout when adjusting phone density.

• Reused assets must not carry stale sibling-app text such as BENCH or

APPLY into CLUT editor source art or generated icons.

• Doxygen should include the README, .h, and .mm files through INPUT and

*.mm in FILE_PATTERNS; do not add EXTENSION_MAPPING = mm=C++.

Validation

Use the smallest complete validation for the changed surface:

git diff --check
cmake --preset apple-ios-simulator-core -S Build/Cmake \
  -DCMAKE_OSX_DEPLOYMENT_TARGET=17.0
cmake --build out/apple-ios-simulator-core --config Release --parallel
examples/ios-clut-editor/build-ios.sh simulator --run-tests
examples/ios-clut-editor/build-ios.sh maccatalyst --run-tests
doxygen .github/ci/doxygen/Doxyfile
test ! -s docs/generated/doxygen-warnings.log

For documentation-only edits, keep the Doxygen and diff checks. For code or helper edits, run the simulator smoke unless unavailable and record the exact skip reason.

Stop Rules

• Do not push until the local gate covering the current diff passes.
• Do not request repeated automated reviews for convergence. If a second review

cycle finds a new blocker, report review-stop: FAIL - maintainer direction required and stop.

• Do not add workflow or CTest registration unless a maintainer explicitly

requests it.