Improve webdirect-runtime skill discoverability - #302
Conversation
Description leads with blank/empty WebDirect symptoms + encoding keywords (UTF-8, Unicode, emoji, non-ASCII, deploy_html). Name deploy_html and common culprits in troubleshooting section.
🦋 Changeset detectedLatest commit: f9a562f The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
@proofkit/better-auth
@proofkit/fmdapi
@proofkit/fmodata
@proofkit/typegen
@proofkit/webviewer
commit: |
📝 WalkthroughWalkthroughThe WebDirect runtime skill now documents blank pages, corrupted HTML, encoding failures, ChangesWebDirect skill discoverability
Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/webviewer/skills/webdirect-runtime/SKILL.md`:
- Line 56: Update the character-encoding guidance in the WebDirect
troubleshooting section to identify malformed or misdecoded non-ASCII content as
the failure condition, rather than listing valid emoji, curly quotes, or
accented letters as inherently problematic. Mention invalid UTF-8 sequences
affecting those characters, while preserving the existing inspection, rebuild,
redeploy, and response-check steps.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 20732dac-ba0e-4d2c-83a4-19820832e3f7
📒 Files selected for processing (2)
.changeset/webdirect-skill-discoverability.mdpackages/webviewer/skills/webdirect-runtime/SKILL.md
| 4. Distinguish an empty WebDirect page response from an empty rendered root element inside the Web Viewer. React can start with an empty root and populate it at runtime, so the DOM alone doesn't prove that WebDirect omitted the bundle. | ||
|
|
||
| If the complete page served by WebDirect has an empty body and the Web Viewer bundle is absent from that response, suspect character encoding first. An incorrectly encoded or unsupported character in the deployed single-file HTML can cause WebDirect to return an empty body instead of sending the bundle. Inspect the built HTML for invalid UTF-8 or problematic characters, rebuild, redeploy, and check the full WebDirect response again. | ||
| If the complete page served by WebDirect has an empty body and the Web Viewer bundle is absent from that response, suspect character encoding first. An incorrectly encoded or unsupported character in the deployed single-file HTML — the payload the `deploy_html` FileMaker script writes into the file — can cause WebDirect to return an empty body instead of sending the bundle. Non-ASCII content such as emoji, curly quotes, accented letters, or invalid UTF-8 sequences is the usual source. Inspect the built HTML for invalid UTF-8 or problematic characters, rebuild, redeploy via `deploy_html`, and check the full WebDirect response again. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
sed -n '1,110p' packages/webviewer/skills/webdirect-runtime/SKILL.md
printf '\n--- deploy_html references ---\n'
rg -n -C 3 'deploy_html|encoding|UTF-8|empty body|WebDirect' packages/webviewerRepository: proofsh/proofkit
Length of output: 19230
🌐 Web query:
FileMaker WebDirect empty response body unsupported character UTF-8 HTML encoding deploy HTML
💡 Result:
In FileMaker WebDirect, issues involving empty response bodies or failing to load content in Web Viewers are often related to how HTML data URIs are constructed, character encoding, or specific reserved character strings. Key technical insights for troubleshooting: 1. Data URI Encoding Strategy: Historically, developers used Base64 encoding for HTML content in Web Viewers to avoid character conflict issues in WebDirect [1][2]. The pattern involves checking the application version and applying Base64 encoding only for WebDirect: Case ( PatternCount ( Get ( ApplicationVersion); "Web"); "data:text/html;base64," & Base64Encode ( YourHTMLField); "data:text/html," & YourHTMLField) [1]. However, note that as of FileMaker Server 21.1, the requirement to use Base64 encoding for Web Viewers has been removed, and using it may now be unnecessary or even detrimental to performance [3]. 2. Special Characters and Encoding: - Reserved Characters: If your HTML or URL contains characters like '#', it can break Web Viewer rendering in certain browsers [4][2]. A common workaround is to substitute '#' with its URL-encoded equivalent '%23' for WebDirect clients [2]. - URI Syntax: Including explicit character sets like 'charset=UTF-8' within a data URI (e.g., 'data:text/html;charset=UTF-8,...') can sometimes conflict with WebDirect's internal handling of the Web Viewer, leading to rendering failures [5]. - General URL Encoding: All URL parameters (database names, script names, script parameters) must be properly URL-encoded (e.g., space to '%20') [6][7][8]. Failing to encode special characters in these strings can lead to HTTP 500 errors or broken sessions [9]. 3. Blocked Strings: FileMaker WebDirect historically blocks specific strings in Web Viewer content. For example, the string '/fmi/webd' is restricted within Web Viewer HTML source because it conflicts with the WebDirect engine itself. If you must use such strings, developers have used workarounds like RFC 3986 encoding (e.g., '/fmi/web%64') to bypass these filters [10]. 4. Troubleshooting Checklist: - Verify that your FileMaker Server deployment is up to date, as many WebDirect rendering and encoding issues have been addressed in recent versions [11][3][6]. - Test your HTML content by stripping it down to the simplest possible version to isolate if specific characters or external resources (like CSS/JS libraries) are causing the failure [1]. - Check browser console logs for "FileMaker is undefined" errors, which often indicate that the Web Viewer failed to initialize correctly due to its content [5].
Citations:
- 1: https://www.soliantconsulting.com/blog/display-complex-webviewer-webdirect/
- 2: https://community.claris.com/en/s/question/0D50H00006ezaKpSAI/no-access-to-web-viewers-via-web-direct-on-chrome
- 3: https://the.fmsoup.org/t/change-in-how-fm-server-21-1-uses-web-viewers-within-webdirect/4473
- 4: https://community.claris.com/en/s/question/0D50H00006eza0mSAA/issue-with-webviewers-not-loading-via-webdirect
- 5: https://community.claris.com/en/s/question/0D53w0000580KXuCAM/server-v19-webdirect-filemakerperformscript-javascript-step-breaks-when-using-datatexthtmlcharsetutf8-uri-prefix
- 6: https://support.claris.com/s/article/Software-Update-FileMaker-Server-16-0-2-1503693099979
- 7: https://help.claris.com/archive/help/17/fms/en/FMS_Help/hostsite-fmwd.html
- 8: https://fmhelp.filemaker.com/fm19/en/webdirect-guide/
- 9: https://community.claris.com/en/s/question/0D53w000058uPafCAE/webdirect-redirect-link-is-invalid-after-login-http-error-500
- 10: https://community.claris.com/en/s/question/0D50H00006ezKTpSAM/bugreport-webdirect-blocking-webviewer-containing-specific-textstring
- 11: https://support.claris.com/s/article/Export-Field-Contents-in-FileMaker-WebDirect-results-in-a-zero-byte-file-1503693086795?language=en_US
🏁 Script executed:
printf '%s\n' '--- all deploy_html references ---'
rg -n -C 4 'deploy_html|Base64Encode|data:text/html|invalid UTF-8|misdecoded|unsupported character|non-ASCII' .
printf '%s\n' '--- UTF-8 validity of the reviewed document ---'
python3 - <<'PY'
from pathlib import Path
path = Path("packages/webviewer/skills/webdirect-runtime/SKILL.md")
data = path.read_bytes()
try:
text = data.decode("utf-8")
except UnicodeDecodeError as exc:
print(f"{path}: invalid UTF-8: {exc}")
else:
print(f"{path}: valid UTF-8, {len(text)} characters")
for term in ("emoji", "curly quotes", "accented letters", "invalid UTF-8 sequences"):
print(f"{term!r}: {term in text}")
PYRepository: proofsh/proofkit
Length of output: 12985
Limit the warning to malformed or misdecoded content.
Emoji, curly quotes, and accented letters are valid UTF-8 by themselves. State that malformed or misdecoded non-ASCII content is the failure condition, including invalid UTF-8 sequences affecting those characters.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/webviewer/skills/webdirect-runtime/SKILL.md` at line 56, Update the
character-encoding guidance in the WebDirect troubleshooting section to identify
malformed or misdecoded non-ASCII content as the failure condition, rather than
listing valid emoji, curly quotes, or accented letters as inherently
problematic. Mention invalid UTF-8 sequences affecting those characters, while
preserving the existing inspection, rebuild, redeploy, and response-check steps.
1 participant
Community report: an agent debugging a blank WebDirect app never found the
webdirect-runtimeskill's encoding guidance. Itsintent listoutput showed no skill title/description mentioning encoding, Unicode,deploy_html, or content corruption.The content existed (shipped in
@proofkit/webviewer@3.3.0, commit 7ba2d6d) but wasn't routable: "character encoding" sat last in a keyword blob, andUTF-8,Unicode,blank screen,corrupted,emoji,special characters, anddeploy_htmlappeared nowhere in the skill.Changes
generate-skillspec: leads with the symptom (blank/white/empty WebDirect app, empty page body, garbled/corrupted deployed HTML) and names UTF-8, Unicode, mojibake, emoji, accented, curly quote, non-ASCII,deploy_html. Refresh/state/bundle-size keywords retained, moved after.deploy_htmlas the script writing the single-file HTML payload, and lists the usual non-ASCII culprits.Changeset added (patch).
intent validatepasses;pnpm run cigreen.Summary by CodeRabbit
deploy_html-generated HTML responses and non-ASCII character problems.