Round 1 Feedback

This document captures the first round of review feedback on the Entity Media use case specifications (GEN::MEDIA::0001, GEN::MEDIA::0002). The feedback was collected as Hypothesis annotations in the arda-products group on 2026-03-23.

Source

All annotations are anchored to a single page:

Published URL	Repository File
`https://arda-cards.github.io/documentation/product/use-cases/general-behaviors/entity-behaviors/entity-media/`	`documentation/src/content/docs/product/use-cases/general-behaviors/entity-behaviors/entity-media.md`

Feedback Summary

#	Annotation ID	Section Quoted	Suggestion (Uriel)	Response (Miguel)	Resolution
1	`FifBci`	Unified input surface	Camera capture: Add a dedicated “Take photo” affordance for mobile/warehouse personas instead of relying on OS file picker’s inconsistent camera trigger.	Agreed, this needs to be reworked together with: GEN::MEDIA::0001:0002.FS	Accepted
2	`S0heKi`	”On cancel, no change is made”	Error recovery: Keep the image area active after validation failure so the user can retry immediately. Don’t restart from scratch. Confirm all error messages are plain language.	Addressed indirectly — Miguel’s interaction state diagram (`r1j1oi`) includes a `FailedValidation` → `Retry` path back to `EmptyImage`, confirming inline retry.	Accept Suggestion, design non-happy-path use cases and interaction states
3	`rzwRnC`	”Accepted image formats: JPEG, PNG, WebP”	HEIC/HEIF missing: Default iPhone photo format. Mobile users will get rejections. Accept natively or auto-convert. Also decide on SVG.	Accept HEIC — the system stores and the browser renders, so it’s the easier approach. Pending: confirmation that most browsers support HEIC display. Also: investigate format coverage needed for target personas.	Accepted, extends Use Cases. Project will need to confirm that HEIC is properly rendered by mainstream browsers
4	`6HVxpi`	”Maximum file size: default 10 MB”	Compress before reject: Auto-compress/resize oversized files (85% JPEG, max 2048px) instead of hard-rejecting. The crop canvas already supports re-encoding. Show “image will be optimized” message.	Nice-to-have if it doesn’t introduce too much scope creep. Fallback: provide instructions for the user to do it themselves.	To be investigated during project definition and planning.
5	`f01r2C`	”Target aspect ratio defined by entity type”	1:1 crop default: Square images tile well in grids. Default to locked 1:1 for products; allow unlocking for edge cases (banners, packaging). Clarify whether stored image is always square.	Aspect ratio is a design-time parameter of the generic component. Item product image = 1:1, not modifiable by user.	Accept suggestion with Response specification
6	`vyhyti`	”Preview works identically regardless of input method”	Background removal (future): Optional “Remove background” toggle in crop/preview. Client-side ML or server-side API. Output shifts to transparent PNG. Spec as separate `0007.FS`. Not v1.	Nice to have. Document the Use Case now, de-scope from project definition.	Document as additional operation in edit capabilities (basic: Crop, Zoom, Rotate, Pan, Reset to original), not scoped for V1.
7a	`GhvVoC`	”External URL path”	Fetch-and-store all URLs: Don’t store external URLs as links — fetch at ingest, run through crop/compress, store on CDN. One rendering path. Keep original URL in metadata for provenance.	Needs discussion regarding legal and copyright compliance.	Pending
7b	`-rROWC`	”Reachability check”	(Same suggestion, different anchor): Fetch image at ingest time; HTTPS/reachability/content-type checks happen once at ingest. Stored image always from CDN.	Pending resolution of legal/copyright implications. Agreed, needs to be reworked together with input detection and routing (`0002.FS`).	Pending
8	`UGRc1i`	”Archival and purging out of scope”	Storage cleanup: Quantify expected growth (entities x avg size x replacement frequency). Acknowledge as future concern. Ensure schema supports efficient purging later.	Agreed. At current scale/tenant count, can be postponed. Create a GitHub ticket to decide and implement a retention policy.	Postponed, Create GH Ticket to address.
9	`f_Ahzi`	”Current image remains visible during interaction”	Comparison layout: Specify how old/new comparison works — side-by-side shrinks too much for quality judgment. Recommend toggle/swipe at full preview size. Also: specify drop zone visual affordances (dashed border, drag highlight).	Agreed. Desktop: existing image in small window, new image in larger viewport. Mobile: two tabs for easy flipping. Provided full state diagram (View → EmptyImage → ProvidedImage → Accept/Discard/Warn, with FailedValidation → Retry). Drop zone shows in EmptyImage state with URL field, upload button, dismiss.	Accept, Update Use Cases with information.
10	`uLtRwi`	”User activates the image area”	Cross-cutting concerns: (1) Who can set/remove images? Role-restricted? (2) Concurrent edits — last-write-win? Audit trail? (3) Bulk CSV with fetch-and-store needs background job queue. (4) Does empty CSV column mean “no change” or “remove”? Recommend empty = no change, `REMOVE` sentinel for explicit removal.	(1) All users can modify images for now; fine-grained permissions later. (2) Last-user-wins; bitemporal persistence provides audit trail. (3) Built-in audit via bitemporal layer. (4) Bulk import needs discussion in light of fetch-and-store. (5) API uses `PUT` semantics (full entity replacement) — blanks unprovided fields. `PATCH` is future/not in roadmap.	Clarification Only. Find a place in the documentation to document these aspects.
11	`0gbacC`	”Clipboard paste” paragraph	Clipboard edge cases: Paste varies by source app — Google Docs gives HTML with embedded URL, Figma/Slack differ. Spec should clarify: extract blob, follow embedded URL, or reject? Users expect paste to “just work” regardless of source.	Agreed, needs to be reworked together with input detection and routing (`0002.FS`).	Accepted: (1) Update Use Cases to include candidate applications, initial list: Google Docs, Google Image Search, Amazon.com, Slack, Gmail, Outlook (desktop), Windows and Mac file explorers. Investigate during project definition and planning to decide scope and approach.

Topics

Each topic below identifies a change to be made to the use case specification in entity-media.md. Topics have been updated to reflect the resolutions recorded in the Feedback Summary table above.

T-01: Add Error Recovery Flow to `0001.UC`

Addresses: Row 2 | Resolution: Accepted

Design non-happy-path use cases and interaction states. The main use case scenario (GEN::MEDIA::0001::0001.UC) does not specify what happens after a validation failure. Add branches that describe:

The error recovery path: the image area remains active with the error message displayed inline, and the user can immediately provide a different image without restarting the interaction.
The interaction states for failure and retry, consistent with Miguel’s state diagram (FailedValidation → Retry → EmptyImage).
Additional non-happy-path scenarios: network failure during upload, timeout, and concurrent edit detection (if applicable).

T-02: Expand Accepted Formats in `0003.FS`

Addresses: Row 3 | Resolution: Accepted — extends Use Cases

Update GEN::MEDIA::0001::0003.FS (Content Validation) to expand the accepted formats list. Current spec: JPEG, PNG, WebP. Changes:

Add HEIC/HEIF — default photo format on modern iPhones and many Android devices. The system stores and the browser renders, so native acceptance is the simpler path.
Implementation prerequisite: Confirm that HEIC is properly rendered by mainstream browsers before committing to native acceptance. Safari and Chrome support HEIC; Firefox support is partial. If browser coverage is insufficient, fall back to server-side conversion to JPEG/PNG on ingest.
Make an explicit decision on SVG (relevant if product images come from design teams). If rejected, state why.
Update the plain-language error message for unsupported formats to include the expanded list.

T-03: Rework Input Detection and Routing in `0002.FS`

Addresses: Rows 7a, 7b, 11

This topic covers two related changes. The fetch-and-store change is blocked; the clipboard change is accepted.

Fetch-and-store for external URLs (Rows 7a, 7b): Pending — blocked on legal/copyright review.

The current spec has two outcomes — managed upload (CDN URL) and external URL (stored as-is). The suggestion is to collapse to a single outcome: all images go through managed storage. External URLs are fetched at ingest time, processed through the same crop/compress pipeline, and stored on the CDN. The original URL is kept in metadata for provenance.

Blocker: Fetching and storing third-party images raises copyright and licensing questions that must be resolved before the spec can be updated. A Copyright Liability Consultation has been prepared analyzing the risk profile of each upload method. Key findings:
- Server-side fetching (Method 5b) is the highest-risk scenario — the platform becomes the direct copier, potentially defeating DMCA safe harbor. The user’s copyright acknowledgment (see Addendum 1) does not cure direct infringement by the platform.
- Browser-side rendering (Method 5a) has lower risk under the Ninth Circuit server rule but remains unsettled in other circuits (Nicklen v. Sinclair, S.D.N.Y. 2021).
- If server-side copy is required, the consultation recommends implementing as a proper caching proxy respecting HTTP caching semantics, which is closer to the DMCA § 512(b) caching safe harbor.
If adopted: The input detection section simplifies (all paths converge to managed upload), but a new async fetch-and-process step is needed for the URL path.
Pending: No changes to entity-media.md until the legal review completes.

Clipboard paste edge cases (Row 11): Accepted.

Update GEN::MEDIA::0001::0002.FS to document clipboard behavior per source application. Add a list of candidate applications to investigate:

Google Docs
Google Image Search
Amazon.com
Slack
Gmail
Outlook (desktop)
Windows file explorer
macOS Finder

For each, the spec should describe what clipboard content the application produces (image blob, HTML with embedded URL, proprietary format) and how the system handles it. The detailed scope and approach for each application will be determined during project definition and planning.

T-04: Specify Comparison Layout in `0005.FS`

Addresses: Row 9 | Resolution: Accepted — update Use Cases

Update GEN::MEDIA::0001::0005.FS (Preview and Crop) with the comparison layout specification from Miguel’s response:

Desktop: Existing image in a small reference window; new image in a larger viewport.
Mobile / small viewports: Two tabs that are easy to flip back and forth.
No existing image: Comparison area is not shown; only the new image preview is displayed.
Drop zone affordances: The empty image state shows a dashed-border drop area with drag-and-drop/paste target, a URL text field, an “upload from computer” button, and a dismiss button.

Also incorporate the interaction state diagram from Miguel’s annotation:

View → EmptyImage (edit/add)
EmptyImage → ProvidedImage (user input, success)
EmptyImage → FailedValidation (user input, failure)
ProvidedImage → accept / discard / edit (crop/pan/zoom/reset) / dismiss
Dismiss from ProvidedImage → Warn (confirm discard or cancel)
FailedValidation → dismiss or retry

T-05: Clarify Aspect Ratio as Design-Time Parameter in `0005.FS`

Addresses: Row 5 | Resolution: Accepted with Response specification

Update GEN::MEDIA::0001::0005.FS to clarify that the crop aspect ratio is a design-time parameter of the generic Entity Media component, not a user-selectable option. The user cannot unlock or change the ratio at runtime (unlike the original suggestion to allow unlocking for edge cases). Specific ratios per entity type:

Item product image: 1:1 (square), not modifiable by user.
Other entity types will define their own ratios at design time as they are implemented.

T-06: Add Cross-Cutting Concerns Section

Addresses: Row 10 | Resolution: Clarification only — document existing behavior

These are not new decisions but existing system behaviors that need to be documented. Find an appropriate location in the documentation (either a new section in entity-media.md or cross-references to existing documentation) to capture:

Permissions: All authenticated users can set and remove images. Fine- grained role-based restrictions are deferred to a future permissions implementation.
Concurrency: Last-user-wins semantics apply. The system does not lock the entity during image editing. The bitemporal persistence layer provides a full audit trail of who changed the image and when.
Bulk CSV semantics: Clarify the interaction between PUT semantics (full entity replacement) and the image field. An omitted image field in a CSV row blanks the image (consistent with PUT semantics). PATCH semantics are not in the current roadmap.

T-07: Document Compression as Future Enhancement

Addresses: Row 4 | Resolution: Investigate during project definition and planning

Add a note to GEN::MEDIA::0001::0003.FS (Content Validation) acknowledging auto-compression as a potential enhancement. The decision on whether to include it will be made during project definition and planning based on scope assessment. Two approaches under consideration:

Auto-compress: If the raw file exceeds the size limit, automatically compress/resize (e.g., 85% JPEG quality, max 2048px on longest edge) and only reject if the result is still too large. Show an inline message: “Your image will be optimized for best display quality.”
Manual fallback: Hard-reject with a plain-language message and provide instructions for the user to resize the image themselves.

T-08: Document Image Edit Operations as Future Capabilities

Addresses: Row 6 | Resolution: Document, not scoped for V1

Document the following as edit operations available in the crop/preview step. The basic set is in scope for V1; advanced operations are documented for future implementation:

Basic (V1):

Crop (within the entity-type aspect ratio)
Zoom
Rotate
Pan
Reset to original

Advanced (future):

Background removal — optional toggle that strips the background and outputs a transparent PNG. May be implemented via client-side ML or server-side API. Must handle poor results gracefully with fallback messaging.

Mark advanced operations as de-scoped from the current project. The use case documentation is written now for completeness; implementation is deferred.

T-09: Create Retention Policy Ticket

Addresses: Row 8 | Resolution: Postponed — create GitHub ticket

Create a GitHub ticket in Arda-cards/management to define and implement a storage retention policy for superseded images. The ticket should reference:

The “no automated cleanup” decision in GEN::MEDIA::0002.
Uriel’s suggestion to quantify expected storage growth (entities x average image size x replacement frequency).

Add a cross-reference from the GEN::MEDIA::0002 spec to the ticket once created.

T-10: Add Camera Capture as Named Input Method in `0002.FS`

Addresses: Row 1 | Resolution: Accepted

Camera capture is accepted as a named input method. Update GEN::MEDIA::0001::0002.FS (Input Detection and Routing) to:

Add camera capture as a fifth named input method alongside file pick, drag-and-drop, clipboard paste, and URL entry.
Document the routing: camera capture produces a file (photo) that follows the same managed upload path as file pick.
The detailed mobile interaction design (tap targets, viewfinder framing, orientation handling) remains deferred to a future mobile UX session, but the input method is acknowledged in the use case now.

T-11: Add Copyright Verification Prompt to Upload Flow

Source: Copyright Liability Consultation — Addendum 1

The consultation recommends adding a user-facing copyright acknowledgment at the point of image upload. This is a net positive with no legal downside — strengthens DMCA safe harbor eligibility, reinforces the red-flag knowledge defense, and establishes a contractual indemnification basis.

Update the use case specification to include a copyright verification step in the upload flow:

Add a step in GEN::MEDIA::0001::0001.UC where the user must provide an affirmative acknowledgment (mandatory checkbox or click, not passive notice) before the upload is accepted.
The acknowledgment confirms that the user owns or has licensed the image and that uploading infringing material constitutes grounds for account termination.
The system logs the acknowledgment with a timestamp and authenticated user identity.
The acknowledgment applies to all input methods (file upload, paste, camera, screenshot, URL entry).

This topic should be implemented regardless of the fetch-and-store decision (T-03). The prompt strengthens the platform’s legal posture for all upload paths, but it does not cure the direct infringement risk for server-side URL fetching (Method 5b).

Source: Copyright Liability Consultation — Addendum 2

Cross-tenant sharing of reference data (including images) changes the copyright risk profile. The consultation identifies constraints that should be documented in the use case specifications:

Authenticated access only. Images shared between tenants must never be accessible via unauthenticated URLs. This is the single most important constraint for preserving the non-public characterization under both U.S. and EU copyright law.
Tenant-initiated sharing. Sharing must be initiated by the owning tenant. The platform must not algorithmically surface, recommend, or curate cross-tenant content (this would risk crossing the “active role” threshold that can imperil DMCA § 512(c) eligibility).
Copyright acknowledgment on share. When a tenant shares reference data containing images, present the same copyright acknowledgment as at upload (see T-11). The sharer confirms they have the right to share the content with the recipient organization.
EU Article 17 review. The cross-tenant sharing feature introduces sufficient uncertainty that a formal EU IP counsel opinion is recommended before enabling the feature for EU customers.

These constraints are not specific to GEN::MEDIA but affect any future use case involving cross-tenant data sharing. Document them in a cross-cutting section or a dedicated sharing policy specification.

Topic Summary

Id	Summary	Scoping Decision
T-01	Add error recovery flow to `0001.UC`	Accepted — design non-happy-path use cases and interaction states
T-02	Expand accepted formats (HEIC/HEIF, SVG) in `0003.FS`	Accepted — confirm HEIC browser rendering before implementation
T-03	Rework input detection/routing in `0002.FS` (fetch-and-store, clipboard edge cases)	Partially accepted — clipboard edge cases accepted with candidate app list; fetch-and-store pending legal review
T-04	Specify comparison layout in `0005.FS`	Accepted — update Use Cases with layout and state diagram
T-05	Clarify aspect ratio as design-time parameter in `0005.FS`	Accepted — 1:1 for Items, not user-modifiable
T-06	Add cross-cutting concerns section (permissions, concurrency, bulk CSV)	Clarification only — document existing behavior
T-07	Document auto-compression as future enhancement in `0003.FS`	Investigate during project definition and planning
T-08	Document image edit operations (basic V1 + advanced future)	Document basic and advanced ops; advanced de-scoped from V1
T-09	Create retention policy GitHub ticket	Postponed — create ticket to address later
T-10	Add camera capture as named input method in `0002.FS`	Accepted — add as fifth input method; defer detailed mobile UX
T-11	Add copyright verification prompt to upload flow	From consultation Addendum 1 — implement for all upload methods
T-12	Document cross-tenant sharing constraints for images	Postpone pending resolution of legal aspects

Round 1 Changelog

Changes applied to entity-media.md on 2026-03-23 in response to the feedback summarized above.

Topic	Section Changed	Change Description
T-01	`0001.UC`	Added error recovery paragraph: inline error display, image area stays active, error clears on new input.
T-02	`0003.FS`	Added HEIC/HEIF to accepted formats. Added SVG exclusion rationale. Updated format error message.
T-03	`0002.FS`	Expanded clipboard paste bullet into three sub-cases: image blob, HTML with embedded URL (with candidate app list), and unrecognized format.
T-04	`0005.FS`	Added comparison layout (desktop: small reference + large preview; mobile: two tabs). Added drop zone affordances. Added interaction state diagram (View, EmptyImage, ProvidedImage, FailedValidation, Warn).
T-05	`0005.FS`	Clarified crop aspect ratio as a design-time parameter, not user-modifiable. Added Item 1:1 square example.
T-06	New section	Added “Cross-Cutting Concerns” section after `GEN::MEDIA::0002`: Permissions (all users), Concurrency (last-user-wins, bitemporal audit), Bulk CSV Semantics (`PUT` replaces full entity).
T-07	`0003.FS`	Added auto-compression behavior: system attempts resize/compress before rejecting oversized files. Added inline optimization message.
T-08	`0005.FS`	Added “Edit operations” block: Crop, Zoom, Rotate, Pan, Reset (basic) and Remove background (advanced).
T-10	`0002.FS`	Expanded camera capture bullet: dedicated “Take photo” affordance on mobile, desktop OS dialog option, pointer to mobile UX specification.
T-11	`0006.FS`	Added copyright acknowledgment step before upload: mandatory checkbox/click, logged with timestamp and user identity, applies to all input methods.

Not applied (pending or postponed):

Topic	Reason
T-03 (fetch-and-store)	Pending legal/copyright review
T-09	Postponed — GitHub ticket to be created during project implementation
T-12	Postponed — pending resolution of legal aspects