@stigmer/react 3.5.1 → 3.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/react",
-  "version": "3.5.1",
+  "version": "3.5.3",
   "description": "React provider and client hook for the Stigmer platform SDK",
   "license": "Apache-2.0",
   "type": "module",
@@ -37,7 +37,7 @@
   "dependencies": {
     "@bufbuild/protovalidate": "^1.1.1",
     "@dagrejs/dagre": "^1.1.4",
-    "@stigmer/theme": "3.5.1",
+    "@stigmer/theme": "3.5.3",
     "diff": "^8.0.3",
     "fflate": "^0.8.2",
     "hast-util-to-jsx-runtime": "^2.3.6",
@@ -60,8 +60,8 @@
     "@codemirror/state": "^6.0.0",
     "@codemirror/view": "^6.0.0",
     "@lezer/highlight": "^1.0.0",
-    "@stigmer/protos": "3.5.1",
-    "@stigmer/sdk": "3.5.1",
+    "@stigmer/protos": "3.5.3",
+    "@stigmer/sdk": "3.5.3",
     "@tanstack/react-table": "^8.20.0",
     "@xyflow/react": "^12.0.0",
     "elkjs": "^0.9.0",

package/skill/SkillFileBrowser.d.ts

@@ -12,7 +12,8 @@ export interface SkillFileBrowserProps {
  * - Left panel: file tree with folder grouping
  * - Right panel: content viewer (rendered Markdown for .md, raw code otherwise)
  *
- * SKILL.md is selected by default on load.
+ * SKILL.md is selected by default on load; packages without a root SKILL.md
+ * fall back to the first file in tree order.
  * Responsive: stacked layout on mobile viewports.
  *
  * Zero Console dependencies — safe for platform builder embedding.

package/skill/SkillFileBrowser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SkillFileBrowser.d.ts","sourceRoot":"","sources":["../../src/skill/SkillFileBrowser.tsx"],"names":[],"mappings":"AAaA,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,qDAAqD;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,kBAAkB,EAClB,SAAS,GACV,EAAE,qBAAqB,kDAkGvB"}
+{"version":3,"file":"SkillFileBrowser.d.ts","sourceRoot":"","sources":["../../src/skill/SkillFileBrowser.tsx"],"names":[],"mappings":"AAaA,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,qDAAqD;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,kBAAkB,EAClB,SAAS,GACV,EAAE,qBAAqB,kDA6GvB"}

package/skill/SkillFileBrowser.js

@@ -16,7 +16,8 @@ import { useSkillArtifact } from "./useSkillArtifact.js";
  * - Left panel: file tree with folder grouping
  * - Right panel: content viewer (rendered Markdown for .md, raw code otherwise)
  *
- * SKILL.md is selected by default on load.
+ * SKILL.md is selected by default on load; packages without a root SKILL.md
+ * fall back to the first file in tree order.
  * Responsive: stacked layout on mobile viewports.
  *
  * Zero Console dependencies — safe for platform builder embedding.
@@ -33,9 +34,22 @@ import { useSkillArtifact } from "./useSkillArtifact.js";
  */
 export function SkillFileBrowser({ artifactStorageKey, className, }) {
     const { files, isLoading, error, getFileContent } = useSkillArtifact(artifactStorageKey);
-    const [selectedPath, setSelectedPath] = useState("SKILL.md");
-    const treeNodes = useMemo(() => (files ? buildFileTree(files.filter((f) => !f.isDirectory)) : []), [files]);
-    const content = useMemo(() => (selectedPath ? getFileContent(selectedPath) : null), [selectedPath, getFileContent]);
+    // Only the user's explicit click is state; the initial selection is derived
+    // from the loaded file list below, so it exists the moment files do.
+    const [userSelectedPath, setUserSelectedPath] = useState(null);
+    const fileEntries = useMemo(() => (files ? files.filter((f) => !f.isDirectory) : []), [files]);
+    const treeNodes = useMemo(() => buildFileTree(fileEntries), [fileEntries]);
+    // Default to the manifest; fall back to the first file in rendered tree
+    // order (buildFileTree sorts by localeCompare, and depth-first tree order
+    // follows that sort) so the auto-highlighted row is the topmost file.
+    const defaultPath = useMemo(() => {
+        if (fileEntries.some((f) => f.path === "SKILL.md"))
+            return "SKILL.md";
+        const sorted = [...fileEntries].sort((a, b) => a.path.localeCompare(b.path));
+        return sorted[0]?.path ?? null;
+    }, [fileEntries]);
+    const selectedPath = userSelectedPath ?? defaultPath;
+    const content = selectedPath !== null ? getFileContent(selectedPath) : null;
     if (!artifactStorageKey)
         return null;
     if (isLoading) {
@@ -46,7 +60,7 @@ export function SkillFileBrowser({ artifactStorageKey, className, }) {
     }
     if (!files || files.length === 0)
         return null;
-    return (_jsxs("div", { className: cn("rounded-lg border border-border overflow-hidden", className), children: [_jsx("div", { className: "border-b border-border px-4 py-2", children: _jsx("h3", { className: "text-xs font-medium uppercase tracking-wider text-muted-foreground", children: "Package Files" }) }), _jsxs("div", { className: "grid grid-cols-1 md:grid-cols-[220px_1fr]", children: [_jsx("nav", { className: "border-b border-border md:border-b-0 md:border-r overflow-y-auto", "aria-label": "Skill package file tree", children: _jsx("ul", { className: "py-1", role: "tree", children: treeNodes.map((node) => (_jsx(FileTreeNode, { node: node, selectedPath: selectedPath, onSelect: setSelectedPath, depth: 0 }, node.path))) }) }), _jsx("div", { className: "min-h-[200px] max-h-[400px] overflow-y-auto p-4", children: content !== null ? (_jsx(FileContentViewer, { path: selectedPath, content: content })) : (_jsx("p", { className: "text-sm text-muted-foreground-subtle italic", children: "Select a file to view its contents" })) })] })] }));
+    return (_jsxs("div", { className: cn("rounded-lg border border-border overflow-hidden", className), children: [_jsx("div", { className: "border-b border-border px-4 py-2", children: _jsx("h3", { className: "text-xs font-medium uppercase tracking-wider text-muted-foreground", children: "Package Files" }) }), _jsxs("div", { className: "grid grid-cols-1 md:grid-cols-[220px_1fr]", children: [_jsx("nav", { className: "border-b border-border md:border-b-0 md:border-r overflow-y-auto", "aria-label": "Skill package file tree", children: _jsx("ul", { className: "py-1", role: "tree", children: treeNodes.map((node) => (_jsx(FileTreeNode, { node: node, selectedPath: selectedPath ?? "", onSelect: setUserSelectedPath, depth: 0 }, node.path))) }) }), _jsx("div", { className: "min-h-[200px] max-h-[400px] overflow-y-auto p-4", children: selectedPath !== null && content !== null ? (_jsx(FileContentViewer, { path: selectedPath, content: content })) : (_jsx("p", { className: "text-sm text-muted-foreground-subtle italic", children: "Select a file to view its contents" })) })] })] }));
 }
 // ---------------------------------------------------------------------------
 // Content viewer

package/skill/SkillFileBrowser.js.map

@@ -1 +1 @@
-{"version":3,"file":"SkillFileBrowser.js","sourceRoot":"","sources":["../../src/skill/SkillFileBrowser.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"SkillFileBrowser.js","sourceRoot":"","sources":["../../src/skill/SkillFileBrowser.tsx"],"names":[],"mappings":"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"}

package/skill/internal/fetchAndUnpackArtifact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetchAndUnpackArtifact.d.ts","sourceRoot":"","sources":["../../../src/skill/internal/fetchAndUnpackArtifact.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClD;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,OAAO,EAChB,kBAAkB,EAAE,MAAM,GACzB,OAAO,CAAC,gBAAgB,CAAC,CA0B3B"}
+{"version":3,"file":"fetchAndUnpackArtifact.d.ts","sourceRoot":"","sources":["../../../src/skill/internal/fetchAndUnpackArtifact.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClD;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,OAAO,EAChB,kBAAkB,EAAE,MAAM,GACzB,OAAO,CAAC,gBAAgB,CAAC,CA6B3B"}

package/skill/internal/fetchAndUnpackArtifact.js

@@ -18,9 +18,12 @@ export async function fetchAndUnpackArtifact(stigmer, artifactStorageKey) {
         size: data.length,
         isDirectory: data.length === 0 && path.endsWith("/"),
     }));
+    // Every non-directory entry gets a map entry — including zero-byte files,
+    // which map to "". Skipping them would make an empty file unreadable in the
+    // browser and read as *deleted* (rather than emptied) in version diffs.
     const contentMap = new Map();
     for (const [path, data] of entries) {
-        if (!path.endsWith("/") && data.length > 0) {
+        if (!path.endsWith("/")) {
             try {
                 contentMap.set(path, strFromU8(data));
             }

package/skill/internal/fetchAndUnpackArtifact.js.map

@@ -1 +1 @@
-{"version":3,"file":"fetchAndUnpackArtifact.js","sourceRoot":"","sources":["../../../src/skill/internal/fetchAndUnpackArtifact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,wBAAwB,EAAE,MAAM,mDAAmD,CAAC;AAU7F;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAAgB,EAChB,kBAA0B;IAE1B,MAAM,OAAO,GAAG,MAAM,CAAC,wBAAwB,EAAE,EAAE,kBAAkB,EAAE,CAAC,CAAC;IACzE,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAE1D,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAE9C,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,KAAK,GAAqB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QAC7D,IAAI;QACJ,IAAI,EAAE,IAAI,CAAC,MAAM;QACjB,WAAW,EAAE,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;KACrD,CAAC,CAAC,CAAC;IAEJ,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC7C,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3C,IAAI,CAAC;gBACH,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;YACxC,CAAC;YAAC,MAAM,CAAC;gBACP,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"fetchAndUnpackArtifact.js","sourceRoot":"","sources":["../../../src/skill/internal/fetchAndUnpackArtifact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,wBAAwB,EAAE,MAAM,mDAAmD,CAAC;AAU7F;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAAgB,EAChB,kBAA0B;IAE1B,MAAM,OAAO,GAAG,MAAM,CAAC,wBAAwB,EAAE,EAAE,kBAAkB,EAAE,CAAC,CAAC;IACzE,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAE1D,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAE9C,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,KAAK,GAAqB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QAC7D,IAAI;QACJ,IAAI,EAAE,IAAI,CAAC,MAAM;QACjB,WAAW,EAAE,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;KACrD,CAAC,CAAC,CAAC;IAEJ,0EAA0E;IAC1E,4EAA4E;IAC5E,wEAAwE;IACxE,MAAM,UAAU,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC7C,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC;QACnC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC;gBACH,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;YACxC,CAAC;YAAC,MAAM,CAAC;gBACP,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,kBAAkB,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;AAC/B,CAAC"}

package/skill/useSkillArtifact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useSkillArtifact.d.ts","sourceRoot":"","sources":["../../src/skill/useSkillArtifact.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAO1D,gDAAgD;AAChD,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IACxC,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACzD,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,kBAAkB,EAAE,MAAM,GAAG,IAAI,GAChC,sBAAsB,CAqDxB"}
+{"version":3,"file":"useSkillArtifact.d.ts","sourceRoot":"","sources":["../../src/skill/useSkillArtifact.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAO1D,gDAAgD;AAChD,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI,CAAC;IACxC,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACzD,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,kBAAkB,EAAE,MAAM,GAAG,IAAI,GAChC,sBAAsB,CA8DxB"}

package/skill/useSkillArtifact.js

@@ -30,13 +30,18 @@ import { fetchAndUnpackArtifact } from "./internal/fetchAndUnpackArtifact.js";
 export function useSkillArtifact(artifactStorageKey) {
     const stigmer = useStigmer();
     const [files, setFiles] = useState(null);
+    // State, not a ref: `getFileContent` derives its identity from this map, so
+    // consumers' memos invalidate exactly when the artifact's contents arrive.
+    // A ref here once made the lookup silently non-reactive — a viewer memoizing
+    // `getFileContent(path)` stayed stuck on the pre-download `null` forever.
+    const [contentMap, setContentMap] = useState(new Map());
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);
-    const contentMapRef = useRef(new Map());
     const fetchIdRef = useRef(0);
     const doFetch = useCallback(async () => {
         if (!artifactStorageKey) {
             setFiles(null);
+            setContentMap(new Map());
             setError(null);
             return;
         }
@@ -47,7 +52,7 @@ export function useSkillArtifact(artifactStorageKey) {
             const result = await fetchAndUnpackArtifact(stigmer, artifactStorageKey);
             if (fetchIdRef.current !== fetchId)
                 return;
-            contentMapRef.current = new Map(result.contentMap);
+            setContentMap(result.contentMap);
             setFiles(result.files);
         }
         catch (err) {
@@ -55,6 +60,7 @@ export function useSkillArtifact(artifactStorageKey) {
                 return;
             setError(toError(err));
             setFiles(null);
+            setContentMap(new Map());
         }
         finally {
             if (fetchIdRef.current === fetchId) {
@@ -65,9 +71,7 @@ export function useSkillArtifact(artifactStorageKey) {
     useEffect(() => {
         doFetch();
     }, [doFetch]);
-    const getFileContent = useCallback((path) => {
-        return contentMapRef.current.get(path) ?? null;
-    }, []);
+    const getFileContent = useCallback((path) => contentMap.get(path) ?? null, [contentMap]);
     const refetch = useCallback(() => {
         doFetch();
     }, [doFetch]);

package/skill/useSkillArtifact.js.map

@@ -1 +1 @@
-{"version":3,"file":"useSkillArtifact.js","sourceRoot":"","sources":["../../src/skill/useSkillArtifact.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useSkillArtifact.js","sourceRoot":"","sources":["../../src/skill/useSkillArtifact.ts"],"names":[],"mappings":"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"}

package/src/execution/__tests__/PlanArtifactCard.test.tsx

@@ -1,5 +1,11 @@
-import { describe, it, expect, vi, afterEach } from "vitest";
-import { render, screen, fireEvent, cleanup } from "@testing-library/react";
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import {
+  render,
+  screen,
+  fireEvent,
+  cleanup,
+  waitFor,
+} from "@testing-library/react";
 import type { ReactNode } from "react";
 import { create } from "@bufbuild/protobuf";
 import type { Stigmer } from "@stigmer/sdk";
@@ -47,6 +53,17 @@ function renderCard(ui: ReactNode) {
 
 afterEach(cleanup);
 
+// The download flow ends in a transient-anchor click with target="_blank".
+// Left unstubbed, happy-dom treats that click as a real popup navigation and
+// fetches the fixture URL over the actual network — after this test has
+// already returned, so the DNS failure gets attributed to whichever test the
+// worker is running by then (the flake in issue #334).
+beforeEach(() => {
+  vi.spyOn(HTMLAnchorElement.prototype, "click")
+    .mockImplementation(() => {})
+    .mockClear();
+});
+
 describe("PlanArtifactCard — compact document card", () => {
   it("is an accessible region with the plan's title, filename, and size", () => {
     renderCard(
@@ -178,6 +195,7 @@ describe("PlanArtifactCard — compact document card", () => {
 
   it("downloads the artifact on demand via a freshly minted URL", async () => {
     const { stigmer, getArtifactDownloadUrl } = createStigmerMock();
+    const anchorClick = vi.spyOn(HTMLAnchorElement.prototype, "click");
     render(
       withStigmer(
         <PlanArtifactCard executionId="aex_1" artifact={planArtifact} org="acme" />,
@@ -191,6 +209,9 @@ describe("PlanArtifactCard — compact document card", () => {
     const req = getArtifactDownloadUrl.mock.calls[0][0];
     expect(req.executionId).toBe("aex_1");
     expect(req.storageKey).toBe("artifacts/aex_1/plan.md");
+    // Wait for the mint-URL → anchor-click continuation INSIDE the test body;
+    // returning while it is still in flight is what let it escape.
+    await waitFor(() => expect(anchorClick).toHaveBeenCalledTimes(1));
   });
 });
 

package/src/skill/SkillFileBrowser.tsx

@@ -30,7 +30,8 @@ export interface SkillFileBrowserProps {
  * - Left panel: file tree with folder grouping
  * - Right panel: content viewer (rendered Markdown for .md, raw code otherwise)
  *
- * SKILL.md is selected by default on load.
+ * SKILL.md is selected by default on load; packages without a root SKILL.md
+ * fall back to the first file in tree order.
  * Responsive: stacked layout on mobile viewports.
  *
  * Zero Console dependencies — safe for platform builder embedding.
@@ -50,17 +51,28 @@ export function SkillFileBrowser({
   className,
 }: SkillFileBrowserProps) {
   const { files, isLoading, error, getFileContent } = useSkillArtifact(artifactStorageKey);
-  const [selectedPath, setSelectedPath] = useState<string>("SKILL.md");
+  // Only the user's explicit click is state; the initial selection is derived
+  // from the loaded file list below, so it exists the moment files do.
+  const [userSelectedPath, setUserSelectedPath] = useState<string | null>(null);
 
-  const treeNodes = useMemo(
-    () => (files ? buildFileTree(files.filter((f) => !f.isDirectory)) : []),
+  const fileEntries = useMemo(
+    () => (files ? files.filter((f) => !f.isDirectory) : []),
     [files],
   );
 
-  const content = useMemo(
-    () => (selectedPath ? getFileContent(selectedPath) : null),
-    [selectedPath, getFileContent],
-  );
+  const treeNodes = useMemo(() => buildFileTree(fileEntries), [fileEntries]);
+
+  // Default to the manifest; fall back to the first file in rendered tree
+  // order (buildFileTree sorts by localeCompare, and depth-first tree order
+  // follows that sort) so the auto-highlighted row is the topmost file.
+  const defaultPath = useMemo(() => {
+    if (fileEntries.some((f) => f.path === "SKILL.md")) return "SKILL.md";
+    const sorted = [...fileEntries].sort((a, b) => a.path.localeCompare(b.path));
+    return sorted[0]?.path ?? null;
+  }, [fileEntries]);
+
+  const selectedPath = userSelectedPath ?? defaultPath;
+  const content = selectedPath !== null ? getFileContent(selectedPath) : null;
 
   if (!artifactStorageKey) return null;
 
@@ -125,8 +137,8 @@ export function SkillFileBrowser({
               <FileTreeNode
                 key={node.path}
                 node={node}
-                selectedPath={selectedPath}
-                onSelect={setSelectedPath}
+                selectedPath={selectedPath ?? ""}
+                onSelect={setUserSelectedPath}
                 depth={0}
               />
             ))}
@@ -135,7 +147,7 @@ export function SkillFileBrowser({
 
         {/* Content viewer */}
         <div className="min-h-[200px] max-h-[400px] overflow-y-auto p-4">
-          {content !== null ? (
+          {selectedPath !== null && content !== null ? (
             <FileContentViewer path={selectedPath} content={content} />
           ) : (
             <p className="text-sm text-muted-foreground-subtle italic">

package/src/skill/__tests__/SkillFileBrowser.test.tsx

@@ -0,0 +1,100 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { zipSync, strToU8 } from "fflate";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { SkillFileBrowser } from "../SkillFileBrowser";
+
+function wrapperFor(stigmer: Stigmer) {
+  return ({ children }: { children: ReactNode }) => (
+    <StigmerContext.Provider value={stigmer}>{children}</StigmerContext.Provider>
+  );
+}
+
+/**
+ * Builds a real ZIP (via fflate, the same library the unpacker uses) and a
+ * Stigmer client whose `skill.getArtifact` serves it — so tests exercise the
+ * genuine fetch → unzip → browse path instead of stubbing the unpacker.
+ */
+function makeStigmerServing(files: Record<string, Uint8Array>) {
+  const getArtifact = vi.fn().mockResolvedValue({ artifact: zipSync(files) });
+  return { skill: { getArtifact } } as unknown as Stigmer;
+}
+
+function renderBrowser(stigmer: Stigmer) {
+  return render(<SkillFileBrowser artifactStorageKey="skills/test/pkg.zip" />, {
+    wrapper: wrapperFor(stigmer),
+  });
+}
+
+const PLACEHOLDER = "Select a file to view its contents";
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("SkillFileBrowser", () => {
+  it("renders SKILL.md content without any click for a single-file package", async () => {
+    // Regression: the content lookup used to be memoized against a frozen
+    // getter, so a one-file package stayed stuck on the placeholder forever.
+    const stigmer = makeStigmerServing({
+      "SKILL.md": strToU8("# Docs Skill\n\nAnswers questions about Stigmer."),
+    });
+    renderBrowser(stigmer);
+
+    expect(
+      await screen.findByRole("heading", { name: "Docs Skill" }),
+    ).toBeTruthy();
+    expect(screen.queryByText(PLACEHOLDER)).toBeNull();
+  });
+
+  it("prefers SKILL.md as the default in a multi-file package and switches on click", async () => {
+    const stigmer = makeStigmerServing({
+      "SKILL.md": strToU8("# Manifest"),
+      "scripts/validate.py": strToU8('print("validated")'),
+    });
+    renderBrowser(stigmer);
+
+    expect(
+      await screen.findByRole("heading", { name: "Manifest" }),
+    ).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("button", { name: "validate.py" }));
+    expect(screen.getByText('print("validated")')).toBeTruthy();
+    expect(
+      screen.queryByRole("heading", { name: "Manifest" }),
+    ).toBeNull();
+  });
+
+  it("falls back to the first file in tree order when there is no root SKILL.md", async () => {
+    // buildFileTree sorts by localeCompare, so "alpha/inner.md" renders above
+    // "beta.md" — the default selection must match what the user sees on top.
+    const stigmer = makeStigmerServing({
+      "beta.md": strToU8("# Beta"),
+      "alpha/inner.md": strToU8("# Inner Alpha"),
+    });
+    renderBrowser(stigmer);
+
+    expect(
+      await screen.findByRole("heading", { name: "Inner Alpha" }),
+    ).toBeTruthy();
+    expect(screen.queryByText(PLACEHOLDER)).toBeNull();
+  });
+
+  it("shows an empty file as (empty) content, not the placeholder", async () => {
+    const stigmer = makeStigmerServing({
+      "SKILL.md": strToU8("# Manifest"),
+      "notes.txt": new Uint8Array(0),
+    });
+    renderBrowser(stigmer);
+
+    await screen.findByRole("heading", { name: "Manifest" });
+    fireEvent.click(screen.getByRole("button", { name: "notes.txt" }));
+
+    // The viewer switched away from the manifest and, despite the file's
+    // empty content, did not regress to the "select a file" placeholder.
+    expect(screen.queryByRole("heading", { name: "Manifest" })).toBeNull();
+    expect(screen.queryByText(PLACEHOLDER)).toBeNull();
+  });
+});

package/src/skill/internal/fetchAndUnpackArtifact.ts

@@ -33,9 +33,12 @@ export async function fetchAndUnpackArtifact(
     isDirectory: data.length === 0 && path.endsWith("/"),
   }));
 
+  // Every non-directory entry gets a map entry — including zero-byte files,
+  // which map to "". Skipping them would make an empty file unreadable in the
+  // browser and read as *deleted* (rather than emptied) in version diffs.
   const contentMap = new Map<string, string>();
   for (const [path, data] of entries) {
-    if (!path.endsWith("/") && data.length > 0) {
+    if (!path.endsWith("/")) {
       try {
         contentMap.set(path, strFromU8(data));
       } catch {

package/src/skill/useSkillArtifact.ts

@@ -54,14 +54,21 @@ export function useSkillArtifact(
 ): UseSkillArtifactReturn {
   const stigmer = useStigmer();
   const [files, setFiles] = useState<SkillFileEntry[] | null>(null);
+  // State, not a ref: `getFileContent` derives its identity from this map, so
+  // consumers' memos invalidate exactly when the artifact's contents arrive.
+  // A ref here once made the lookup silently non-reactive — a viewer memoizing
+  // `getFileContent(path)` stayed stuck on the pre-download `null` forever.
+  const [contentMap, setContentMap] = useState<ReadonlyMap<string, string>>(
+    new Map(),
+  );
   const [isLoading, setIsLoading] = useState(false);
   const [error, setError] = useState<Error | null>(null);
-  const contentMapRef = useRef<Map<string, string>>(new Map());
   const fetchIdRef = useRef(0);
 
   const doFetch = useCallback(async () => {
     if (!artifactStorageKey) {
       setFiles(null);
+      setContentMap(new Map());
       setError(null);
       return;
     }
@@ -75,12 +82,13 @@ export function useSkillArtifact(
 
       if (fetchIdRef.current !== fetchId) return;
 
-      contentMapRef.current = new Map(result.contentMap);
+      setContentMap(result.contentMap);
       setFiles(result.files);
     } catch (err) {
       if (fetchIdRef.current !== fetchId) return;
       setError(toError(err));
       setFiles(null);
+      setContentMap(new Map());
     } finally {
       if (fetchIdRef.current === fetchId) {
         setIsLoading(false);
@@ -92,9 +100,10 @@ export function useSkillArtifact(
     doFetch();
   }, [doFetch]);
 
-  const getFileContent = useCallback((path: string): string | null => {
-    return contentMapRef.current.get(path) ?? null;
-  }, []);
+  const getFileContent = useCallback(
+    (path: string): string | null => contentMap.get(path) ?? null,
+    [contentMap],
+  );
 
   const refetch = useCallback(() => {
     doFetch();