TopCutout is a small iOS Swift package that exposes top cutout geometry for iPhone screens, including classic notches and Dynamic Island devices.

It is useful when you need more than safe-area insets alone. Instead of only knowing how far content should stay away from the top edge, you can retrieve the cutout kind, exact cutout size, top padding, and helper geometry for the free space on each side.

NO Private API.

• Runtime lookup for the current device using the model identifier
• Nearest-size fallback for unknown iPhone model identifiers
• Generated catalog of iPhone screen metadata and top cutout geometry
• Distinguishes between .none, .notch, and .dynamicIsland
• Helper APIs for the cutout rect, occupied top band, and left/right "ear" regions
• Optional SwiftUI Path data for supported sensor housing outlines
• Included demo app and catalog-generation scripts

• iOS 13+

Add the package in Xcode with File > Add Package Dependencies... and use:

https://github.com/rijieli/TopCutout.git

Then add the TopCutout product to your target:

.target(
    name: "YourApp",
    dependencies: [
        .product(name: "TopCutout", package: "TopCutout")
    ]
)

TopCutoutCatalog is the main runtime entry point.

• TopCutoutCatalog.current -> TopCutoutInfo?
• TopCutoutCatalog.screen -> ScreenInfo?

When the current iPhone model identifier is not present in the generated catalog, TopCutoutCatalog falls back to the nearest generated iPhone screen size. Values are still nil when no safe match can be resolved, such as on non-phone devices.

Represents the resolved top cutout for the current screen.

• kind
• geometryAvailable
• curveAvailable
• size
• paddingTop
• rect(in:)
• occupiedTopBand(in:)
• leadingEarRect(in:)
• trailingEarRect(in:)
• recommendedButtonCenters(in:buttonSize:sidePadding:)

Represents screen metadata plus top cutout data.

• points
• pixels
• scale
• dpi
• cornerRadiusPoints
• isResolvedByScreenSize
• topCutout

Generated device catalog with:

• displayName
• screen
• sensorHousingPath

The current generated catalog includes 42 iPhone identifiers.

Build the package for iOS Simulator:

xcodebuild -scheme TopCutout -destination 'generic/platform=iOS Simulator' build

Refresh the generated catalog from installed Simulator assets:

python3 inspect_simulator_topcutouts.py

Refresh Dynamic Island probe results with the demo app workflow:

python3 collect_dynamic_island_simulator_info.py

TopCutoutDemo is a lightweight SwiftUI app used both as a visual demo and as part of the probing workflow for Dynamic Island geometry.

Use it to:

• Visualize the resolved cutout region
• Inspect debug output for the current simulator
• Validate spacing assumptions when updating generated data

Contributions are most useful when they improve one of these areas:

• Newly released device support
• Corrections to generated geometry
• Better demo coverage
• Tests and validation tooling
• Documentation and examples

When changing generated data, keep the generated Swift files and the source data in sync.