feat(assistant): optimize MCP and custom widget authoring (#6743)

* feat(assistant): optimize MCP and custom widget authoring

* fix(assistant): isolate server-safe JSX analyzer

* refactor(assistant): generate MCP tool staging

* fix(assistant): preserve widget placement follow-up

* fix(ci): allow fast gate to finish

* fix(custom-widgets): address review findings

* fix(custom-widgets): split preview evidence module

* style: format assistant custom widget files

* fix(custom-widgets): sync formatted skill schema
This commit is contained in:
Thomas authored and GitHub committed 2026-08-30 23:43:29 +02:00
1 parent 38f4b0e1f8
commit 5e23659d99
95 files changed
+6799 -1778

No files matched your search

File diff suppressed because it is too large. Load diff
@@ -11,6 +11,8 @@ import {
getAiProviderChatCompletionsUrl,
getDeterministicEvaluationIssues,
getEvaluationResponseFixtureText,
getExpectedWidgetCase,
getAiEvaluationMaxOutputTokens,
getJudgeResponseFormat,
judgePasses,
parseJudgeResult,
@@ -52,9 +54,15 @@ const makeJudgeResult = (score: number) => ({
});
describe("AI authoring evaluation", () => {
it("allows bounded output reservations for low-credit live judges without changing defaults", () => {
expect(getAiEvaluationMaxOutputTokens("judge", undefined)).toBe(8_000);
expect(getAiEvaluationMaxOutputTokens("judge", "3000")).toBe(3_000);
expect(getAiEvaluationMaxOutputTokens("generation", "1000")).toBe(4_096);
expect(getAiEvaluationMaxOutputTokens("generation", "invalid")).toBe(20_000);
});
it("defines distinct complex and public-API scenarios", () => {
expect(CUSTOM_WIDGET_AI_EVALUATION_CASES).toHaveLength(9);
expect(new Set(CUSTOM_WIDGET_AI_EVALUATION_CASES.map((entry) => entry.id)).size).toBe(9);
expect(CUSTOM_WIDGET_AI_EVALUATION_CASES).toHaveLength(10);
expect(new Set(CUSTOM_WIDGET_AI_EVALUATION_CASES.map((entry) => entry.id)).size).toBe(10);
expect(CUSTOM_WIDGET_AI_EVALUATION_CASES.map(({ id }) => id)).toEqual(
expect.arrayContaining([
"pokedex",
@@ -62,8 +70,100 @@ describe("AI authoring evaluation", () => {
"coinmarketcap-keyless",
"bored-activity",
"agify-name",
"seerr-media-workflows",
]),
);
const advancedCase = CUSTOM_WIDGET_AI_EVALUATION_CASES.find(({ id }) => id === "seerr-media-workflows");
expect(advancedCase?.expectedWidgets?.every(({ expectations }) => !("maximumRequests" in expectations))).toBe(true);
expect(advancedCase?.research).toMatchObject({
requiredReferences: ["schema", "runtime", "security"],
allowedReferences: ["schema", "runtime", "security"],
});
expect(advancedCase?.request).toContain("voteAverage");
expect(advancedCase?.request).toContain("functional pagination");
expect(advancedCase?.request).toContain("responsive SimpleGrid");
expect(advancedCase?.request).toContain("createdAt");
expect(advancedCase?.request).toContain("prefers backdropPath");
expect(advancedCase?.request).toContain("approve and decline");
expect(advancedCase?.request).toContain("TMDB 603 · Request #91");
expect(advancedCase?.request).toContain("Rating label only when voteAverage is present");
expect(advancedCase?.request).toContain("without redundant outer or per-item chrome");
expect(advancedCase?.request).toContain("relies on native loading/error/retry");
expect(advancedCase?.request).toContain("query/page/total-results summary");
expect(advancedCase?.request).toContain("Not provided");
expect(advancedCase?.request).toContain("Media profile");
expect(advancedCase?.request).toContain("when only its sibling request fails");
expect(advancedCase?.request).toContain("compact thumbnail beside content at base");
expect(advancedCase?.request).toContain("Avatar imageProps.alt");
expect(advancedCase?.request).toContain("Pagination only when totalPages is greater than 1");
expect(advancedCase?.apiNotes).toContain("render the array at response.results");
expect(advancedCase?.apiNotes).toContain("/request/{param:requestId}/approve");
const operationsExpectations = advancedCase?.expectedWidgets?.find(
({ id }) => id === "request-operations",
)?.expectations;
expect(operationsExpectations?.requests).toEqual(
expect.arrayContaining([
expect.objectContaining({ kind: "query", requiresStatusBinding: true }),
expect.objectContaining({ kind: "action", pathIncludes: "/request/{param:requestId}/approve" }),
expect.objectContaining({ kind: "action", pathIncludes: "/request/{param:requestId}/decline" }),
]),
);
expect(operationsExpectations?.templateIncludes).toEqual(
expect.arrayContaining([
"processing",
"declined",
"tmdbId",
"status4k",
"Failed",
"Completed",
"Not provided",
"imageProps",
]),
);
expect(operationsExpectations?.templateIncludesAny).toEqual(
expect.arrayContaining([
["TMDB", "Tmdb"],
["Request #", "Request ID"],
["UTC", "utc"],
]),
);
const mediaExpectations = advancedCase?.expectedWidgets?.find(({ id }) => id === "media-research")?.expectations;
expect(mediaExpectations?.templateIncludes).toEqual(
expect.arrayContaining([
".results",
"backdropPath",
"https://image.tmdb.org/t/p/",
"w780",
"inputs.page ?? 1",
"status4k",
'trigger="manual"',
"lineClamp",
]),
);
expect(mediaExpectations?.templateIncludesAny).not.toContainEqual(["SimpleGrid", "Grid"]);
expect(mediaExpectations?.templateIncludesAny).toContainEqual(["Rating", "★", "/10"]);
expect(mediaExpectations?.templateIncludesAny).toContainEqual(["Partially Available", "Partially available"]);
});
it("scopes multi-widget judging to each requested capability and its exact fixtures", () => {
const testCase = CUSTOM_WIDGET_AI_EVALUATION_CASES.find(({ id }) => id === "seerr-media-workflows");
const expectedWidgets = testCase?.expectedWidgets;
if (!testCase || !expectedWidgets) throw new Error("Advanced Seerr expectations are missing");
const expectedOperations = expectedWidgets.find(({ id }) => id === "request-operations");
const expectedResearch = expectedWidgets.find(({ id }) => id === "media-research");
if (!expectedOperations || !expectedResearch) throw new Error("Scoped Seerr expectations are missing");
const operations = getExpectedWidgetCase(testCase, expectedOperations);
const research = getExpectedWidgetCase(testCase, expectedResearch);
expect(operations.apiNotes).not.toContain("GET /search");
expect(operations.previewResponses?.map(({ pathIncludes }) => pathIncludes)).toEqual([
"/request/count",
"/request",
"/request/{param:requestId}/approve",
"/request/{param:requestId}/decline",
]);
expect(research.apiNotes).not.toContain("GET /request/count");
expect(research.previewResponses?.map(({ pathIncludes }) => pathIncludes)).toEqual(["/search", "/request"]);
});
it("grounds fixture-backed scenarios in verified routes and authentication", () => {
@@ -141,6 +241,246 @@ describe("AI authoring evaluation", () => {
requests: { prices: { ...widget.requests.prices, query: { id: "1,1027", convert: "USD" } } },
}),
).toContainEqual(expect.objectContaining({ path: ["requests"] }));
expect(
getDeterministicEvaluationIssues(testCase, {
...widget,
requests: {
prices: {
...widget.requests.prices,
query: { id: { $option: "symbols" }, convert: "USD" },
},
},
options: {
symbols: { label: "Symbols", control: "text", default: "1,1027,5426" },
},
}),
).toEqual([]);
});
it("accepts equivalent empty-state wording from an allowed semantic group", () => {
const baseCase = CUSTOM_WIDGET_AI_EVALUATION_CASES.find(({ id }) => id === "fake-service-health");
if (!baseCase?.expectations) throw new Error("Fake service-health expectations are missing");
const testCase = {
...baseCase,
expectations: {
...baseCase.expectations,
templateIncludesAny: [["No matching services", "No services found", "Nothing to show"]],
},
};
const widget = {
$schema: "homarr-custom-widget-v2" as const,
name: "Health",
sources: {
default: { baseUrl: "https://status.example.test", networkScope: "public" as const, auth: "none" as const },
},
requests: {
health: {
source: "default",
kind: "query" as const,
method: "GET" as const,
path: "/v1/health",
trigger: "load" as const,
auth: "inherit" as const,
permission: "view" as const,
},
},
options: {},
template:
"<Stack><RefreshButton /><Text>status openIncidents latencyMs checkedAt services</Text><Text>No services found</Text></Stack>",
};
expect(getDeterministicEvaluationIssues(testCase, widget)).toEqual([]);
expect(
getDeterministicEvaluationIssues(testCase, {
...widget,
template: widget.template.replace("No services found", "All services loaded"),
}),
).toContainEqual(expect.objectContaining({ path: ["template"] }));
});
it("rejects a wrapped response rendered as an array and unwired pagination", () => {
const testCase = CUSTOM_WIDGET_AI_EVALUATION_CASES.find(({ id }) => id === "seerr-media-workflows");
if (!testCase?.expectedWidgets) throw new Error("Advanced Seerr expectations are missing");
const mediaCase = {
...testCase,
expectations: testCase.expectedWidgets.find(({ id }) => id === "media-research")?.expectations,
expectedWidgets: undefined,
};
const operationsCase = {
...testCase,
expectations: testCase.expectedWidgets.find(({ id }) => id === "request-operations")?.expectations,
expectedWidgets: undefined,
};
const validMedia = {
$schema: "homarr-custom-widget-v2" as const,
name: "Seerr research",
sources: {
default: {
baseUrl: "http://seerr.local:5055/api/v1",
networkScope: "private" as const,
auth: { type: "apiKeyHeader" as const, name: "X-Api-Key" },
},
},
requests: {
search: {
source: "default",
kind: "query" as const,
method: "GET" as const,
path: "/search",
trigger: "manual" as const,
query: { query: { $param: "query" }, page: { $param: "page" } },
auth: "inherit" as const,
permission: "view" as const,
},
requestMovie: {
source: "default",
kind: "action" as const,
method: "POST" as const,
path: "/request",
trigger: "manual" as const,
body: { mediaType: "movie", mediaId: { $param: "id" } },
auth: "inherit" as const,
permission: "modify" as const,
confirmation: "Request movie?",
invalidates: ["search"],
},
requestSeries: {
source: "default",
kind: "action" as const,
method: "POST" as const,
path: "/request",
trigger: "manual" as const,
body: { mediaType: "tv", mediaId: { $param: "id" }, seasons: "all" },
auth: "inherit" as const,
permission: "modify" as const,
confirmation: "Request series?",
invalidates: ["search"],
},
},
options: {},
template:
'<Stack><TextInput bind="query" /><SubFetch requestId="search" trigger="manual" params={{ query: inputs.query, page: inputs.page ?? 1 }}>{(response) => <Stack><Group><Text>{response.totalResults}</Text><RefreshButton requestId="search" label="Run again" /></Group><SimpleGrid>{response.results.map(item => <Stack key={item.id}><Image src={`https://image.tmdb.org/t/p/w780${item.backdropPath ?? item.posterPath}`} alt={item.title} /><Text lineClamp={2}>{item.overview}</Text></Stack>)}</SimpleGrid><Pagination bind="page" defaultValue={1} resetKey={inputs.query} total={response.totalPages} /></Stack>}</SubFetch><Text>overview voteAverage ★ mediaInfo status4k Unknown Pending Processing Partially available Available Blocklisted Deleted No results</Text><ActionButton requestId="requestMovie" /><ActionButton requestId="requestSeries" /></Stack>'.repeat(
4,
),
};
const brokenMedia = {
...validMedia,
template: validMedia.template.replaceAll("response.results", "response"),
};
expect(getDeterministicEvaluationIssues(mediaCase, validMedia)).toEqual([]);
const missingSearchInvalidation = {
...validMedia,
requests: {
...validMedia.requests,
requestMovie: { ...validMedia.requests.requestMovie, invalidates: [] },
},
};
expect(getDeterministicEvaluationIssues(mediaCase, missingSearchInvalidation)).toContainEqual(
expect.objectContaining({
path: ["requests"],
message: expect.stringMatching(/invalidates.*\/search/u),
}),
);
const actionIssue = getDeterministicEvaluationIssues(mediaCase, missingSearchInvalidation).find(
(issue) => issue.path?.[0] === "requests",
);
expect(actionIssue?.message).toContain('mediaType="movie" or any $param binding');
expect(actionIssue?.message).not.toContain('["movie","$param:*"]');
const boundActionValues = {
...validMedia,
requests: {
...validMedia.requests,
requestMovie: {
...validMedia.requests.requestMovie,
body: { mediaType: { $param: "mediaType" }, mediaId: { $param: "id" } },
},
requestSeries: {
...validMedia.requests.requestSeries,
body: {
mediaType: { $param: "mediaType" },
mediaId: { $param: "id" },
seasons: { $param: "seasons" },
},
},
},
};
expect(getDeterministicEvaluationIssues(mediaCase, boundActionValues)).toEqual([]);
expect(
getDeterministicEvaluationIssues(mediaCase, {
...boundActionValues,
requests: {
...boundActionValues.requests,
requestSeries: { ...boundActionValues.requests.requestSeries, body: { mediaType: "tv" } },
},
}),
).toContainEqual(expect.objectContaining({ path: ["requests"] }));
expect(getDeterministicEvaluationIssues(mediaCase, brokenMedia)).toContainEqual(
expect.objectContaining({ message: expect.stringContaining("'.results'") }),
);
const operationsWidget = {
$schema: "homarr-custom-widget-v2" as const,
name: "Seerr operations",
sources: validMedia.sources,
requests: {
counts: {
source: "default",
kind: "query" as const,
method: "GET" as const,
path: "/request/count",
trigger: "load" as const,
auth: "inherit" as const,
permission: "view" as const,
},
recent: {
source: "default",
kind: "query" as const,
method: "GET" as const,
path: "/request",
trigger: "load" as const,
query: { take: 10, skip: 0, sort: "added", sortDirection: "desc" },
auth: "inherit" as const,
permission: "view" as const,
},
approvePending: {
source: "default",
kind: "action" as const,
method: "POST" as const,
path: "/request/{param:requestId}/approve",
trigger: "manual" as const,
auth: "inherit" as const,
permission: "modify" as const,
confirmation: "Approve request?",
invalidates: ["counts", "recent"],
},
declinePending: {
source: "default",
kind: "action" as const,
method: "POST" as const,
path: "/request/{param:requestId}/decline",
trigger: "manual" as const,
auth: "inherit" as const,
permission: "modify" as const,
confirmation: "Decline request?",
invalidates: ["counts", "recent"],
},
},
options: {},
template:
'<Stack><RefreshButton /><SimpleGrid><Text>pending approved available processing declined status.</Text></SimpleGrid><Text>{status.counts.loading} {status.recent.error} {data.recent.results} {data.recent.pageInfo} {data.recent.createdAt} UTC TMDB {data.recent.tmdbId} {data.recent.mediaType} {data.recent.status4k} Request #</Text><ActionButton requestId="approvePending" /><ActionButton requestId="declinePending" /><Pagination total={5} /></Stack>'.repeat(
8,
),
};
const operationIssues = getDeterministicEvaluationIssues(operationsCase, operationsWidget);
expect(operationIssues.filter((issue) => issue.path?.[0] === "requests")).toEqual([]);
expect(operationIssues).toContainEqual(expect.objectContaining({ message: expect.stringContaining("Pagination") }));
expect(
getDeterministicEvaluationIssues(operationsCase, {
...operationsWidget,
template: operationsWidget.template.replaceAll("status.counts", "status").replaceAll("status.recent", "status"),
}),
).toContainEqual(expect.objectContaining({ message: expect.stringContaining("no global status.loading") }));
});
it("includes every path-specific Pokédex fixture in generator and judge context", () => {
@@ -278,20 +618,22 @@ describe("AI authoring evaluation", () => {
expect(prompt).toContain("status.<requestId> with loading/ok/status/error fields");
expect(prompt).toContain("RefreshButton is an installed runtime helper");
expect(prompt).toContain("cannot display stale results under edited inputs");
expect(prompt).toContain("do not penalize a repeated short literal label array");
expect(prompt).toContain(JSON.stringify(testCase.sampleResponse, null, 2));
expect(prompt).toContain("# Bundled file: references/runtime.md");
expect(prompt).toContain("# Runtime");
expect(prompt).not.toContain("# Bundled file:");
expect(prompt).toContain("does not prove API correctness, visual quality, usefulness, or accessibility");
expect(prompt).toContain(
"verified API notes and representative response fixtures are authoritative for endpoint paths, authentication requirements, and response shapes",
);
expect(prompt).toContain("Do not invent external endpoint or authentication objections from outside assumptions");
expect(prompt).toContain("an endpoint mentioned in broader API notes is available, not automatically required");
expect(prompt).toContain(
"Decorative icons paired with equivalent adjacent visible status text need no separate aria-label",
);
expect(prompt).toContain("A Badge containing explicit visible status text is not color-only");
expect(prompt).toContain(
"A readable absolute UTC date and time is valid; do not require relative or localized time without a documented safe helper",
);
expect(prompt).toContain('Date.toLocaleString(value, "en-US", "UTC") is an installed safe static helper');
expect(prompt).toContain(
'A pass requires a weighted total of at least 85, every category at least 75, goalFulfillment at least 85, complexityDiscipline at least 80, no fatal problem, and dailyUseDecision="would-use-daily"',
);
@@ -322,7 +664,10 @@ describe("AI authoring evaluation", () => {
it("normalizes a prose 'none' entry out of an otherwise empty fatal-problem list", () => {
const parsed = parseJudgeResult(
JSON.stringify({ ...makeJudgeResult(90), fatalProblems: ["None: all requested capabilities are present."] }),
JSON.stringify({
...makeJudgeResult(90),
fatalProblems: ["None: all requested capabilities are present.", "No fatal issues."],
}),
);
expect(parsed.fatalProblems).toEqual([]);
expect(parsed.verdict).toBe("pass");
@@ -3,7 +3,9 @@ import { describe, expect, it } from "vitest";
import {
buildCustomWidgetAiPrompt,
buildCustomWidgetMcpPrompt,
CUSTOM_WIDGET_ASSISTANT_POLICY,
CUSTOM_WIDGET_FINAL_OUTPUT_INSTRUCTION,
CUSTOM_WIDGET_TOOL_STAGING_INSTRUCTION,
CUSTOM_WIDGET_MCP_AUTHORING_PROMPT,
} from "../core/ai-prompt";
@@ -43,58 +45,85 @@ describe("AI prompt", () => {
expect(prompt.match(/Recommended components:/gu)).toHaveLength(1);
});
it("makes the connected MCP workflow load the complete skill and test every preview query", () => {
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("First call customWidget_getSkill");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("customWidget_validate");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("customWidget_previewCreate");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("customWidget_previewQuery once for every query");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("customWidget_createFromPreview");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("customWidget_getSharedProps");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("at most eight named component documents");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("at most four after loading a complete example");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("Treat preview data as the binding contract");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("Make initial states actionable");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("Label standalone icons");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("Prefer templateLines");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("Make one documentation tool call at a time");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("Never issue batched customWidget_getComponent calls");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain(
"choose at most four component names total and never request a fifth",
it("makes the connected MCP workflow lazy, batch-capable, and evidence-driven", () => {
expect(CUSTOM_WIDGET_ASSISTANT_POLICY.length).toBeLessThan(4_000);
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT.length).toBeLessThan(4_500);
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("Start with customWidget_getSkill");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("one focused component search per widget job");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("Lifecycle tools run one at a time");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("change the active phase");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("customWidget_getComponents");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("Do not load the full catalog");
expect(CUSTOM_WIDGET_TOOL_STAGING_INSTRUCTION).toContain("staged by the authoring lifecycle");
expect(CUSTOM_WIDGET_TOOL_STAGING_INSTRUCTION).toContain("task-needed");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("Reuse loaded context");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("no arbitrary documentation or creativity cap");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("one focused component search per widget job");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("presentation components exist");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("Load the compact schema reference once for a new manifest");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("skip it for a supplied valid v2 draft");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("validate one response-driven correction");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("customWidget_previewReviseTemplate");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("it inherits the manifest and resets evidence");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain(
"fresh previewCreate only when sources, requests, or options change",
);
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain(
"reject IIFEs, new, block callbacks or => {, and raw HTML tags such as span",
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("Do not reopen discovery or add optional polish");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("byte-identical template");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("coordinated set");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("research primary API documentation once");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("Before previewing any authenticated source or mutation");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("security reference exactly once");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("SubFetch");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain('<SubFetch trigger="manual">');
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain('<RefreshButton requestId="x">');
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("SubFetch owns loading/error/retry");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("literal inherited requestId");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("RefreshButton");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("load queries");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("Fixed query/body values stay primitives");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("load queries never contain $param");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("resetKey={inputs.query}");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("defaultValue={1}");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("ActionButton");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("ToggleSwitch");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("Do not simplify because JSX is interpreted");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("choicesFrom");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("charts");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("multiple sources");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("customWidget_validateTemplate");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("queries and actions that need evidence");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("every relevant simulated action");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("byte-identical template");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("customWidget_createFromPreview");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("reserved roots");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("one JSX expression");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("statement-bodied callbacks");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("Fix unknown-prop warnings before preview");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("IconFoo");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("exact response envelope");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("Never map the envelope as an array");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("indexed literal label arrays");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("Wire every stateful control");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("remove dead controls");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("keep sibling request data/errors independent");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("preserve field meaning");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("documented Date helpers");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("Base artwork fills its row");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("responsive media grid");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("one summary of responsive metrics");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).toContain("One primary badge");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).not.toContain("Example —");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY).not.toContain("Recommended components:");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).not.toContain("homarr_findTools");
expect(CUSTOM_WIDGET_ASSISTANT_POLICY.indexOf("customWidget_validateTemplate")).toBeLessThan(
CUSTOM_WIDGET_ASSISTANT_POLICY.indexOf("customWidget_previewCreate"),
);
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("concise human-readable absolute dates and times");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain(
"do not compute relative time with Date, Date.now, or Date.parse unless the live docs provide a safe helper",
expect(CUSTOM_WIDGET_ASSISTANT_POLICY.indexOf("customWidget_previewCreate")).toBeLessThan(
CUSTOM_WIDGET_ASSISTANT_POLICY.indexOf("customWidget_previewReviseTemplate"),
);
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("one restrained accent for decorative chrome");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain(
"operational, degraded, and down states retain distinct semantic colors",
);
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("Do not wrap every metric or service row in Paper or Card");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain("one dominant surface with clearly separated service rows");
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain(
"a one-column compact narrow layout, and an intentionally more spacious wide layout",
);
const orderedSteps = [
"1. First call customWidget_getSkill",
"2. Call customWidget_schema",
"3. If a complete example is useful, call customWidget_getExample before any customWidget_getComponent call",
"4. Before validation",
"5. Call customWidget_previewCreate",
"6. Call customWidget_previewQuery once for every query",
"7. Call customWidget_createFromPreview",
];
for (const [index, step] of orderedSteps.entries()) {
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT).toContain(step);
if (index === 0) continue;
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT.indexOf(orderedSteps[index - 1] ?? "")).toBeLessThan(
CUSTOM_WIDGET_MCP_AUTHORING_PROMPT.indexOf(step),
);
}
expect(CUSTOM_WIDGET_MCP_AUTHORING_PROMPT.indexOf("customWidget_previewQuery")).toBeLessThan(
CUSTOM_WIDGET_MCP_AUTHORING_PROMPT.indexOf("customWidget_create"),
expect(CUSTOM_WIDGET_ASSISTANT_POLICY.indexOf("customWidget_previewReviseTemplate")).toBeLessThan(
CUSTOM_WIDGET_ASSISTANT_POLICY.indexOf("customWidget_createFromPreview"),
);
const prompt = buildCustomWidgetMcpPrompt(
@@ -3,12 +3,17 @@ import path from "node:path";
import { describe, expect, it } from "vitest";
import {
findCustomWidgetComponents,
getCustomWidgetComponent,
getCustomWidgetComponentCatalog,
getCustomWidgetComponents,
getCustomWidgetContextRequestKey,
getCustomWidgetExample,
getCustomWidgetSharedProps,
getCustomWidgetSkill,
getCustomWidgetSkillContent,
getCustomWidgetSkillEntrypoint,
getCustomWidgetSkillReference,
} from "../core/authoring-resources";
import { validateCustomJsxTemplate } from "../jsx/analyzer";
@@ -17,7 +22,7 @@ const skillSourceDirectory = path.resolve(import.meta.dirname, "../../../../.age
describe("authoring resources", () => {
it("returns the complete portable skill and keeps every bundled source file in sync", () => {
const skill = getCustomWidgetSkill();
expect(skill).toMatchObject({ name: "homarr-custom-widget", version: "2.3.0" });
expect(skill).toMatchObject({ name: "homarr-custom-widget", version: "2.9.0" });
expect(skill.skillsShUrl).toContain("skills.sh/homarr-labs/homarr");
expect(skill.sourceUrl).toContain("/tree/HEAD/.agents/skills/homarr-custom-widget");
expect(skill.installCommand).toContain("--skill homarr-custom-widget");
@@ -32,11 +37,54 @@ describe("authoring resources", () => {
expect(bundledContent).toContain(content.trim());
}
expect(bundledContent).toContain(skill.skillMd.trim());
expect(bundledContent).toContain("at most eight named component documents");
expect(bundledContent).toContain("at most four after loading a complete example");
expect(bundledContent).toContain("successful preview response as the binding contract");
expect(bundledContent).toContain("coordinated set of widgets");
expect(bundledContent).toContain("customWidget_validateTemplate");
expect(bundledContent).toContain("customWidget_findComponents");
expect(bundledContent).toContain("Batch selected non-obvious binding or interaction documentation");
expect(bundledContent).not.toContain("at most eight named component documents");
expect(bundledContent).toContain("Do not use an unlabeled decorative icon as an empty state");
expect(Buffer.byteLength(JSON.stringify(skill), "utf8")).toBeLessThan(12_000);
const entrypoint = getCustomWidgetSkillEntrypoint();
expect(entrypoint.references).toEqual(
expect.arrayContaining([expect.objectContaining({ name: "runtime", tool: "customWidget_getReference" })]),
);
expect(JSON.stringify(entrypoint)).not.toContain("# Runtime");
expect(entrypoint.skillMd).toContain("Context routing");
expect(entrypoint.skillMd).toContain("customWidget_validateTemplate");
expect(entrypoint.skillMd).toContain("customWidget_previewReviseTemplate");
expect(entrypoint.skillMd).toContain("map every requested capability");
expect(entrypoint.skillMd).toContain("purpose-specific visual signature");
expect(entrypoint.skillMd).toContain("asymmetric priority metric/action");
expect(entrypoint.skillMd).toContain("new manifest");
expect(entrypoint.skillMd).not.toContain("To install an existing widget");
expect(getCustomWidgetSkillReference("runtime").content).toContain("SubFetch");
expect(getCustomWidgetSkillReference("runtime").content).toContain(
'require `trigger: "manual"` on request and `SubFetch`',
);
expect(getCustomWidgetSkillReference("runtime").content).toContain("RefreshButton");
expect(getCustomWidgetSkillReference("runtime").content).toContain("owns loading/error/retry");
expect(getCustomWidgetSkillReference("runtime").content).toContain("need literal `requestId`");
expect(getCustomWidgetSkillReference("runtime").content).toContain('requestId="search" label="Run again"');
expect(getCustomWidgetSkillReference("runtime").content).toContain("Render load queries directly");
expect(getCustomWidgetSkillReference("runtime").content).toContain("entire JSON response");
expect(getCustomWidgetSkillReference("runtime").content).toContain("never map the envelope itself");
expect(getCustomWidgetSkillReference("runtime").content).toContain("immediately hides its prior result");
expect(getCustomWidgetSkillReference("runtime").content).toContain("Every stateful control must use `bind`");
expect(getCustomWidgetSkillReference("runtime").content).toContain("resetKey={inputs.search}");
expect(getCustomWidgetSkillReference("runtime").content).toContain('Date.toLocaleString(value, "en-US", "UTC")');
expect(getCustomWidgetSkillReference("runtime").content).toContain("Never invent a formatter component");
const schemaReference = getCustomWidgetSkillReference("schema").content;
expect(schemaReference).toContain('"default": {');
expect(schemaReference).toContain('"trigger": "manual"');
expect(schemaReference).toContain('"kind": "action"');
expect(schemaReference).toContain('"apiKeyHeader"');
expect(schemaReference).toContain("is the required source ID");
expect(Buffer.byteLength(schemaReference, "utf8")).toBeLessThan(4_000);
expect(Buffer.byteLength(JSON.stringify(entrypoint), "utf8")).toBeLessThan(3_000);
expect(Buffer.byteLength(JSON.stringify(entrypoint), "utf8")).toBeLessThan(
Buffer.byteLength(JSON.stringify(skill), "utf8") / 3,
);
});
it("keeps catalog discovery compact and component details lazy", () => {
@@ -87,6 +135,55 @@ describe("authoring resources", () => {
expect(largestComponentPayload).toBeLessThan(20_000);
});
it("finds a focused component subset without sending the full catalog", () => {
const result = findCustomWidgetComponents("TextInput SubFetch Image Card ActionButton", 12);
const oversizedRequest = findCustomWidgetComponents("layout input action chart image status", 40);
expect(result.components.map(({ name }) => name)).toEqual(
expect.arrayContaining(["TextInput", "SubFetch", "Image", "Card", "ActionButton"]),
);
expect(result.components).toHaveLength(12);
expect(result.nextStep).toContain("customWidget_getComponent");
expect(Buffer.byteLength(JSON.stringify(result), "utf8")).toBeLessThan(6_000);
expect(Buffer.byteLength(JSON.stringify(result), "utf8")).toBeLessThan(
Buffer.byteLength(JSON.stringify(getCustomWidgetComponentCatalog()), "utf8") / 5,
);
expect(oversizedRequest.components.length).toBeLessThanOrEqual(16);
});
it("batches selected component documentation without limiting the complete library", () => {
const result = getCustomWidgetComponents([
"SubFetch",
"ActionButton",
"TextInput",
"Pagination",
"SubFetch",
"Missing",
]);
expect(result.components.map(({ name }) => name)).toEqual(["SubFetch", "ActionButton", "TextInput", "Pagination"]);
expect(result.components.find(({ name }) => name === "SubFetch")).toHaveProperty("props");
expect(result.components.find(({ name }) => name === "TextInput")).toMatchObject({
bind: { type: "string", initialProp: "defaultValue", resetProp: "resetKey" },
propNames: expect.arrayContaining(["label", "description"]),
fullDetailsTool: "customWidget_getComponent",
});
expect(result.components.find(({ name }) => name === "TextInput")).not.toHaveProperty("props");
expect(result.notFound).toEqual(["Missing"]);
expect(result.nextStep).toContain("template validation");
expect(Buffer.byteLength(JSON.stringify(result), "utf8")).toBeLessThan(10_000);
});
it("identifies duplicate reloadable context requests independent of name order", () => {
expect(getCustomWidgetContextRequestKey("customWidget_getReference", { name: "schema" })).toBe(
'customWidget_getReference:{"name":"schema"}',
);
expect(getCustomWidgetContextRequestKey("customWidget_getComponents", { names: ["Text", "Badge", "Text"] })).toBe(
getCustomWidgetContextRequestKey("customWidget_getComponents", { names: ["Badge", "Text"] }),
);
expect(getCustomWidgetContextRequestKey("customWidget_previewCreate", { definition: {} })).toBeNull();
});
it("returns only requested shared prop documentation in one bounded payload", () => {
const result = getCustomWidgetSharedProps(["p", "m", "not-a-shared-prop", "p"]);
expect(result.props.map(({ name }) => name)).toEqual(["p", "m"]);
@@ -86,10 +86,17 @@ describe("Custom JSX authoring catalog", () => {
expect(label && getCustomJsxPropType(label)).toContain("ReactNode");
expect(label?.required).toBe(false);
expect(label?.description).toBeTruthy();
expect(textInput?.bind).toEqual({ type: "string", initialProp: "defaultValue" });
expect(textInput?.bind).toEqual({ type: "string", initialProp: "defaultValue", resetProp: "resetKey" });
const switchComponent = customJsxAuthoringCatalog.components.find(({ name }) => name === "Switch");
expect(switchComponent?.bind).toEqual({ type: "boolean", initialProp: "defaultChecked" });
expect(switchComponent?.bind).toEqual({
type: "boolean",
initialProp: "defaultChecked",
resetProp: "resetKey",
});
const refreshButton = customJsxAuthoringCatalog.components.find(({ name }) => name === "RefreshButton");
expect(refreshButton?.props).toEqual(expect.arrayContaining([expect.objectContaining({ name: "requestId" })]));
expect(customJsxAuthoringCatalog.components.some(({ name }) => name === "RecursiveList")).toBe(false);
@@ -249,6 +249,13 @@ describe("customJsxComponentRegistry", () => {
expect(getCustomJsxBindingType(component)).toBe(type);
});
test("advertises resetKey only for declaratively bindable controls", () => {
expect(customJsxComponentByName.get("Pagination")?.supportedProps).toEqual(
expect.arrayContaining(["bind", "resetKey"]),
);
expect(customJsxComponentByName.get("Text")?.supportedProps).not.toContain("resetKey");
});
test("infers range and multiple date controls from their authored props", () => {
for (const component of [
"DatePicker",
@@ -67,6 +67,22 @@ describe("shared Custom JSX policy", () => {
expect(validateCustomJsxTemplate('<Text>{"b".localeCompare("a")}</Text>')).toEqual([]);
});
test("formats an absolute date and time in an explicit safe timezone", () => {
const template = '<Text>{Date.toLocaleString(data.createdAt, "en-US", "UTC")} UTC</Text>';
expect(validateCustomJsxTemplate(template)).toEqual([]);
const rendered = renderSafeJsx({
template,
components: {
Text: ((props: { children?: unknown }) => createElement("span", null, props.children as never)) as never,
},
bindings: createCustomJsxBindings({ createdAt: "2026-08-28T19:22:00.000Z" }),
});
const html = renderToStaticMarkup(rendered.node);
expect(html).toContain("Aug 28, 2026");
expect(html).toContain("7:22 PM UTC");
});
test.each([...CUSTOM_JSX_BLOCKED_PROPERTIES])(
"blocks reflective property %s in diagnostics and runtime",
(property) => {
@@ -257,6 +273,41 @@ describe("shared Custom JSX policy", () => {
).toBe(false);
});
test.each(["SubFetch", "ActionButton", "ToggleSwitch"])(
"requires a literal requestId on %s during independent JSX validation",
(component) => {
expect(validateCustomJsxTemplate(`<${component} requestId="known" />`)).toEqual([]);
for (const template of [`<${component} />`, `<${component} requestId={data.requestId} />`]) {
expect(validateCustomJsxTemplate(template)).toEqual(
expect.arrayContaining([
expect.objectContaining({
severity: "error",
message: `${component} must use a literal requestId`,
}),
]),
);
}
},
);
test("accepts only scalar reset dependencies for bindable controls", () => {
expect(
validateCustomJsxTemplate(
'<Pagination bind="page" resetKey={inputs.search} defaultValue={1} total={5} />',
).filter(({ severity }) => severity === "error"),
).toEqual([]);
expect(
validateCustomJsxTemplate('<Pagination bind="page" resetKey={{ search: inputs.search }} total={5} />'),
).toEqual(
expect.arrayContaining([
expect.objectContaining({ severity: "error", message: expect.stringContaining("resetKey must resolve") }),
]),
);
expect(sanitizeCustomJsxProps({ resetKey: { search: "unsafe" }, total: 5 }, "Pagination")).toEqual({
total: 5,
});
});
test("rejects bind values introduced by JSX spreads at the emitter boundary", () => {
expect(() =>
renderSafeJsx({
@@ -338,6 +389,20 @@ describe("shared Custom JSX policy", () => {
expect(renderToStaticMarkup(rendered.node)).toContain("BULBASAUR");
});
test("supports compact indexed literal labels for numeric API enums", () => {
const template =
'<Text>{["Unknown", "Pending", "Processing", "Partially Available", "Available", "Blocklisted", "Deleted"][(data.item?.status ?? 1) - 1] ?? "Unknown"}</Text>';
expect(validateCustomJsxTemplate(template).filter(({ severity }) => severity === "error")).toEqual([]);
const rendered = renderSafeJsx({
template,
components: {
Text: ((props: { children?: unknown }) => createElement("span", null, props.children as never)) as never,
},
bindings: { data: { item: { status: 4 } } },
});
expect(renderToStaticMarkup(rendered.node)).toContain("Partially Available");
});
test("supports bounded regex string operations", () => {
const template = '<Text>{data.name.replace(/[^a-z]/gi, "-")}</Text>';
expect(validateCustomJsxTemplate(template).filter(({ severity }) => severity === "error")).toEqual([]);
@@ -134,6 +134,8 @@ describe("preview sessions", () => {
},
appendJournal: async () => undefined,
getJournal: async () => [],
saveEvidence: async () => undefined,
getEvidence: async () => [],
};
const service = new CustomWidgetPreviewSessionService({
createId: () => "session",
@@ -194,4 +196,55 @@ describe("preview sessions", () => {
expect(service.getSecrets(session, "default")).toEqual([{ kind: "apiKey", value: "token" }]);
expect(service.getSecrets(session, "secondary")).toEqual([{ kind: "username", value: "operator" }]);
});
it("revises only the template with optimistic concurrency and resets evidence by revision", async () => {
const service = new CustomWidgetPreviewSessionService({
createId: () => "session",
encrypt: String,
decrypt: String,
});
await service.create({
userId: "owner",
sources: definition.sources,
requests: definition.requests,
name: definition.name,
template: definition.template,
optionDefinitions: definition.options,
options: { limit: 10 },
secrets: [],
});
const original = await service.get("session", "owner");
await service.appendJournal(original, {
requestId: "data",
kind: "query",
method: "GET",
path: "/data",
status: 200,
durationMs: 1,
simulated: false,
sessionRevision: original.revision,
});
const revised = await service.reviseTemplate(
"session",
"owner",
"<Stack><Text>{data.data?.name}</Text><Badge>Ready</Badge></Stack>",
0,
);
const session = await service.get("session", "owner");
expect(revised).toMatchObject({ id: "session", revision: 1, evidenceReset: true });
expect(session.template).toContain("<Badge>Ready</Badge>");
expect(session.sources).toEqual(original.sources);
expect(session.requests).toEqual(original.requests);
expect(session.optionDefinitions).toEqual(original.optionDefinitions);
expect(await service.getJournal("session", "owner")).toEqual([expect.objectContaining({ sessionRevision: 0 })]);
await expect(service.reviseTemplate("session", "owner", session.template, 1)).rejects.toThrow("unchanged");
await expect(service.reviseTemplate("session", "owner", "<Text>Stale edit</Text>", 0)).rejects.toMatchObject({
code: "CONFLICT",
});
await expect(
service.reviseTemplate("session", "owner", '<ActionButton requestId="missing">Run</ActionButton>', 1),
).rejects.toMatchObject({ code: "BAD_REQUEST" });
});
});
@@ -8,7 +8,15 @@ import { MantineProvider } from "@mantine/core";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { ActionButton, CustomJsxRenderer, CustomWidgetRuntimeProvider, SubFetch, ToggleSwitch } from "../runtime";
import {
ActionButton,
CustomJsxRenderer,
CustomWidgetRuntimeProvider,
parseRequestCapabilities,
RefreshButton,
SubFetch,
ToggleSwitch,
} from "../runtime";
import { createCustomJsxComponents } from "../jsx";
import { MAX_REFRESH_INTERVAL_MS, MAX_REFRESH_INTERVAL_SECONDS, normalizeRefreshInterval } from "../runtime/sub-fetch";
import type {
@@ -44,6 +52,49 @@ const rendererMessages = {
`Input ${name} conflicts between ${firstType} and ${secondType}`,
} satisfies CustomJsxRendererMessages;
it("normalizes request capabilities and drops malformed entries", () => {
expect(
parseRequestCapabilities([
{
id: "approve",
kind: "action",
method: "POST",
trigger: "manual",
minimumBoardPermission: "modify",
confirmation: { title: "Approve", message: "Approve this request?" },
invalidates: ["queue", 3],
},
{
id: "malformed-confirmation",
kind: "action",
method: "POST",
minimumBoardPermission: "modify",
confirmation: { title: 3, message: "Approve this request?" },
},
{ id: "unsafe", kind: "action", method: "TRACE", minimumBoardPermission: "full" },
]),
).toEqual([
{
id: "approve",
kind: "action",
method: "POST",
trigger: "manual",
minimumBoardPermission: "modify",
confirmation: { title: "Approve", message: "Approve this request?" },
invalidates: ["queue"],
},
{
id: "malformed-confirmation",
kind: "action",
method: "POST",
trigger: "manual",
minimumBoardPermission: "modify",
confirmation: undefined,
invalidates: [],
},
]);
});
let root: Root;
let host: HTMLDivElement;
@@ -266,6 +317,60 @@ describe("Custom Widget runtime ports", () => {
expect(host.textContent).toContain("p");
});
it("resets a dependent binding when its scalar reset key changes", async () => {
const query = vi.fn<CustomWidgetRuntimePort["query"]>(async () => ({
ok: true,
status: 200,
data: { name: "The Matrix" },
}));
const components = createCustomJsxComponents({
TablerIcon: (() => null) as never,
copyLabels: { copy: "Copy", copied: "Copied" },
});
await render(
<CustomJsxRenderer
template={
'<Stack><TextInput bind="search" defaultValue="matrix" placeholder="Search"/><Pagination bind="page" resetKey={inputs.search} defaultValue={1} total={5}/><Text>search:{inputs.search}</Text><Text>page:{inputs.page}</Text><SubFetch requestId="search" trigger="manual" params={{ query: inputs.search, page: inputs.page ?? 1 }}>{(result) => <Text>{result.name}</Text>}</SubFetch></Stack>'
}
data={{}}
components={components}
createBindings={() => ({})}
messages={rendererMessages}
/>,
createPort({ query }),
);
await settle();
const pageThree = [...host.querySelectorAll("button")].find((button) => button.textContent === "3");
expect(pageThree).toBeTruthy();
await act(async () => pageThree?.click());
await settle();
expect(host.textContent).toContain("page:3");
const input = host.querySelector('input[placeholder="Search"]') as HTMLInputElement;
await act(async () => {
Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set?.call(input, "s");
input.dispatchEvent(new InputEvent("input", { bubbles: true, data: "s", inputType: "insertText" }));
});
await settle();
expect(input.value).toBe("s");
expect(host.textContent).toContain("search:s");
expect(host.textContent).toContain("page:1");
expect(query).not.toHaveBeenCalled();
const load = [...host.querySelectorAll("button")].find((button) => button.textContent === "Load");
expect(load).toBeTruthy();
await act(async () => load?.click());
await settle();
expect(query).toHaveBeenCalledOnce();
expect(query.mock.calls[0]?.[0]).toMatchObject({
requestId: "search",
params: { query: "s", page: 1 },
});
});
it("resets temporary bindings when the template changes", async () => {
const components = createCustomJsxComponents({
TablerIcon: (() => null) as never,
@@ -383,6 +488,87 @@ describe("Custom Widget runtime ports", () => {
expect(host.textContent).toContain("Bulbasaur:200:false");
});
it("reruns a successful manual query through a targeted refresh button", async () => {
const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
const query = vi.fn<CustomWidgetRuntimePort["query"]>(async () => ({
ok: true,
status: 200,
data: { name: "Bulbasaur" },
}));
const invalidate = vi.fn<CustomWidgetRuntimePort["invalidate"]>(async ({ itemId, targets }) => {
await queryClient.invalidateQueries({
predicate: ({ queryKey }) =>
queryKey[0] === "custom-widget" &&
queryKey[1] === "item" &&
queryKey[2] === itemId &&
(targets.includes("*") || targets.includes(String(queryKey[3]))),
});
});
const port = createPort({ query, invalidate });
await render(
<SubFetch requestId="details" trigger="manual">
{(data) => (
<span>
{(data as { name: string }).name}
<RefreshButton requestId="details" label="Run details again" />
</span>
)}
</SubFetch>,
port,
[],
undefined,
{ queryClient },
);
await act(async () => (host.querySelector("button") as HTMLButtonElement).click());
await settle();
expect(query).toHaveBeenCalledOnce();
const rerun = host.querySelector('button[aria-label="Run details again"]') as HTMLButtonElement;
await act(async () => rerun.click());
await settle();
expect(invalidate).toHaveBeenCalledWith(expect.objectContaining({ targets: ["details"] }));
expect(query).toHaveBeenCalledTimes(2);
});
it("keeps an untargeted refresh global", async () => {
const port = createPort();
await render(<RefreshButton label="Refresh all" />, port);
await act(async () => (host.querySelector("button") as HTMLButtonElement).click());
await settle();
expect(port.invalidate).toHaveBeenCalledWith(expect.objectContaining({ targets: ["parent", "*"] }));
});
it("returns to the manual trigger without fetching or showing stale results when params change", async () => {
const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
const port = createPort();
const renderSearch = (query: string) =>
render(
<SubFetch requestId="details" trigger="manual" params={{ query }}>
{(data) => <span>{(data as { name: string }).name}</span>}
</SubFetch>,
port,
[],
undefined,
{ queryClient },
);
await renderSearch("bulbasaur");
await act(async () => (host.querySelector("button") as HTMLButtonElement).click());
await settle();
expect(host.textContent).toContain("Bulbasaur");
await renderSearch("ivysaur");
await settle();
expect(port.query).toHaveBeenCalledOnce();
expect(host.textContent).toContain("Load");
expect(host.textContent).not.toContain("Bulbasaur");
});
it("keeps manual query results local instead of publishing a shared request slot", async () => {
const port = createPort();
const publish = vi.fn();
@@ -88,6 +88,15 @@ describe("lean Custom Widget schema", () => {
expect(normalizeCustomWidgetAuthoringDefinition(candidate).template).toBe(templateLines.join("\n"));
});
it("removes model-inserted zero-width spaces before JSX validation and persistence", () => {
const candidate = customWidgetDefinitionSchema.parse({
...CUSTOM_WIDGET_STARTER,
template: "<Stack>\u200b<Text>Cafe\u0301 {1 ?? \u03040}</Text>\u200b</Stack>",
});
expect(candidate.template).toBe("<Stack><Text>Café {1 ?? 0}</Text></Stack>");
});
it("requires exactly one authoring template representation", () => {
expect(
customWidgetAuthoringDefinitionSchema.safeParse({ ...CUSTOM_WIDGET_STARTER, templateLines: ["<Text />"] })
@@ -306,6 +315,13 @@ describe("lean Custom Widget schema", () => {
template: "<Stack><Text>Bearer authentication uses source credentials</Text></Stack>",
}).success,
).toBe(true);
expect(
customWidgetDefinitionSchema.safeParse({
...CUSTOM_WIDGET_STARTER,
template:
"<Text>https://www.themoviedb.org/assets/2/v4/glyphicons/basic/glyphicons-basic-38-picture-grey-c8f8b4d9.svg</Text>",
}).success,
).toBe(true);
});
it("requires installation confirmation for private and placeholder source URLs", () => {