feat: declare preview shape on SocialPlatformConfig (#140)

[chubes4]

Summary

Implements #140 — declares a preview shape on each handler's SocialPlatformConfig so downstream clients (Studio publish-pane preview, mobile app, etc.) can render platform-canonical post previews without any per-platform branching. The client renders whatever shape the server declares.

Changes

• 8 handlers under inc/Handlers/{Twitter,Bluesky,Instagram,Threads,Facebook,LinkedIn,Pinterest,Reddit}/*.php declare a preview array in their meta config, following the per-platform mapping in SocialPlatformConfig: declare preview shape (aspectRatio, captionPosition, previewSurface) #140.

• REST assembly (RestApi::get_platforms()) gains a normalize_preview() step applied to every entry. Handlers that don't declare it (or declare an incomplete shape) get a generic feed-shaped default:

  array(
      'aspectRatio'     => 'native',
      'captionPosition' => 'above',
      'previewSurface'  => 'feed',
  )

  The field is always present on the response — clients never default it.

• README gets a new "Handler API" section documenting the meta config shape with the per-platform preview mapping.

Per-platform mapping

Platform	aspectRatio	captionPosition	previewSurface
Twitter	16:9	above	feed
Bluesky	16:9	above	feed
Threads	native	below	feed
Instagram	1:1	below	square
Facebook	native	above	card
LinkedIn	native	above	card
Pinterest	4:5	below	square
Reddit	native	above	card

Companion PR — must merge together

This is the data-contract foundation for the Studio publish-pane preview architecture. The TypeScript types in @extrachill/api-client are updated in a companion PR — both should land together so consumers see a consistent surface:

• api-client companion: feat: add SocialPlatformConfig.preview type for #140 extrachill-api-client#13

Downstream consumers (extrachill-studio#43, #44) are unblocked once both merge.

Backwards compat

• preview is purely additive on the response. Existing publish-pane behavior is unchanged.
• Older clients that don't know about preview ignore it (extra JSON fields are tolerated).
• Newer clients running against an older DM-Socials install that pre-dates this would see preview missing — but this PR ships alongside the api-client companion; once both land, the server always emits the field.

Verification

• php -l clean on all 9 modified files
• Handler entries inspected — preview keys placed inside the meta array passed to registerHandler() so they flow through to the REST response naturally
• RestApi::get_platforms() docblock updated to document the new field

Constraints

• No CHANGELOG.md edits — homeboy owns the changelog.
• No version bumps — homeboy owns version targets.
• Conventional commits used throughout (3 commits: 2 feat:, 1 docs:).

Refs: #140

[homeboy-ci]

Homeboy Results — data-machine-socials

Audit

✅ audit — passed

• test_coverage — 20 finding(s)
• intra-method-duplication — 4 finding(s)
• dead_code — 3 finding(s)
• repeated_literal_shape — 2 finding(s)
• Total: 29 finding(s)

Deep dive: homeboy audit data-machine-socials --changed-since 70b8a54

Tooling versions

• Homeboy CLI: homeboy 0.163.1+be64fd263
• Extension: wordpress from https://github.com/Extra-Chill/homeboy-extensions
• Extension revision: 7e6a4a3
• Action: Extra-Chill/homeboy-action@v2