feat(native): image positioning and explicit scale-down contract for shared STX Image

STX integration blocker

Follow-up to https://github.com/stacksjs/stx/issues/2091. Shared Image is covered through explicit imports on web/native, but its default-resolution migration remains gated on a faithful native contract for CSS object-position and object-fit: scale-down. STX currently diagnoses these rather than silently approximating them. Legacy native source callers and the web Image builtin must stay compatible.

Read-only audit of clean Craft b49aa1e894198d1b8b5fe7b07a6fa43d2d6d34f6:

• packages/ios/templates/CraftNativeScreen.swift: imageContentMode supports cover/stretch/center and defaults to aspect-fit; Image/ImageBackground read resizeMode. There is no object-position or explicit scale-down input.
• packages/android/templates/MainActivityNative.kt.template: the image branches support cover/stretch/center and otherwise use CENTER_INSIDE. That default does not have the same upscaling behavior as iOS aspect-fit, so please define the new CSS-facing contract explicitly while preserving existing callers.
• STX's native/image-fit.test.ts and native/shared-image-fit.test.ts deliberately report unsupported scale-down/object-position. Replacing those diagnostics with contain or center would change the requested rendering.

Requested host contract

Provide host-owned image positioning and an explicit scale-down mode usable by STX on iOS/Android. The exact protocol spelling can be coordinated, but the behavior should be:

• Position the image within its box, including percentage/keyword alignment and crop alignment for cover.
• Scale-down uses intrinsic size when it fits, otherwise contain; it never upscales a smaller image.
• Recompute after image load, source replacement, frame changes and live prop updates without replacing the image/player view or restarting an unchanged request.
• Preserve legacy source/resizeMode behavior and define clear/reset defaults.
• Cover small/large intrinsic images, cover crops, live updates, clear/default restoration and remounts with maintained host tests.

This issue records the host prerequisite for the assigned Craft agent. No Craft code was edited by the STX session. STX implementation/version status: current published baseline 0.2.745; shared Image migration remains open in #2091 until the capability is available and integrated.

Implemented on main in cb95ae0, b5c1438, and 4202419.

Both maintained hosts now accept objectFit (fill, contain, cover, none, scale-down) and objectPosition on Image/ImageBackground. Position supports one/two alignment keywords or percentages, including cover crop alignment. Non-null props override style; clearing both restores legacy resizeMode behavior. The iOS loader preserves intrinsic dimensions through downsampling. Geometry updates retain views and do not reload an unchanged source.

Validation: 352 iOS native unit tests passed, followed by all five focused image tests including targeted mutation/load-event assertions; 53 Android native tests passed, followed by all three strengthened image tests including remount and decoded-image retention. SDK: 820 passed, 10 existing skips; release/workflow: 413 passed. Typechecks, package builds/verification, pinned formatting, and lint passed (26 existing warnings, zero errors).

Closing the Craft host prerequisite as implemented. The protocol is documented in docs/guides/native-stx.md; pixel offsets and three/four-token position syntax are explicitly unsupported. STX compiler integration/default-resolution migration in stacksjs/stx#2091 remains separate.

Not yet released: these commits are on main, not in v0.0.395. Full GitHub CI and Mobile E2E are still pending; this closure does not claim green hosted validation or publication.

Shipped the Craft host support in v0.0.396, including iOS/Android Image and ImageBackground fit/position behavior and SDK types. Full CI and Mobile E2E passed on the exact release commit; GitHub assets, Pantry publication, and all eight npm packages are verified.

Upgrade the Craft packages to 0.0.396 and regenerate the native shell. STX compiler integration is the separate downstream prerequisite described above.