Media constraints: correct the platform limits, then measure video server-side

[paulocastellano]

Design and implementation plan for the media-constraint work, ready to execute. Supersedes the approach in #287 and covers all three goals of #200.

Full design doc and the Phase 1 task-by-task plan are attached as comments below, so this issue is self-contained.

Why #287 can't be merged as-is

PR #287 extended ContentTypeCompatibleWithMedia from type-only checks to the full numeric rule set and widened YouTube Shorts to accept square video. Reviewing it turned up three problems.

1. Half the new checks can never fire. Nothing measures video metadata. HasMedia::getMediaMetaFromBytes() handles type === 'image' only, and the video path (streamFileToStorage) stores 'meta' => $meta untouched. No frontend code reads videoWidth or listens for loadedmetadata. So meta.duration and video meta.width/height are never populated — the duration and video aspect checks are dead code, live only for an API client that volunteers the values. That's both forgeable and a perverse incentive: the honest client gets rejected, the lazy one doesn't.

2. Three of the six aspect-ratio windows are wrong. They were written as a soft cropper hint — the docblock says so verbatim: "Soft aspect-ratio window used by the Vue cropper / media picker." They're harmless today precisely because video meta never exists. Measuring video for real arms them.

Content type	Current	Official wording	Verdict
instagram_feed (image)	0.8–1.91	"Must be within a 4:5 to 1.91:1 range"	correct
instagram_reel	0.5–0.6	"Required aspect ratio is between 0.01:1 and 10:1 but we recommend 9:16"	far too strict
instagram_story (video)	0.5–0.6	"between 0.1:1 and 10:1 but we recommend 9:16"	too strict
facebook_reel	0.5–0.6	"Aspect Ratio | 9 x 16"	keep — declared spec
facebook_story	0.5–0.6	"Aspect Ratio | 9 x 16"	keep
youtube_short	0.5–0.6	"square or vertical … up to three minutes"	max should be 1.0; the minimum has no basis

Sources: IG User Media reference, FB Reels publishing, FB Page Stories, YouTube Shorts.

Note the asymmetry: "it's only a recommendation" holds for Instagram and not for Facebook, whose spec tables state 9:16 flatly. The fix is per-content-type numbers, not a new hard-limit/recommendation abstraction.

3. Validation reads client-supplied data, so measuring on the server doesn't help by itself. UpdatePost::execute() stores 'media' => data_get($data, 'media', $post->media) — posts.media is a verbatim copy of the request payload, never re-hydrated from the medias table. The rule reads that copy.

Other findings

• instagram_feed video is published as a Reel. InstagramPublisher::publishFeed() routes a single video to publishReel(). Its rules describe a feed image — 60s and 0.8–1.91 — so once video is measured, a valid 90s 9:16 video on Instagram Feed gets rejected twice over, for two reasons that don't apply to it.
• In production, video never has a local file. ChunkedCloudUploader::shouldUseMultipart() returns true for Video and Document whenever the disk is s3, so the chunked receiver goes straight to object storage. Any probe that assumes a local temp only works on a dev machine. Media::temporaryUrl() already exists and ffprobe reads HTTP directly without downloading the whole file.
• A live forgery vector. AssetController::store is the only call site forwarding client meta into addMedia; StoreAssetRequest accepts meta.width/height/duration and HasMedia merges client over server. Nothing in the frontend sends those keys — it's dead code whose only present function is letting a client override a server measurement.
• The API reports the wrong message. errorsFor() overwrites, so with several $fail() calls the caller gets the last while the editor shows the first. Confirmed by running it: a LinkedIn post with a 6MB GIF says "images must be under 5.0 MB" over the API and "does not support animated GIFs" in the editor.
• We enforce what we don't advertise. toListingArray() — used by ListContentTypesTool and PlatformContentTypesResource — omits the aspect bounds, so API and MCP clients get a 422 for a constraint they have no way to discover.
• i18n. fix: harden backend media constraints and allow square YouTube Shorts #287 changed the Shorts description in lang/en only; the other 15 locales still read "Vertical video up to 3 minutes". LocalizationParityTest compares keys, never values. Since the aspect change is dormant until video is measured, this copy is the only user-visible part of the Shorts fix.
• The editor blocks images the publisher would fix. With meta.aspect_ratio set, InstagramPublisher::cropImageForAspectRatio() centre-crops before upload. StreamPostCreation writes that meta on every AI-generated post. So a 3:4 photo with aspect_ratio: '4:5' publishes fine today, yet the editor blocks scheduling and — after fix: harden backend media constraints and allow square YouTube Shorts #287 — the API would 422 it.

Plan: three phases, and the order is load-bearing

Doing Phase 2 before Phase 1 is a guaranteed production regression: arming video measurement against the current 0.5–0.6 bounds rejects most Reels.

Phase 1 — correct the numbers before arming them (~12 files + 16 lang)

Full task-by-task plan in the comments. Nothing changes at runtime today — video still has no metadata — so this is pure "make it correct before it matters". This is also the scope #287 was aiming at, corrected.

• Split aspectRatioBounds() into imageAspectRatioBounds() / videoAspectRatioBounds(), add minVideoDurationSec(), correct every number, delete the now-redundant autoFitsImage()
• Expose aspect bounds + min duration in toListingArray() and the MCP tool description
• Rule: split bounds, minimum duration, Number::fileSize(), ??= so the first violation wins
• Rule: validate the cropped ratio when a platform crop is set (images only)
• Frontend: reshape contentTypeMediaRules.ts, apply the split and the crop in useMedia.ts
• Wire the selected crop ratio through usePostCompliance and the Instagram/Facebook settings panels
• Translate the Shorts copy and the new video_too_short keys across all 16 locales
• Full verification — pint, npm run lint, php artisan test --compact --parallel (baseline: 3951 passed, 1 skipped)

Phase 2 — VideoProbe + infra (~10 files)

Blocked on Phase 1.

• App\Services\Media\VideoProbe — Process facade in array form, ffprobe -v error -print_format json -show_format -show_streams, binary from FFPROBE_PATH
• Handle rotation: stream.width/height are pre-rotation, so swap when side_data_list[].rotation is ±90/270. Needs a genuinely rotated fixture — ffmpeg 8.1.2 transposes rather than writing a display matrix, so one could not be synthesised during design. Do not assume this is handled because the code contains a swap.
• Wire into HasMedia::streamFileToStorage() (local temp) and addMediaFromStoredPath() (S3, via temporaryUrl)
• Fail open on every error — missing binary, timeout, bad JSON. ffprobe is never on the critical path of an upload succeeding
• ffmpeg in the Dockerfile's system-base stage (covers dev and production); apt-get install -y ffmpeg on the Forge VPS; FFPROBE_PATH in .env.example
• Delete meta.width/height/duration from StoreAssetRequest and $clientMeta from AssetController::store
• php artisan media:backfill-video-meta with --dry-run, so old and new videos aren't under two different regimes

Phase 3 — validation reads the database (~6 files)

• Resolve size / mime_type / meta from medias by media.*.id, scoped to the post's workspace, memoised per validation
• Items with no id (the API's bare external URL) keep today's fail-open behaviour
• An id that doesn't resolve is treated as unknown metadata, not an error — today an unresolvable id just means the payload's url is what gets published, and hardening that would break callers over a field that's currently decorative

To be precise about what Phase 3 buys: it's a consistency goal, not a security boundary. A client sending no id still lands in fail-open, and that's fine — the only person harmed by dodging validation is the post's author, whose publish then fails at the platform instead. What's worth having is that the editor and an honest API client reach the same verdict, and that declaring your metadata truthfully is never punished while omitting it is rewarded.

Explicitly out of scope

• TikTok's account-dynamic creator_info.max_video_post_duration_sec — needs a fetch-at-validate-time design of its own
• Minimum video resolution (FB Reel/Story 540×960) — documented, but one more field across enum, Inertia payload, useMedia.ts and toListingArray() for a rarely-hit case
• A "recommended framing" warning. Widening Instagram Reel to 0.01–10 means the editor no longer warns that a 16:9 video will letterbox. ContentType::aspectRatio() already holds the 9:16 guidance; it just has no warning surface. The product loss is mild and deliberate — a warning must never block scheduling, which is exactly what the old numbers did.

Refs: #200, #287

[paulocastellano]

Full design doc — the why, with every finding verified against the code or an official doc. Would live at docs/superpowers/specs/2026-08-27-media-constraints-design.md if committed.

---

Media constraints: server-measured video meta, correct per-platform limits, backend enforcement

Status: Approved design, ready for implementation plan
Branch: feat/issue-200-media-constraints (revises PR #287 in place)
Issue: #200 — all three goals
Date: 2026-08-27

Motivation

PR #287 extended ContentTypeCompatibleWithMedia from type-only checks to the full numeric
rule set (counts, GIF, byte caps, video duration, aspect ratio) and widened YouTube Shorts to
accept square video. Reviewing it turned up three problems that make the change, as written,
either inert or actively harmful.

1. Half the new checks can never fire. Nothing in the codebase measures video metadata.
HasMedia::getMediaMetaFromBytes() only handles type === 'image'
(app/Models/Traits/HasMedia.php:283), and the video path
(HasMedia::streamFileToStorage()) stores 'meta' => $meta untouched. No frontend code
reads videoWidth or listens for loadedmetadata. So meta.duration and video
meta.width/height are never populated, and the duration and video aspect checks are dead
code — live only for an API client that volunteers the values, which is both forgeable and a
perverse incentive (the honest client gets rejected, the lazy one does not).

2. The aspect-ratio numbers are wrong for three of the six content types that have them.
They were written as a soft cropper hint — the docblock says so verbatim: "Soft aspect-ratio
window used by the Vue cropper / media picker." They are harmless today precisely because
video meta never exists. Measuring video for real arms them, and a 0.5–0.6 window rejects
most video that Instagram publishes without complaint.

3. Validation reads client-supplied data, so measuring on the server does not help by
itself. UpdatePost::execute() stores 'media' => data_get($data, 'media', $post->media)
(app/Actions/Post/UpdatePost.php:36) — posts.media is a verbatim copy of the request
payload, never re-hydrated from the medias table. The rule reads that copy.

Verified facts

Everything below was confirmed against the code or an official doc, not assumed.

Where media metadata comes from today

Path	Entry point	Video meta
Web chunked upload, S3 disk (production)	ChunkedAssetReceiver::receiveViaMultipart → HasMedia::addMediaFromStoredPath	none — file goes straight to object storage, no local temp ever exists
Web chunked upload, local disk (Herd, tests)	ChunkedAssetReceiver::receiveViaLocalAssemble → addMediaFromPath → streamFileToStorage	none
Web single upload	AssetController::store → addMedia	none for video; images get getimagesizefromstring
API upload	Api\UploadController → addMediaFromPath	none
API external URL	Services\Post\MediaAttacher → addMediaFromPath	none
Unsplash	AssetController::storeFromUrl	getimagesize, images only

ChunkedCloudUploader::shouldUseMultipart() returns true for Video and Document whenever
the disk driver is s3. In production every video takes the no-local-file path. Any probe
design that assumes a local temp file only works on a developer's machine.

The forgery vector

AssetController::store (app/Http/Controllers/App/AssetController.php:65-67) is the only
call site that forwards client meta into addMedia. StoreAssetRequest accepts
meta.width, meta.height, meta.duration, and HasMedia merges client over server:
array_merge($this->getMediaMetaFromBytes(...), $meta) (HasMedia.php:105). No frontend code
sends those keys. It is dead code whose only present function is to let a client override a
server measurement.

What the platform docs actually require

Content type	Current bounds	Official wording	Verdict
instagram_feed (image)	0.8–1.91	"Must be within a 4:5 to 1.91:1 range"	correct
instagram_reel	0.5–0.6	"Required aspect ratio is between 0.01:1 and 10:1 but we recommend 9:16"; duration "15 mins maximum, 3 seconds minimum"	far too strict
instagram_story (video)	0.5–0.6	"between 0.1:1 and 10:1 but we recommend 9:16"; "60 seconds maximum, 3 seconds minimum"	too strict
facebook_reel	0.5–0.6	"Aspect Ratio | 9 x 16"; "Duration | 3 to 90 seconds"	keep — declared spec, no tolerance range published
facebook_story	0.5–0.6	"Aspect Ratio | 9 x 16"; video story "can not exceed 60 seconds"	keep
youtube_short	0.5–0.6	"square or vertical aspect ratio up to three minutes"	max should be 1.0; the minimum has no basis

Sources: IG User Media reference,
FB Reels publishing,
FB Page Stories,
YouTube Shorts.

The generalisation "the window is only a recommendation" holds for Instagram and not for
Facebook, whose spec tables state 9:16 flatly. The fix is per-content-type numbers, not a new
hard-limit/recommendation abstraction.

instagram_feed video is published as a Reel

InstagramPublisher::publishFeed() routes a single video to publishReel()
(app/Services/Social/InstagramPublisher.php:96-101). The content type's rules describe a
feed image — 60s and 0.8–1.91 — so once video is measured, a perfectly valid 90s 9:16 video
on Instagram Feed would be rejected twice over, for two reasons that do not apply to it.

ffprobe against object storage works

Media::temporaryUrl() already exists (app/Models/Media.php:79). ffprobe reads HTTP(S)
directly and only pulls what it needs:

ffprobe -v error -print_format json -show_format -show_streams http://…/probe_test.mp4
→ duration 4.000000, 1080x1920   (0.04s CPU)

Environment

• Production is a VPS provisioned by Laravel Forge — root available, apt-get install ffmpeg.
• Self-hosted ships docker/Dockerfile, Alpine-based, stage system-base at line 18; both
  the dev and production targets derive from it, so one apk add ffmpeg covers both.
• Laravel 13.24. Illuminate\Support\Facades\Process with Process::fake() is available, so
  the test suite never needs the binary.
• app/ currently contains no shell-out of any kind. ffprobe is the first.

Goals

1. Video assets carry server-measured duration, width, height after upload, on every
   storage path including S3.

2. Media constraints are enforced on the web, public API and MCP schedule/publish paths,
   against server-measured data rather than whatever the client echoes back.

   To be precise about what this does and does not buy: it is a consistency goal, not a
   security boundary. A client that sends an unknown id, or no id, still lands in the
   fail-open path — and that is acceptable, because the only person harmed by dodging
   validation is the author of the post, whose publish then fails at the platform instead. The
   property worth having is that the editor and an honest API client see the same verdict,
   and that declaring your metadata truthfully is never punished while omitting it is
   rewarded.

3. The enforced numbers match what each platform documents.

4. Scheduling something the publisher would have fixed on its own (a crop) is not rejected.

Non-goals

• TikTok's account-dynamic creator_info.max_video_post_duration_sec. Still needs a
  fetch-at-validate-time design; out of scope, issue Harden media constraints: backend validation, reliable video meta, square YouTube Shorts #200 stays open for it.
• Minimum video resolution (FB Reel/Story 540×960). Documented but deferred — one more field
  across enum, Inertia payload, useMedia.ts and toListingArray() for a rarely-hit case.
• Re-encoding, transcoding, or thumbnail generation. The probe reads; it never writes media.
• Changing how the editor crops. ImageCropperDialog is untouched.

Design

1. Split media rules into image limits and video limits

ContentType::mediaRules() currently exposes one aspect_ratio_min/aspect_ratio_max pair
per content type. That cannot express instagram_feed, which legitimately has different
limits for the image it posts and the Reel it becomes. Split the payload:

image_aspect_ratio_min / image_aspect_ratio_max      (was aspect_ratio_min / aspect_ratio_max)
video_aspect_ratio_min / video_aspect_ratio_max      (new)
max_video_duration_sec                               (existing, corrected)
min_video_duration_sec                               (new)

Corrected values:

Content type	image	video	duration
instagram_feed	0.8–1.91	0.01–10	3s – 15min (was 60s)
instagram_reel	—	0.01–10 (was 0.5–0.6)	3s – 15min
instagram_story	auto-fits	0.1–10 (was 0.5–0.6)	3s – 60s
facebook_reel	—	0.5–0.6	3s – 90s
facebook_story	—	0.5–0.6	3s – 60s
youtube_short	—	null – 1.0	null – 3min

instagram_feed's video row is the Reel's, because that is what the publisher turns it into.
youtube_short has no documented minimum duration — leave it null rather than assume
the 3s that Meta specifies for its own formats.

A null bound means "no limit on that side" and needs no new code: contentTypeMediaRules.ts
already types these as number | null, and useMedia.ts guards with
if (rules.aspectRatioMin && …), so null is skipped on both sides.

autoFitsImage() keeps skipping image aspect checks for instagram_story. That interacts
correctly with the split — story images are auto-fitted, story video is bounded by the video
pair.

Touches: ContentType::mediaRules(), toListingArray(), contentTypeMediaRules.ts,
useMedia.ts, ContentTypeCompatibleWithMedia.

2. App\Services\Media\VideoProbe

A sibling of MediaOptimizer — a plain class in App\Services\Media, no interface, resolved
through app(). That is the existing convention and Process::fake() makes an interface
unnecessary for testing.

probeLocalFile(string $absolutePath): ?VideoMeta
probeStoredPath(string $storagePath): ?VideoMeta

• probeStoredPath resolves its own source: Storage::path() on a local driver,
  Storage::temporaryUrl() on S3.
• Invocation uses the Process facade in array form. No user-controlled value is ever
  interpolated into a shell string. Short timeout.
• Binary from config('trypost.media.ffprobe_path'), env FFPROBE_PATH, default ffprobe.
• Parses format.duration (falling back to the video stream's duration) and the first video
  stream's width/height.
• Rotation is handled explicitly. stream.width/height are pre-rotation; phone video in
  portrait commonly arrives 1920×1080 with a display matrix of rotation: -90. When
  side_data_list[].rotation is ±90 or ±270, width and height are swapped. Reading this
  naively would classify every portrait phone video as landscape and reject it.
• Any failure — binary missing, timeout, non-zero exit, unparseable JSON — returns null and
  is logged at debug level. The caller stores no video meta, which is exactly today's
  behaviour. ffprobe is never on the critical path of an upload succeeding.

Wired at two points, one per storage shape:

Call site	Covers	Method
HasMedia::streamFileToStorage()	local disk: Herd, tests, API upload, MediaAttacher	probeLocalFile on the temp, before it is deleted
HasMedia::addMediaFromStoredPath()	S3: production, chunked multipart	probeStoredPath

3. Trust chain

Three changes that only make sense together.

3a. Close the write-side forgery. Drop meta.width, meta.height, meta.duration from
StoreAssetRequest, and the $clientMeta argument from AssetController::store. Nothing
sends them. medias.meta becomes wholly server-measured. This is deletion, not a new guard —
inverting the array_merge in HasMedia would leave the same hole open through a different
door.

3b. Read authoritative data at validation. ContentTypeCompatibleWithMedia resolves
size, mime_type and meta from the medias table by media.*.id — a single whereIn
per validation, memoised on the instance — and ignores the payload's copy of those fields.
Items with no id (the public API's bare external URL, which is downloaded later) keep
today's fail-open behaviour.

Ownership is not checked upstream: PostMediaRules requires media.*.id to be a string
and nothing more — no exists, no workspace scope. The medias table is polymorphic
(mediable_type / mediable_id, the workspace being the mediable for assets). So the lookup
is scoped to the post's workspace, and the rule takes that workspace: the web request has it
via $this->route('post'), errorsFor() accepts it as an argument, and
assertStoredPostCompatible() reads it off the post.

An id that does not resolve inside the workspace is treated as unknown metadata — the
numeric checks are skipped for that item, exactly as for an item with no id at all. It is
deliberately not a new rejection reason: an unresolvable id today means the payload's url is
what actually gets published, and turning that into a hard error would break callers for a
field that is currently decorative.

3c. Crop-aware aspect ratio. When a platform has meta.aspect_ratio set and it is not
original, the publisher will centre-crop before upload
(InstagramPublisher::cropImageForAspectRatio, FacebookPublisher). Validation must
therefore check the cropped ratio via AspectRatio::toFloat(), not the source's.

Without this, the AI creation flow regresses: StreamPostCreation writes
$meta['aspect_ratio'] on every AI-generated post (app/Jobs/Ai/StreamPostCreation.php:218),
so a 3:4 photo with aspect_ratio: '4:5' publishes cleanly today and would start returning
422 at schedule time.

The editor has the same blind spot today and is fixed in the same pass:
getMediaValidationWarning() and getMediaItemIssue() take an optional aspect-ratio
argument; usePostCompliance already holds platformMeta, and InstagramSettings.vue /
FacebookSettings.vue already hold props.meta.

4. Corrections carried over from PR #287

• i18n. Only lang/en/posts.php was updated for the YouTube Shorts description; the other
  15 locales still read "Vertical video up to 3 minutes". LocalizationParityTest does not
  catch this — the key exists, only the value is stale.
• First message, not last. errorsFor() overwrites ($errors[$key] = $message), so with
  several $fail() calls the caller receives the last, while the editor shows the
  first. Confirmed by execution: a LinkedIn post with a 6MB GIF reports "images must be
  under 5.0 MB" via API and "does not support animated GIFs" in the editor. Use ??=.
• Advertise what is enforced. toListingArray() — consumed by ListContentTypesTool and
  PlatformContentTypesResource — omits the aspect bounds, so API and MCP clients get a 422
  for a constraint they have no way to discover. Add the aspect pair(s) and
  min_video_duration_sec.
• Number::fileSize() replaces the hand-rolled formatBytes(). Verified equivalent:
  Number::fileSize(5242881, 1) → 5.0 MB, Number::fileSize(1073741824, 1) → 1.0 GB.
• Float in copy. "between 0.5 and 1." — a bound of 1.0 interpolates as 1. Format it.

5. Infrastructure

• docker/Dockerfile: add ffmpeg to the apk add in system-base (line 18). Covers the
  dev and production targets in one line.
• Forge VPS: apt-get install -y ffmpeg, documented in the deploy notes.
• .env.example + self-hosting docs: FFPROBE_PATH.
• CI needs no change — tests use Process::fake(). An optional integration test that shells
  out is skipped when the binary is absent.
• php artisan media:backfill-video-meta — chunked, probes existing videos via
  probeStoredPath, supports --dry-run. Without it we run two regimes indefinitely: old
  videos silently unvalidated, new ones enforced.

Testing

Level	What
Unit	VideoProbe JSON parsing against fixtures, including a rotated sample; failure modes (missing binary, timeout, bad JSON) all return null. Process::fake().
Unit	ContentTypeCompatibleWithMedia: DB-resolved meta beats payload; crop-aware aspect; corrected numbers per content type; ??= message ordering.
Unit	ContentType: the split payload shape and every corrected value.
Feature	API and MCP schedule — video over max_video_duration_sec → 422; under min_video_duration_sec → 422; out-of-range aspect with a crop set → passes.
Feature	Chunked upload on a local disk stores measured video meta.
Integration (skippable)	Real ffprobe against a checked-in fixture, skipped when the binary is missing.

Run with php artisan test --compact --parallel. The suite is at 3951 passing on this branch
today; that is the baseline to hold.

Risks

Rotation. The highest-consequence detail. ffmpeg 8.1.2 on the dev machine transposes
rather than writing a display matrix, so a rotated fixture could not be synthesised
locally during design. The plan must obtain a genuinely rotated sample (a real phone
recording) — or, at minimum, assert the behaviour through a stubbed ffprobe JSON payload
carrying side_data_list[].rotation. Do not assume this is handled because the code contains
a swap.

Breaking change for API and MCP clients. Posts that scheduled successfully before will
now be rejected when they genuinely violate a documented platform limit. Intended, but it is
a behaviour change on a public contract and belongs in the changelog. The corrected numbers
and crop-awareness mean the set of newly-rejected posts should be close to "posts that would
have failed at publish anyway".

S3 round trip per video upload. probeStoredPath issues a temporaryUrl and an HTTP
range read at upload time. Measured at ~0.04s CPU locally; over the network it costs one extra
request against storage. Acceptable for a once-per-upload cost, and it fails open.

Existing videos. Until the backfill command runs, previously-uploaded videos have no meta
and stay unvalidated. Fail-open, so nothing breaks — but the two regimes coexist until it runs.

Follow-ups (not this branch)

• TikTok dynamic max duration via creator_info.
• Minimum video resolution (FB Reel/Story 540×960).
• Scope media.*.id with an ownership rule on the web contract (hosted: true), where the
  id is always a real asset. Closes the fail-open gap on the one path where it costs nothing.
• A "recommended framing" warning — now that Instagram Reel accepts 0.01–10, the editor no
  longer tells anyone that a 16:9 video will letterbox in a Reel. ContentType::aspectRatio()
  ('9:16') already holds the guidance; it just has no warning surface. Product loss is mild
  and deliberate: a warning must never block scheduling, which is what the old numbers did.

[paulocastellano]

Phase 1 implementation plan — task-by-task, TDD, with the real code for each step. Would live at docs/superpowers/plans/2026-08-27-media-constraints-phase-1.md if committed.

---

Media Constraints — Phase 1: correct the numbers before arming them

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make every media constraint match what the platform actually documents, and make the editor and the backend agree, so that measuring video for real (Phase 2) cannot become a production regression.

Architecture: ContentType::aspectRatioBounds() is split into separate image and video bounds, because instagram_feed genuinely has different limits for the image it posts and the Reel it becomes. The corrected numbers flow to the Vue editor unchanged through the existing Inertia contentTypeMediaRules prop, so the frontend needs shape changes but no new plumbing. Aspect validation becomes crop-aware on both sides: when a platform has meta.aspect_ratio set, the publisher will centre-crop before upload, so the cropped ratio is what gets validated.

Tech Stack: Laravel 13.24, PHP 8.5, Pest 5, Vue 3 + Inertia v3, TypeScript.

Spec: docs/superpowers/specs/2026-08-27-media-constraints-design.md

Global Constraints

• Nothing in this phase may change runtime behaviour for video. Video metadata is never populated today (HasMedia::getMediaMetaFromBytes() handles images only), so every video aspect/duration path stays dormant until Phase 2. If a change here alters what a video post can do today, it is wrong.
• Validation rules live in FormRequests; numeric limits live only in App\Enums\PostPlatform\ContentType. Never re-hardcode a limit in JS or in a request.
• All 16 locales in lang/ must carry every new or changed key. LocalizationParityTest catches missing keys but not stale values.
• Arrow functions only in Vue/TS. No function declarations.
• Icons from @tabler/icons-vue, never lucide-vue-next.
• No HTML5 validation attributes on inputs.
• vendor/bin/pint --dirty --format agent after any PHP change.
• Never add Co-Authored-By or AI attribution to commits.
• Baseline to hold: php artisan test --compact --parallel → 3951 passed, 1 skipped.

Platform numbers (authoritative — copy verbatim)

Content type	image bounds	video bounds	min duration	max duration
instagram_feed	0.8 – 1.91	0.01 – 10.0	3	900
instagram_reel	—	0.01 – 10.0	3	900
instagram_story	—	0.1 – 10.0	3	60
facebook_reel	—	0.5 – 0.6	3	90
facebook_story	—	0.5 – 0.6	3	60
youtube_short	—	null – 1.0	null	180
everything else	null	null	null	unchanged

instagram_feed's video row is the Reel's, because InstagramPublisher::publishFeed() routes a single video to publishReel(). youtube_short has no documented minimum on either axis — leave both null, do not borrow Meta's 3 seconds.

---

Task 1: Split aspect bounds and correct the numbers

Files:

• Modify: app/Enums/PostPlatform/ContentType.php:296-320 (aspectRatioBounds, autoFitsImage), :191-208 (maxVideoDurationSec), :318-364 (mediaRules)
• Test: tests/Unit/Enums/ContentTypeTest.php

Interfaces:

• Consumes: nothing.
• Produces: imageAspectRatioBounds(): ?array{min: ?float, max: ?float}, videoAspectRatioBounds(): ?array{min: ?float, max: ?float}, minVideoDurationSec(): ?int. Removes aspectRatioBounds() and autoFitsImage(). mediaRules() keys aspect_ratio_min/aspect_ratio_max/auto_fits_image are replaced by image_aspect_ratio_min/image_aspect_ratio_max/video_aspect_ratio_min/video_aspect_ratio_max/min_video_duration_sec.

autoFitsImage() is deleted rather than kept: it existed only to skip image aspect checks on instagram_story, and with split bounds that content type has no image bounds at all. The Instagram story blurred-background behaviour lives in InstagramPublisher::publishStory() and does not consult it.

• Step 1: Write the failing tests

test('image and video aspect bounds are separate and match platform docs', function () {
    expect(ContentType::InstagramFeed->imageAspectRatioBounds())->toBe(['min' => 0.8, 'max' => 1.91]);
    expect(ContentType::InstagramFeed->videoAspectRatioBounds())->toBe(['min' => 0.01, 'max' => 10.0]);
    expect(ContentType::InstagramReel->imageAspectRatioBounds())->toBeNull();
    expect(ContentType::InstagramReel->videoAspectRatioBounds())->toBe(['min' => 0.01, 'max' => 10.0]);
    expect(ContentType::InstagramStory->videoAspectRatioBounds())->toBe(['min' => 0.1, 'max' => 10.0]);
    expect(ContentType::FacebookReel->videoAspectRatioBounds())->toBe(['min' => 0.5, 'max' => 0.6]);
    expect(ContentType::XPost->videoAspectRatioBounds())->toBeNull();
});

test('youtube shorts accepts anything up to square, with no lower bound', function () {
    expect(ContentType::YouTubeShort->videoAspectRatioBounds())->toBe(['min' => null, 'max' => 1.0]);
    expect(ContentType::YouTubeShort->minVideoDurationSec())->toBeNull();
});

test('instagram feed video follows reel limits because it publishes as a reel', function () {
    expect(ContentType::InstagramFeed->maxVideoDurationSec())->toBe(900);
    expect(ContentType::InstagramFeed->minVideoDurationSec())->toBe(3);
});

test('media rules expose split aspect bounds and the minimum duration', function () {
    $rules = ContentType::InstagramFeed->mediaRules();

    expect($rules)->toHaveKeys([
        'image_aspect_ratio_min', 'image_aspect_ratio_max',
        'video_aspect_ratio_min', 'video_aspect_ratio_max',
        'min_video_duration_sec',
    ]);
    expect($rules)->not->toHaveKeys(['aspect_ratio_min', 'aspect_ratio_max', 'auto_fits_image']);
    expect($rules['image_aspect_ratio_min'])->toBe(0.8);
    expect($rules['video_aspect_ratio_max'])->toBe(10.0);
});

• Step 2: Run tests to verify they fail

Run: php artisan test --compact --filter="aspect bounds|youtube shorts accepts|instagram feed video|split aspect"
Expected: FAIL — Call to undefined method … imageAspectRatioBounds().

• Step 3: Replace the bounds methods

Delete aspectRatioBounds() and autoFitsImage(). Add:

    /**
     * Aspect-ratio window for still images, from the platform's own docs.
     * Null when the content type publishes no image, or the platform states no limit.
     *
     * @return array{min: ?float, max: ?float}|null
     */
    public function imageAspectRatioBounds(): ?array
    {
        return match ($this) {
            // "Must be within a 4:5 to 1.91:1 range" — IG User Media reference.
            self::InstagramFeed => ['min' => 0.8, 'max' => 1.91],
            default => null,
        };
    }

    /**
     * Aspect-ratio window for video. Instagram publishes a far wider range than
     * its 9:16 recommendation; Facebook states 9 x 16 as the spec. YouTube
     * classifies anything square or taller as a Short, with no lower bound.
     *
     * @return array{min: ?float, max: ?float}|null
     */
    public function videoAspectRatioBounds(): ?array
    {
        return match ($this) {
            // A single video on the feed is published as a Reel — see InstagramPublisher::publishFeed().
            self::InstagramFeed, self::InstagramReel => ['min' => 0.01, 'max' => 10.0],
            self::InstagramStory => ['min' => 0.1, 'max' => 10.0],
            self::FacebookReel, self::FacebookStory => ['min' => 0.5, 'max' => 0.6],
            self::YouTubeShort => ['min' => null, 'max' => 1.0],
            default => null,
        };
    }

    /**
     * Shortest video the platform accepts, in seconds. Null when undocumented.
     */
    public function minVideoDurationSec(): ?int
    {
        return match ($this) {
            self::InstagramFeed, self::InstagramReel, self::InstagramStory,
            self::FacebookReel, self::FacebookStory => 3,
            default => null,
        };
    }

In maxVideoDurationSec(), change self::InstagramFeed => 60 to self::InstagramFeed => 15 * 60, with the comment // Feed video publishes as a Reel.

• Step 4: Update the mediaRules() payload

Replace the $bounds = $this->aspectRatioBounds(); line and the three affected array entries:

        $imageBounds = $this->imageAspectRatioBounds();
        $videoBounds = $this->videoAspectRatioBounds();

            'max_video_duration_sec' => $this->maxVideoDurationSec(),
            'min_video_duration_sec' => $this->minVideoDurationSec(),
            'image_aspect_ratio_min' => $imageBounds['min'] ?? null,
            'image_aspect_ratio_max' => $imageBounds['max'] ?? null,
            'video_aspect_ratio_min' => $videoBounds['min'] ?? null,
            'video_aspect_ratio_max' => $videoBounds['max'] ?? null,

Update the @return array{...} docblock to match, dropping aspect_ratio_min, aspect_ratio_max and auto_fits_image.

• Step 5: Run tests to verify they pass

Run: php artisan test --compact tests/Unit/Enums/ContentTypeTest.php
Expected: PASS. Existing assertions referencing aspectRatioBounds() will fail — update them to the new methods; do not delete a test to make it green.

• Step 6: Format and commit

vendor/bin/pint --dirty --format agent
git add app/Enums/PostPlatform/ContentType.php tests/Unit/Enums/ContentTypeTest.php
git commit -m "fix: split media aspect bounds by media type and correct them against platform docs"

---

Task 2: Advertise the constraints over API and MCP

Files:

• Modify: app/Enums/PostPlatform/ContentType.php (toListingArray)
• Modify: app/Mcp/Tools/Platform/ListContentTypesTool.php:17 (the #[Description] text)
• Test: tests/Unit/Enums/ContentTypeTest.php

Interfaces:

• Consumes: Task 1's imageAspectRatioBounds(), videoAspectRatioBounds(), minVideoDurationSec().
• Produces: toListingArray() gains image_aspect_ratio_min, image_aspect_ratio_max, video_aspect_ratio_min, video_aspect_ratio_max, min_video_duration_sec. Consumed by ListContentTypesTool and PlatformContentTypesResource.

An API or MCP client currently receives a 422 for an aspect constraint it has no way to discover, because toListingArray() never exposed the bounds. Enforcing an undiscoverable rule is a contract bug.

• Step 1: Write the failing test

test('the api and mcp listing advertises every constraint that is enforced', function () {
    $listing = ContentType::InstagramFeed->toListingArray();

    expect($listing)->toHaveKeys([
        'image_aspect_ratio_min', 'image_aspect_ratio_max',
        'video_aspect_ratio_min', 'video_aspect_ratio_max',
        'min_video_duration_sec',
    ]);
    expect($listing['image_aspect_ratio_min'])->toBe(0.8);
    expect($listing['min_video_duration_sec'])->toBe(3);
});

• Step 2: Run test to verify it fails

Run: php artisan test --compact --filter="advertises every constraint"
Expected: FAIL — keys absent.

• Step 3: Add the keys

Append to the toListingArray() return array, after max_document_bytes:

            'min_video_duration_sec' => $this->minVideoDurationSec(),
            'image_aspect_ratio_min' => $this->imageAspectRatioBounds()['min'] ?? null,
            'image_aspect_ratio_max' => $this->imageAspectRatioBounds()['max'] ?? null,
            'video_aspect_ratio_min' => $this->videoAspectRatioBounds()['min'] ?? null,
            'video_aspect_ratio_max' => $this->videoAspectRatioBounds()['max'] ?? null,

Update the @return array{...} docblock to match. In ListContentTypesTool, extend the description to end with: …per-type max image/video/document bytes, min/max video duration in seconds, image and video aspect-ratio bounds, default content_type).

• Step 4: Run tests to verify they pass

Run: php artisan test --compact tests/Unit/Enums/ContentTypeTest.php tests/Feature/Mcp
Expected: PASS.

• Step 5: Format and commit

vendor/bin/pint --dirty --format agent
git add app/Enums/PostPlatform/ContentType.php app/Mcp/Tools/Platform/ListContentTypesTool.php tests/Unit/Enums/ContentTypeTest.php
git commit -m "feat: expose aspect bounds and minimum video duration over API and MCP"

---

Task 3: Teach the validation rule the split bounds and minimum duration

Files:

• Modify: app/Rules/ContentTypeCompatibleWithMedia.php
• Test: tests/Unit/Rules/ContentTypeCompatibleWithMediaTest.php

Interfaces:

• Consumes: Task 1's bounds methods and minVideoDurationSec().
• Produces: private formatRatio(float): string; validateAspectRatio() gains no public surface. formatBytes() is deleted in favour of Illuminate\Support\Number::fileSize().

Three separate corrections land together because they touch the same two methods.

• Step 1: Write the failing tests

test('instagram reel accepts a landscape video now that bounds match the docs', function () {
    $media = [[
        'type' => MediaType::Video->value,
        'mime_type' => 'video/mp4',
        'meta' => ['width' => 1920, 'height' => 1080],
    ]];

    expect(runMediaRule(ContentType::InstagramReel->value, $media))->toBe([]);
});

test('youtube short accepts a very tall video because there is no lower bound', function () {
    $media = [[
        'type' => MediaType::Video->value,
        'mime_type' => 'video/mp4',
        'meta' => ['width' => 1080, 'height' => 2400],
    ]];

    expect(runMediaRule(ContentType::YouTubeShort->value, $media))->toBe([]);
});

test('instagram feed still bounds images at 4:5', function () {
    $media = [[
        'type' => MediaType::Image->value,
        'mime_type' => 'image/jpeg',
        'meta' => ['width' => 1200, 'height' => 1600],
    ]];

    $errors = runMediaRule(ContentType::InstagramFeed->value, $media);

    expect($errors)->toHaveCount(1);
    expect($errors[0])->toContain('at least 0.80');
});

test('rejects a video shorter than the platform minimum', function () {
    $media = [[
        'type' => MediaType::Video->value,
        'mime_type' => 'video/mp4',
        'meta' => ['duration' => 2, 'width' => 1080, 'height' => 1920],
    ]];

    $errors = runMediaRule(ContentType::FacebookReel->value, $media);

    expect($errors)->toHaveCount(1);
    expect($errors[0])->toContain('at least 3s');
});

test('a video with unknown duration is still skipped rather than rejected', function () {
    $media = [['type' => MediaType::Video->value, 'mime_type' => 'video/mp4']];

    expect(runMediaRule(ContentType::FacebookReel->value, $media))->toBe([]);
});

• Step 2: Run tests to verify they fail

Run: php artisan test --compact tests/Unit/Rules/ContentTypeCompatibleWithMediaTest.php
Expected: FAIL — landscape reel rejected, no minimum-duration message exists.

• Step 3: Rewrite the per-item constraint methods

Add use Illuminate\Support\Number; at the top. Delete the private formatBytes() helper entirely and replace every call with Number::fileSize($bytes, 1). In the video branch of validateItemConstraints(), after the max-duration check:

            $minDuration = $contentType->minVideoDurationSec();

            if ($minDuration && $duration > 0 && $duration < $minDuration) {
                $fail("{$contentType->label()} videos must be at least ".self::formatDuration($minDuration).' long.');
            }

The $duration > 0 guard keeps unknown duration fail-open, matching the maximum check.

Replace validateAspectRatio() wholesale:

    /**
     * @param  array<string, mixed>  $item
     * @param  Closure(string, ?string=): PotentiallyTranslatedString  $fail
     */
    private function validateAspectRatio(ContentType $contentType, array $item, Closure $fail): void
    {
        $bounds = $this->isVideo($item)
            ? $contentType->videoAspectRatioBounds()
            : $contentType->imageAspectRatioBounds();

        if (! $bounds) {
            return;
        }

        $width = (float) data_get($item, 'meta.width', 0);
        $height = (float) data_get($item, 'meta.height', 0);

        if ($width <= 0 || $height <= 0) {
            return;
        }

        $ratio = $width / $height;

        if ($bounds['min'] !== null && $ratio < $bounds['min']) {
            $fail("{$contentType->label()} media must have an aspect ratio of at least ".self::formatRatio($bounds['min']).'.');
        }

        if ($bounds['max'] !== null && $ratio > $bounds['max']) {
            $fail("{$contentType->label()} media must have an aspect ratio of at most ".self::formatRatio($bounds['max']).'.');
        }
    }

    private static function formatRatio(float $ratio): string
    {
        return number_format($ratio, 2);
    }

formatRatio fixes the "between 0.5 and 1." copy — a bound of 1.0 used to interpolate as bare 1.

• Step 4: Make errorsFor() keep the first message

In errorsFor(), change the closure body from $errors[$entry['key']] = $message; to:

                    $errors[$entry['key']] ??= $message;

The editor reports the first violation it finds (getMediaValidationWarning returns early); the API reported the last. A LinkedIn post with an oversized GIF said "does not support animated GIFs" in the editor and "images must be under 5.0 MB" over the API. Add:

test('the api surfaces the same first violation the editor shows', function () {
    $media = [[
        'type' => MediaType::Image->value,
        'mime_type' => 'image/gif',
        'size' => ContentType::LinkedInPost->maxImageBytes() + 1,
    ]];

    $errors = ContentTypeCompatibleWithMedia::errorsFor(
        [['key' => 'platforms.0.content_type', 'content_type' => ContentType::LinkedInPost->value]],
        $media,
    );

    expect($errors['platforms.0.content_type'])->toContain('does not support animated GIFs');
});

• Step 5: Run tests to verify they pass

Run: php artisan test --compact tests/Unit/Rules/ContentTypeCompatibleWithMediaTest.php
Expected: PASS. PR #287's rejects media outside the content type aspect ratio window test asserted the old 0.5–0.6 reel window — update it to assert the documented range, do not delete it.

• Step 6: Format and commit

vendor/bin/pint --dirty --format agent
git add app/Rules/ContentTypeCompatibleWithMedia.php tests/Unit/Rules/ContentTypeCompatibleWithMediaTest.php
git commit -m "fix: validate aspect per media type, enforce minimum video duration, report the first violation"

---

Task 4: Make aspect validation crop-aware

Files:

• Modify: app/Rules/ContentTypeCompatibleWithMedia.php (the whole change lives here)
• Verify only, likely unchanged: app/Http/Requests/App/Post/UpdatePostRequest.php:52-56, app/Http/Requests/Api/Post/UpdatePostRequest.php:110-125, app/Mcp/Tools/Post/UpdatePostTool.php:76-90
• Test: tests/Unit/Rules/ContentTypeCompatibleWithMediaTest.php, tests/Feature/Api/PostApiPlatformMetaTest.php

Interfaces:

• Consumes: Task 3's validateAspectRatio().
• Produces: constructor becomes __construct(private ?array $fallbackMedia = null, private ?string $cropAspectRatio = null). entriesForUpdate() entries gain an aspect_ratio key: array{key: string, content_type: ?string, aspect_ratio: ?string}. errorsFor() keeps its two-argument signature and reads aspect_ratio off each entry.

When a platform has meta.aspect_ratio set to something other than original, InstagramPublisher::cropImageForAspectRatio() centre-crops the image before upload, so the source ratio is not what gets published. StreamPostCreation writes that meta on every AI-generated post, so without this a 3:4 photo with aspect_ratio: '4:5' publishes cleanly today and would start returning 422.

Cropping applies to images only — the publishers never crop video.

• Step 1: Write the failing tests

test('an image outside the window passes when a crop will bring it inside', function () {
    $media = [[
        'type' => MediaType::Image->value,
        'mime_type' => 'image/jpeg',
        'meta' => ['width' => 1200, 'height' => 1600],
    ]];

    $errors = ContentTypeCompatibleWithMedia::errorsFor([[
        'key' => 'platforms.0.content_type',
        'content_type' => ContentType::InstagramFeed->value,
        'aspect_ratio' => AspectRatio::Square->value,
    ]], $media);

    expect($errors)->toBe([]);
});

Use Square (1.0), not Portrait. Portrait resolves to 4 / 5, which lands exactly on
Instagram Feed's 0.8 minimum — a float-boundary comparison is a fragile thing to hang a
regression test on, even though both values round to the same double.

test('original means no crop, so the source ratio is still validated', function () {
    $media = [[
        'type' => MediaType::Image->value,
        'mime_type' => 'image/jpeg',
        'meta' => ['width' => 1200, 'height' => 1600],
    ]];

    $errors = ContentTypeCompatibleWithMedia::errorsFor([[
        'key' => 'platforms.0.content_type',
        'content_type' => ContentType::InstagramFeed->value,
        'aspect_ratio' => AspectRatio::Original->value,
    ]], $media);

    expect($errors)->toHaveCount(1);
});

test('a crop selection never rescues a video, which is published uncropped', function () {
    $media = [[
        'type' => MediaType::Video->value,
        'mime_type' => 'video/mp4',
        'meta' => ['width' => 1920, 'height' => 1080],
    ]];

    $errors = ContentTypeCompatibleWithMedia::errorsFor([[
        'key' => 'platforms.0.content_type',
        'content_type' => ContentType::FacebookReel->value,
        'aspect_ratio' => AspectRatio::Square->value,
    ]], $media);

    expect($errors)->toHaveCount(1);
});

• Step 2: Run tests to verify they fail

Run: php artisan test --compact tests/Unit/Rules/ContentTypeCompatibleWithMediaTest.php
Expected: FAIL — the first test reports an aspect error because the crop is ignored.

• Step 3: Thread the crop ratio through the rule

Add use App\Enums\PostPlatform\AspectRatio;. Change the constructor:

    public function __construct(
        private ?array $fallbackMedia = null,
        private ?string $cropAspectRatio = null,
    ) {}

Thread the crop ratio down as an explicit parameter rather than mutating instance state —
validate() resolves it once, then hands it to validateItemConstraints(), which hands it to
validateAspectRatio(). Both of those signatures gain ?string $cropAspectRatio as their
final parameter before $fail.

In validateAspectRatio(), replace the source-ratio calculation with:

        $ratio = $this->effectiveAspectRatio($item, $cropAspectRatio);

        if ($ratio === null) {
            return;
        }

and add:

    /**
     * The ratio that will actually be published: the crop target when the
     * platform asked for one (publishers centre-crop images before upload),
     * otherwise the source's own ratio. Null when the source is unmeasured.
     *
     * @param  array<string, mixed>  $item
     */
    private function effectiveAspectRatio(array $item, ?string $cropAspectRatio): ?float
    {
        if (! $this->isVideo($item) && $cropAspectRatio !== null) {
            $crop = AspectRatio::tryFrom($cropAspectRatio);

            if ($crop !== null && $crop !== AspectRatio::Original) {
                return $crop->toFloat();
            }
        }

        $width = (float) data_get($item, 'meta.width', 0);
        $height = (float) data_get($item, 'meta.height', 0);

        return $width > 0 && $height > 0 ? $width / $height : null;
    }

• Step 4: Carry the crop ratio on each entry

In entriesForUpdate(), add aspect_ratio to both mapped shapes:

            return collect($requestPlatforms)->map(function ($platform, $index) use ($post): array {
                $stored = $post->postPlatforms()->where('id', data_get($platform, 'id'))->first();

                return [
                    'key' => "platforms.{$index}.content_type",
                    'content_type' => data_get($platform, 'content_type') ?? $stored?->content_type?->value,
                    'aspect_ratio' => data_get($platform, 'meta.aspect_ratio')
                        ?? data_get($stored?->meta, 'aspect_ratio'),
                ];
            })->all();

        return $post->postPlatforms()->enabled()->get()->values()
            ->map(fn ($postPlatform, $index): array => [
                'key' => "platforms.{$index}.content_type",
                'content_type' => $postPlatform->content_type?->value,
                'aspect_ratio' => data_get($postPlatform->meta, 'aspect_ratio'),
            ])->all();

In errorsFor(), pass it through: (new self($media, data_get($entry, 'aspect_ratio')))->validate(...). Update the @param docblocks on both methods to the new entry shape.

• Step 5: Feed the crop ratio from the web request

The web path registers one shared rule instance across platforms.*.content_type, so it
cannot be given a per-platform crop ratio at construction time. It does not need to be:
setData() has already populated $this->data with the whole request, and the attribute name
carries the index (platforms.0.content_type). So the rule resolves it itself, and
app/Http/Requests/App/Post/UpdatePostRequest.php needs no change at all — leave
new ContentTypeCompatibleWithMedia exactly as it is.

Add to the rule:

    private function resolveCropAspectRatio(string $attribute): ?string
    {
        if ($this->cropAspectRatio !== null) {
            return $this->cropAspectRatio;
        }

        $index = explode('.', $attribute)[1] ?? null;

        return $index === null
            ? null
            : data_get($this->data, "platforms.{$index}.meta.aspect_ratio");
    }

Call it once at the top of validate() into a local, and pass that local down through
validateItemConstraints() into validateAspectRatio():

        $cropAspectRatio = $this->resolveCropAspectRatio($attribute);

        foreach ($media as $item) {
            $this->validateItemConstraints($contentType, (array) $item, $cropAspectRatio, $fail);
        }

The constructor argument wins when set — that is the errorsFor() path, where $this->data
is empty because the rule is built directly rather than through the validator. The request
data is the fallback, which is the web path.

Since UpdatePostRequest needs no edit, the files actually touched in this task are the rule
plus the API request and MCP tool, which both call entriesForUpdate()/errorsFor() and
therefore pick the crop ratio up for free once those carry aspect_ratio. Verify that by
reading them; if they already just forward the entries, they need no edit either, and this
task is a single-file change plus tests.

• Step 6: Run tests to verify they pass

Run: php artisan test --compact tests/Unit/Rules tests/Feature/Api tests/Feature/Mcp
Expected: PASS.

• Step 7: Format and commit

vendor/bin/pint --dirty --format agent
git add app/Rules/ContentTypeCompatibleWithMedia.php app/Http/Requests tests/
git commit -m "fix: validate the cropped aspect ratio, not the source, when a platform crop is set"

---

Task 5: Reshape the frontend rule payload

Files:

• Modify: resources/js/lib/contentTypeMediaRules.ts:22-110
• Modify: resources/js/types/index.d.ts:83-84
• Test: covered by Task 6's behaviour tests plus npm run lint.

Interfaces:

• Consumes: Task 1's mediaRules() payload.

• Produces: MediaRules gains imageAspectRatioMin?, imageAspectRatioMax?, videoAspectRatioMin?, videoAspectRatioMax?, minVideoDurationSec? and loses aspectRatioMin, aspectRatioMax, autoFitsImage. ContentTypeMediaRule mirrors the snake_case payload.

• Step 1: Update both type definitions

In ContentTypeMediaRule, replace aspect_ratio_min, aspect_ratio_max and auto_fits_image with:

    min_video_duration_sec: number | null;
    image_aspect_ratio_min: number | null;
    image_aspect_ratio_max: number | null;
    video_aspect_ratio_min: number | null;
    video_aspect_ratio_max: number | null;

In MediaRules, replace aspectRatioMin, aspectRatioMax, autoFitsImage with:

    minVideoDurationSec?: number;
    imageAspectRatioMin?: number;
    imageAspectRatioMax?: number;
    videoAspectRatioMin?: number;
    videoAspectRatioMax?: number;

• Step 2: Update toMediaRules()

Replace the three trailing if blocks with:

    if (rule.min_video_duration_sec !== null) {
        mapped.minVideoDurationSec = rule.min_video_duration_sec;
    }

    if (rule.image_aspect_ratio_min !== null) {
        mapped.imageAspectRatioMin = rule.image_aspect_ratio_min;
    }

    if (rule.image_aspect_ratio_max !== null) {
        mapped.imageAspectRatioMax = rule.image_aspect_ratio_max;
    }

    if (rule.video_aspect_ratio_min !== null) {
        mapped.videoAspectRatioMin = rule.video_aspect_ratio_min;
    }

    if (rule.video_aspect_ratio_max !== null) {
        mapped.videoAspectRatioMax = rule.video_aspect_ratio_max;
    }

In resources/js/types/index.d.ts, rename the two aspect_ratio_* fields to the four new ones and add min_video_duration_sec.

• Step 3: Do not lint or commit yet

Renaming these fields breaks useMedia.ts, which is the only consumer. Task 6 fixes it and
the two commit together — they are one reviewable change split across two sections for
readability, not two independent deliverables. Go straight to Task 6.

---

Task 6: Apply the split and the crop in the editor's rule engine

Files:

• Modify: resources/js/composables/useMedia.ts:33-175
• Test: resources/js/composables/__tests__ if the project has one; otherwise verified through Task 9's browser/feature runs.

Interfaces:

• Consumes: Task 5's MediaRules.

• Produces: getMediaValidationWarning(contentType: string, media: MediaItem[], cropAspectRatio?: string | null) and getMediaItemIssue(item: MediaItem, contentType: string, cropAspectRatio?: string | null). New warning key video_too_short. The third parameter is optional, so existing call sites keep compiling and keep today's behaviour until Task 7 wires them.

• Step 1: Add the shared ratio helpers

Above getMediaValidationWarning:

const CROP_RATIOS: Record<string, number> = {
    '1:1': 1,
    '4:5': 4 / 5,
    '16:9': 16 / 9,
};

const aspectBoundsFor = (rules: MediaRules, item: MediaItem) => (isVideo(item)
    ? { min: rules.videoAspectRatioMin, max: rules.videoAspectRatioMax }
    : { min: rules.imageAspectRatioMin, max: rules.imageAspectRatioMax });

/**
 * The ratio that will actually be published: the crop target when the platform
 * asked for one (images only — video is never cropped), else the source's own.
 */
const effectiveRatio = (item: MediaItem, cropAspectRatio?: string | null): number | null => {
    if (!isVideo(item) && cropAspectRatio && cropAspectRatio !== 'original') {
        const cropped = CROP_RATIOS[cropAspectRatio];
        if (cropped) return cropped;
    }

    const width = item.meta?.width ?? 0;
    const height = item.meta?.height ?? 0;

    return width > 0 && height > 0 ? width / height : null;
};

MediaRules must be imported as a type in this file if it is not already.

• Step 2: Replace the aspect block in getMediaValidationWarning

Delete the if (width > 0 && height > 0 && ! (rules.autoFitsImage && isImage(m))) block and its two returns. Replace with:

        const bounds = aspectBoundsFor(rules, m);
        const ratio = effectiveRatio(m, cropAspectRatio);

        if (ratio !== null) {
            if (bounds.min && ratio < bounds.min) {
                return {
                    key: 'aspect_ratio_too_narrow',
                    params: { current: formatAspect(ratio), min: formatAspect(bounds.min) },
                };
            }
            if (bounds.max && ratio > bounds.max) {
                return {
                    key: 'aspect_ratio_too_wide',
                    params: { current: formatAspect(ratio), max: formatAspect(bounds.max) },
                };
            }
        }

Also remove the now-unused width/height locals at the top of the loop, and add the minimum-duration check immediately after the existing video_too_long check:

            if (rules.minVideoDurationSec && duration > 0 && duration < rules.minVideoDurationSec) {
                return {
                    key: 'video_too_short',
                    params: { current: date.formatDurationWords(duration), min: date.formatDurationWords(rules.minVideoDurationSec) },
                };
            }

Change the signature to (contentType: string, media: MediaItem[], cropAspectRatio?: string | null).

• Step 3: Apply the same three changes to getMediaItemIssue

Change its signature to (item: MediaItem, contentType: string, cropAspectRatio?: string | null), drop the autoFitsImage guard, use aspectBoundsFor + effectiveRatio, and add if (itemIsVideo && rules.minVideoDurationSec && duration > 0 && duration < rules.minVideoDurationSec) return 'video_too_short'; after the video_too_long return.

• Step 4: Map the new key for the publish gate

In resources/js/composables/usePostCompliance.ts, add to COMPLIANCE_KEY_BY_WARNING:

    video_too_short: 'video_too_short',

and in getMediaIncompatibilityReason, alongside the existing video_too_long param block:

    if (warning.key === 'video_too_short') {
        params.seconds = String(getMediaRulesForContentType(contentType).minVideoDurationSec ?? '');
    }

• Step 5: Verify it compiles

Run: npm run lint
Expected: PASS.

• Step 6: Commit

git add resources/js/lib/contentTypeMediaRules.ts resources/js/types/index.d.ts \
        resources/js/composables/useMedia.ts resources/js/composables/usePostCompliance.ts
git commit -m "fix: apply per-media-type aspect bounds and the crop target in the editor rule engine"

This commit carries Task 5's two files as well — that is intended.

---

Task 7: Feed the selected crop ratio into the compliance gate

Files:

• Modify: resources/js/composables/usePostCompliance.ts:116-215
• Modify: resources/js/components/posts/editor/InstagramSettings.vue:82
• Modify: resources/js/components/posts/editor/FacebookSettings.vue:82

Interfaces:

• Consumes: Task 6's optional third parameter.
• Produces: getMediaIncompatibilityReason(contentType, mediaItems, cropAspectRatio?). firstCompatibleVariant keeps its two-argument signature — variant snapping deliberately ignores the crop, since it answers "which post type could this media use at all".

Without this the editor still blocks the exact case Task 4 fixed on the backend: a 3:4 photo with PORTRAIT (4:5) selected on Instagram shows "Aspect ratio 0.63 is too tall for this post type (min 0.80)" even though the publisher would crop it and publish it fine.

• Step 1: Thread the parameter through getMediaIncompatibilityReason

export const getMediaIncompatibilityReason = (
    contentType: string,
    mediaItems: MediaItem[],
    cropAspectRatio?: string | null,
): string | null => {
    const warning = getMediaValidationWarning(contentType, mediaItems, cropAspectRatio);

• Step 2: Pass the platform's own meta at both call sites inside usePostCompliance

In mediaIssues:

                const reason = getMediaItemIssue(item, contentType, platformMeta.value[pp.id]?.aspect_ratio);

In platformIssues:

            const reason = getMediaIncompatibilityReason(
                contentType,
                media.value,
                platformMeta.value[pp.id]?.aspect_ratio,
            );

• Step 3: Pass it in the settings panels

In InstagramSettings.vue and FacebookSettings.vue, both at line 82:

const warning = computed(() => getMediaValidationWarning(props.contentType, props.media, props.meta?.aspect_ratio));

PinterestSettings.vue is left alone — Pinterest has no crop control and no aspect bounds.

• Step 4: Verify by hand in the app

Open a post with a 3:4 image, Instagram Feed selected. With ORIGINAL the error must still appear; switching to PORTRAIT (4:5) must clear it and re-enable scheduling. This is the user-visible payoff of Tasks 4 and 7 together.

Run: npm run lint
Expected: PASS.

• Step 5: Commit

git add resources/js/composables/usePostCompliance.ts resources/js/components/posts/editor/InstagramSettings.vue resources/js/components/posts/editor/FacebookSettings.vue
git commit -m "fix: stop blocking images in the editor that the platform crop would make valid"

---

Task 8: Translations across all 16 locales

Files:

• Modify: lang/{ar,de,el,en,es,fr,it,ja,ko,nl,pl,pt-BR,ru,tr,uk,zh}/posts.php

Interfaces:

• Consumes: Task 6's video_too_short warning key.
• Produces: posts.form.warnings.video_too_short and posts.edit.compliance.video_too_short in every locale, plus a corrected posts.content_types.youtube_short.description.

PR #287 changed the YouTube Shorts description in lang/en only; the other 15 still read "Vertical video up to 3 minutes". LocalizationParityTest passes because the key exists — it compares keys, never values. Since the aspect change is dormant until Phase 2, this copy is the only user-visible part of the Shorts fix, which makes it the deliverable rather than a nicety.

• Step 1: Correct the Shorts description in all 16 locales

lang/en/posts.php already reads 'Vertical or square video up to 3 minutes'. Translate that same meaning into the other 15, e.g. pt-BR: 'Vídeo vertical ou quadrado de até 3 minutos', es: 'Video vertical o cuadrado de hasta 3 minutos', de: 'Vertikales oder quadratisches Video bis zu 3 Minuten'. Match each file's existing tone and punctuation.

• Step 2: Add the two new keys in all 16 locales

Under posts.form.warnings, after video_too_long:

            'video_too_short' => 'Video is :current long, but this post type requires at least :min.',

Under posts.edit.compliance, after video_too_long:

            'video_too_short' => 'Video must be at least :seconds seconds for this format.',

• Step 3: Run the parity test

Run: php artisan test --compact --filter=Localization
Expected: PASS.

• Step 4: Commit

git add lang/
git commit -m "i18n: translate the square Shorts copy and the minimum video duration warnings"

---

Task 9: Full verification

Files: none — verification only.

• Step 1: Format and lint everything

vendor/bin/pint --format agent
npm run lint

• Step 2: Run the whole suite

Run: php artisan test --compact --parallel
Expected: 3951+ passed, 1 skipped, 0 failed. Any drop below the baseline means a test was deleted rather than updated — investigate before continuing.

• Step 3: Confirm the dormancy constraint held

Grep for any new code that reads meta.duration or meta.width on a video outside the validation rule. There should be none: Phase 1 must not start populating or depending on video metadata. Phase 2 does that.

• Step 4: Sanity-check the editor

With npm run dev running, confirm in the app: an Instagram Feed post with a 3:4 image blocks on ORIGINAL and passes on PORTRAIT (4:5); a Reel with a 16:9 video no longer shows an aspect error.

---

Phases 2 and 3

These are not planned here, deliberately. Their design is settled in the spec, but their task breakdown depends on the final shapes this phase lands, and planning them now would drift.

• Phase 2 — VideoProbe + infra (~10 files): the ffprobe service, wiring into HasMedia::streamFileToStorage() and addMediaFromStoredPath(), ffmpeg in the Dockerfile's system-base stage, deleting the client-meta forgery vector in StoreAssetRequest/AssetController, and the media:backfill-video-meta command. Must not start before Phase 1 merges — arming video measurement against the old 0.5–0.6 bounds would reject most Reels in production.
• Phase 3 — validation reads the database (~6 files): resolve size/mime_type/meta from the medias table by media.*.id, scoped to the post's workspace, with unresolvable ids treated as unknown metadata rather than an error.

Generate each plan from the spec when its turn comes.