Disclosure: This draft was generated with AI and checked against the cited primary sources, with a separate AI editorial review. It was prepared for the FrameSprite team, which has a commercial interest in FrameSprite. Proposed examples are not executed tests unless explicitly identified as recorded fixture results.
Declare whether a manifest field contains a filesystem path or a URL. A hash sign in a filename is ordinary file data in some contexts but a fragment delimiter in a URI. Encode path components for the intended consumer instead of applying ad hoc replacements to an entire string.
Key Takeaways
- Keep filesystem names and URI references distinct.
- Encode each component once at the serialization boundary.
- Test the exact URL consumed by the browser.
One string can have different meanings
RFC 3986 defines reserved URI characters and components. A browser URL containing an unescaped hash sign has a fragment component. It does not necessarily request a file whose literal basename contains that character.
The failure can look like a caching or loader problem because the browser successfully requests a shorter path. Check the actual requested resource before regenerating the artwork or changing image formats.
Establish the manifest contract
Name fields according to their meaning. For example, a local export record can contain a filesystem-relative path, while a web delivery record contains a URI reference. Specify what base each relative value uses and who converts between representations.
RFC 8259 defines JSON string syntax. A valid JSON string is not automatically a valid or correctly encoded URL. JSON escaping and URI percent-encoding solve different problems.
Use a URL builder for web references and filesystem path utilities for local paths. Avoid joining URL components with operating-system path functions. Avoid repeatedly encoding already encoded values.
Example: a ranked attack variant
A designer names an export attack#2.png. A local viewer opens it, but a web manifest uses the literal name inside a URL string. The browser interprets the hash and following characters as a fragment, so the request no longer identifies the intended file.
One repair is a documented portable delivery name such as attack-variant-2.png, with every reference updated. Another is correct encoding of the filename component, if the delivery system supports that naming policy. Choose one contract rather than mixing literal and encoded names in different manifests.
Check both the serialized manifest value and the resolved browser request. A double-encoded percent sequence is a new mismatch, not evidence that encoding itself is wrong.
Acceptance from source to request
Use proposed cases containing a supported space, hash sign, percent sign, and non-ASCII character. Record the original local name, serialized reference, resolved URL, and downloaded output identity.
Verify that the returned body is the intended image. A successful status code can still deliver a fallback page or the wrong asset. Keep loading failures visible instead of substituting a different action silently.
This is a mechanism-derived diagnosis and test plan. No browser loader or server was executed for the example. URI correctness also does not settle platform filename compatibility; both contracts need checking when one package serves local engines and web previews.
Related workflow
See sprite assets case sensitive path export for the adjacent failure. Keep the animation handoff checklist with the package and record visual decisions in the art reference board.
Prepared by the FrameSprite Workflow Team. Editorial method · Corrections. Primary documentation checked 2026-10-20.
Top comments (0)