Skip to content

Improve webdirect-runtime skill discoverability #302

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
eluce2 wants to merge 1 commit into
base: main
Choose a base branch
from
+16 −6
Open

Improve webdirect-runtime skill discoverability #302

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/webdirect-skill-discoverability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@proofkit/webviewer": patch
---

Make webdirect-runtime skill discoverable for encoding/blank-app issues: description now leads with blank/empty WebDirect page and character encoding (UTF-8, Unicode, emoji, special characters, deploy_html) keywords; troubleshooting section names `deploy_html` and common non-ASCII culprits.
17 changes: 11 additions & 6 deletions packages/webviewer/skills/webdirect-runtime/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,16 @@
---
name: webdirect-runtime
description: >
FileMaker WebDirect ProofKit Web Viewer runtime behavior refresh resilience
session state localStorage browser resize reload same deployment embedded bundle
avoid separate deployment avoid separate web server @proofkit/webviewer
fmFetch callFMScript WebViewerAdapter WebDirect page refresh blank app empty body
character encoding browser network response console errors deployed HTML
Troubleshoot and build FileMaker WebDirect ProofKit Web Viewer apps. Load when a Web Viewer
app is blank, white, or empty in WebDirect, when the WebDirect page response has an empty
body, when deployed HTML is garbled, mangled, or corrupted, or when diagnosing character
encoding, UTF-8, Unicode, mojibake, emoji, accented, curly quote, or other special or
non-ASCII characters in the single-file HTML written by the deploy_html FileMaker script.
Also covers refresh resilience, unexpected page reload from browser resize, session state
in localStorage, bundle size and page-weight myths, running the same embedded bundle in
WebDirect and FileMaker Pro without a separate deployment or web server, and browser
console and network diagnosis with @proofkit/webviewer fmFetch callFMScript
WebViewerAdapter.
metadata:
type: core
library: proofkit
Expand Down Expand Up @@ -48,7 +53,7 @@ When a web app doesn't load in WebDirect, inspect what the browser received befo
3. Check the browser console for parse errors, runtime exceptions, blocked resources, or security errors.
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.

@coderabbitai coderabbitai Bot Aug 12, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 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/webviewer

Repository: 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:

🏁 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}")
PY

Repository: 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.


If the full WebDirect response contains the Web Viewer HTML and JavaScript bundle, don't keep treating encoding or bundle size as the default cause. Follow the browser's console and network evidence to the parse, runtime, bridge, or security failure.

Expand Down
Loading