@stigmer/react 3.12.2 → 3.12.4

package/src/session/facets/UsageTab.tsx

@@ -1,8 +1,9 @@
 "use client";
 
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
-import { useSessionUsage } from "../useSessionUsage.js";
-import { UsageWidget } from "../../execution/UsageWidget.js";
+import { ServiceTier } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { useSessionUsage, type ExecutionUsageEntry } from "../useSessionUsage.js";
+import { UsageWidget, formatCost } from "../../execution/UsageWidget.js";
 
 export interface UsageTabProps {
   readonly executions: readonly AgentExecution[];
@@ -11,9 +12,16 @@ export interface UsageTabProps {
 /**
  * Usage facet for the session panel (a `useSessionRailViews` rail view).
  *
- * Uses `useSessionUsage` to determine if data exists, then delegates
- * rendering to the existing `UsageWidget`. Shows an empty state when
- * no usage data is available.
+ * Renders the session totals ({@link UsageWidget}) plus the #362 model
+ * provenance list: per execution, the billing-RESOLVED model with its
+ * cost — for a Cursor Auto run, the only honest answer to "which model
+ * actually ran and what did it cost", since the requested model is empty
+ * by definition there — paired with the tier the runner REQUESTED (the
+ * streaming summary's audit record that the account default was never
+ * left in control). Requested-vs-billed divergence is a platform alarm
+ * (`stigmer.billing.service_tier.mismatch`), not a per-row UI concern.
+ *
+ * Shows an empty state when no usage data is available.
  */
 export function UsageTab({ executions }: UsageTabProps) {
   const usage = useSessionUsage(executions);
@@ -28,5 +36,89 @@ export function UsageTab({ executions }: UsageTabProps) {
     );
   }
 
-  return <UsageWidget executions={executions} />;
+  return (
+    <div className="stg:flex stg:flex-col stg:gap-4">
+      <UsageWidget executions={executions} />
+      {usage.executionBreakdown.length > 0 && (
+        <ExecutionModelList
+          entries={usage.executionBreakdown}
+          executions={executions}
+        />
+      )}
+    </div>
+  );
+}
+
+/**
+ * Per-execution model provenance rows, in the report's chronological
+ * order: `#N resolved-model [tier requested] [Estimated]  $cost`.
+ */
+function ExecutionModelList({
+  entries,
+  executions,
+}: {
+  readonly entries: readonly ExecutionUsageEntry[];
+  readonly executions: readonly AgentExecution[];
+}) {
+  return (
+    <div
+      className="stg:flex stg:flex-col stg:gap-1"
+      role="list"
+      aria-label="Per-execution model and tier"
+    >
+      <div className="stg:text-xs stg:font-medium stg:text-foreground">
+        Models per run
+      </div>
+      {entries.map((entry, index) => {
+        const requestedTier = requestedTierLabel(executions, entry.executionId);
+        return (
+          <div
+            key={entry.executionId}
+            className="stg:flex stg:items-baseline stg:justify-between stg:gap-2 stg:text-xs stg:text-muted-foreground"
+            role="listitem"
+          >
+            <span className="stg:truncate">
+              <span className="stg:tabular-nums">#{index + 1}</span>{" "}
+              {entry.resolvedModel || "—"}
+              {requestedTier && (
+                <span className="stg:ml-1 stg:rounded stg:bg-muted stg:px-1 stg:py-0.5 stg:text-[10px] stg:font-medium stg:leading-none">
+                  {requestedTier} requested
+                </span>
+              )}
+              {entry.isEstimated && (
+                <span className="stg:ml-1 stg:rounded stg:bg-muted stg:px-1 stg:py-0.5 stg:text-[10px] stg:font-medium stg:leading-none">
+                  Estimated
+                </span>
+              )}
+            </span>
+            <span className="stg:shrink-0 stg:tabular-nums">
+              {formatCost(entry.billableCostUsd)}
+            </span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+/**
+ * The tier the runner requested for one execution, from its streaming
+ * usage summary — present once the runner has translated the execution
+ * config, absent for executions that predate the tier attribute. Never
+ * "unspecified": the runner records the RESOLVED tier (#357's audit
+ * contract).
+ */
+function requestedTierLabel(
+  executions: readonly AgentExecution[],
+  executionId: string,
+): string | null {
+  const match = executions.find((e) => e.metadata?.id === executionId);
+  switch (match?.status?.streamingUsage?.requestedServiceTier) {
+    case ServiceTier.FAST:
+      return "fast";
+    case ServiceTier.STANDARD:
+      return "standard";
+    default:
+      return null;
+  }
 }

package/src/session/index.ts

@@ -58,6 +58,7 @@ export type { UseSessionFileChangesReturn } from "./useSessionFileChanges.js";
 
 export { useSessionUsage } from "./useSessionUsage.js";
 export type {
+  ExecutionUsageEntry,
   ModelCostEntry,
   UseSessionUsageReturn,
 } from "./useSessionUsage.js";

package/src/session/useSessionUsage.ts

@@ -41,6 +41,25 @@ export interface ModelCostEntry {
   readonly callCount: number;
 }
 
+/**
+ * Per-execution model provenance from billing records (stigmer/stigmer#362).
+ */
+export interface ExecutionUsageEntry {
+  /** Execution identifier (`metadata.id`). */
+  readonly executionId: string;
+  /**
+   * Billing-resolved primary model — what the provider actually served.
+   * For a Cursor Auto execution this is the after-the-fact answer to
+   * "which model did Auto pick", which the requested model (empty by
+   * definition there) can never give.
+   */
+  readonly resolvedModel: string;
+  /** Billable cost in USD for this execution. */
+  readonly billableCostUsd: number;
+  /** `true` while this execution's records are still provisional. */
+  readonly isEstimated: boolean;
+}
+
 /** Return value of {@link useSessionUsage}. */
 export interface UseSessionUsageReturn {
   /** Aggregate estimated cost in USD across all models. */
@@ -59,6 +78,13 @@ export interface UseSessionUsageReturn {
   readonly llmCallCount: number;
   /** Per-model cost and token breakdown. */
   readonly modelBreakdown: readonly ModelCostEntry[];
+  /**
+   * Per-execution resolved model + cost, chronological, from billing
+   * records (#362). Empty until the first authoritative record lands —
+   * the streaming fallback deliberately contributes none, because the
+   * runner only knows what it REQUESTED, never what the provider served.
+   */
+  readonly executionBreakdown: readonly ExecutionUsageEntry[];
   /** Model with the highest usage in this session. */
   readonly primaryModel: string;
   /** Provider of the primary model. */
@@ -82,6 +108,7 @@ const EMPTY: UseSessionUsageReturn = {
   cacheCreationTokens: 0,
   llmCallCount: 0,
   modelBreakdown: [],
+  executionBreakdown: [],
   primaryModel: "",
   primaryProvider: "",
   hasUsage: false,
@@ -122,6 +149,12 @@ function mapReport(report: GetSessionUsageReportOutput): UseSessionUsageReturn {
     cacheCreationTokens: Number(agg.cacheCreationInputTokens),
     llmCallCount,
     modelBreakdown: report.modelBreakdown.map(mapModelUsage),
+    executionBreakdown: report.executions.map((e) => ({
+      executionId: e.executionId,
+      resolvedModel: e.primaryModel,
+      billableCostUsd: microsToUsd(e.billableCostMicros),
+      isEstimated: e.isEstimated,
+    })),
     primaryModel: agg.primaryModel,
     primaryProvider: agg.primaryProvider,
     hasUsage: llmCallCount > 0 || totalTokens > 0 || billableCost > 0,
@@ -169,6 +202,10 @@ function aggregateStreamingUsage(
     cacheReadTokens,
     cacheCreationTokens,
     llmCallCount: turnCount,
+    // No executionBreakdown here on purpose: the runner only knows the
+    // REQUESTED model; resolved-model rows exist only once billing
+    // records land (#362).
+    executionBreakdown: [],
     modelBreakdown: model
       ? [
           {

package/src/settings/__tests__/useSettingsNavGroups.test.tsx

@@ -48,6 +48,7 @@ describe("useSettingsNavGroups", () => {
     verdicts = {
       can_manage_model_pricing: true,
       can_manage_cursor_accounts: true,
+      can_view_provider_standing: true,
     };
     render(<GroupsProbe />);
 
@@ -56,7 +57,7 @@ describe("useSettingsNavGroups", () => {
       `${BASE_LABELS},${PLATFORM_SETTINGS_NAV_GROUP.label}`,
     );
     expect(el.getAttribute("data-platform-items")).toBe(
-      "Pricing Governance,Cursor Accounts",
+      "Pricing Governance,Cursor Accounts,Provider Standing",
     );
   });
 
@@ -78,6 +79,15 @@ describe("useSettingsNavGroups", () => {
     );
   });
 
+  it("filters per item: standing-only operator sees only Provider Standing", () => {
+    verdicts = { can_view_provider_standing: true };
+    render(<GroupsProbe />);
+
+    expect(screen.getByTestId("groups").getAttribute("data-platform-items")).toBe(
+      "Provider Standing",
+    );
+  });
+
   it("returns exactly the base groups when not authorized", () => {
     function IdentityProbe() {
       const groups = useSettingsNavGroups();

package/src/settings/settings-nav.ts

@@ -1,5 +1,6 @@
 import type { ComponentType } from "react";
 import {
+  Activity,
   AppWindow,
   BarChart3,
   Box,
@@ -123,5 +124,11 @@ export const PLATFORM_SETTINGS_NAV_GROUP: SettingsNavGroup = {
       icon: MousePointerClick,
       requiredPermission: "can_manage_cursor_accounts",
     },
+    {
+      href: "/settings/provider-standing",
+      label: "Provider Standing",
+      icon: Activity,
+      requiredPermission: "can_view_provider_standing",
+    },
   ],
 };

package/src/settings/useSettingsNavGroups.ts

@@ -52,14 +52,21 @@ export function useSettingsNavGroups(): readonly SettingsNavGroup[] {
     "can_manage_cursor_accounts",
     { fail: "closed" },
   );
+  const providerStanding = useCheckPermission(
+    PLATFORM_RESOURCE,
+    "can_view_provider_standing",
+    { fail: "closed" },
+  );
 
   const pricingAllowed = pricing.allowed;
   const cursorAccountsAllowed = cursorAccounts.allowed;
+  const providerStandingAllowed = providerStanding.allowed;
 
   return useMemo(() => {
     const verdicts: Record<string, boolean> = {
       can_manage_model_pricing: pricingAllowed,
       can_manage_cursor_accounts: cursorAccountsAllowed,
+      can_view_provider_standing: providerStandingAllowed,
     };
 
     const visibleItems = PLATFORM_SETTINGS_NAV_GROUP.items.filter(
@@ -77,5 +84,5 @@ export function useSettingsNavGroups(): readonly SettingsNavGroup[] {
       ...SETTINGS_NAV_GROUPS,
       { ...PLATFORM_SETTINGS_NAV_GROUP, items: visibleItems },
     ];
-  }, [pricingAllowed, cursorAccountsAllowed]);
+  }, [pricingAllowed, cursorAccountsAllowed, providerStandingAllowed]);
 }

package/src/sharing/ShareAgentDialog.tsx

@@ -2,6 +2,8 @@
 
 import { useCallback, useId, useMemo, useRef, useState, type FormEvent } from "react";
 import { cn } from "@stigmer/theme";
+import { DialogShell } from "../internal/DialogShell.js";
+import { UNSTYLED_LIST } from "../internal/element-resets.js";
 import {
   MAX_ALLOWED_ORIGINS,
   StigmerError,
@@ -137,8 +139,6 @@ export function ShareAgentDialog({
   onSharingChanged,
   modal = true,
 }: ShareAgentDialogProps) {
-  const dialogRef = useRef<HTMLDialogElement>(null);
-
   // Instance-scoped title id (oss#593): a reusable component must not
   // hardcode DOM ids — hosts legitimately mount this dialog more than once
   // per page (e.g. zone-cached detail pages), and duplicate ids break the
@@ -146,36 +146,15 @@ export function ShareAgentDialog({
   const titleId = useId();
 
   const handleClose = useCallback(() => {
-    dialogRef.current?.close();
     onOpenChange(false);
   }, [onOpenChange]);
 
-  // Sync native dialog open state (matches the SDK dialog convention).
-  // Non-modal hosts pass `open` as a plain attribute instead — the dialog
-  // renders in-flow with no top layer to manage.
-  const prevOpenRef = useRef(false);
-  if (modal && open !== prevOpenRef.current) {
-    prevOpenRef.current = open;
-    if (open) {
-      requestAnimationFrame(() => {
-        if (dialogRef.current && !dialogRef.current.open) {
-          dialogRef.current.showModal();
-        }
-      });
-    } else if (dialogRef.current?.open) {
-      dialogRef.current.close();
-    }
-  }
-
   return (
-    <dialog
-      ref={dialogRef}
-      open={modal ? undefined : open}
-      onClose={handleClose}
-      className={cn(
-        "stg:w-full stg:max-w-lg stg:rounded-xl stg:border stg:border-border stg:bg-popover stg:p-0 stg:shadow-xl",
-        modal ? "stg:fixed stg:inset-0 stg:m-auto stg:backdrop:bg-backdrop" : "stg:relative",
-      )}
+    <DialogShell
+      open={open}
+      onOpenChange={onOpenChange}
+      modal={modal}
+      width="lg"
       aria-labelledby={titleId}
     >
       {/* Body mounts only while open so its draft state resets per
@@ -191,7 +170,7 @@ export function ShareAgentDialog({
           titleId={titleId}
         />
       )}
-    </dialog>
+    </DialogShell>
   );
 }
 
@@ -1338,7 +1317,7 @@ function OriginsEditor({
       </p>
 
       {draft.allowedOrigins.length > 0 && (
-        <ul className="stg:mt-2 stg:flex stg:flex-col stg:divide-y stg:divide-border stg:rounded-md stg:border stg:border-border">
+        <ul className={cn(UNSTYLED_LIST, "stg:mt-2 stg:flex stg:flex-col stg:divide-y stg:divide-border stg:rounded-md stg:border stg:border-border")}>
           {draft.allowedOrigins.map((origin) => (
             <li
               key={origin}

package/src/sidebar/WorkspaceSidebar.tsx

@@ -15,6 +15,7 @@ import type { RecentActivityEntry, RecentActivityGroup } from "../activity/types
 import { groupRecentActivityByTime } from "../activity/group-activity.js";
 import { formatRelativeTime } from "../activity/format-relative-time.js";
 import { recentActivityStatusBadge } from "../activity/entry-status-badge.js";
+import { UNSTYLED_LIST } from "../internal/element-resets.js";
 import { ScrollArea } from "../internal/scroll-area.js";
 import {
   Tooltip,
@@ -313,7 +314,7 @@ function ActivityGroupList({
             <p className="stg:text-sidebar-muted-foreground stg:mb-1 stg:px-2 stg:text-[10px] stg:font-medium stg:tracking-wider stg:uppercase">
               {group.label}
             </p>
-            <ul className="stg:space-y-0.5" role="list">
+            <ul className={`${UNSTYLED_LIST} stg:space-y-0.5`} role="list">
               {group.entries.map((entry) => (
                 <ActivityEntry
                   key={entry.id}

package/src/skill/SkillDiffDialog.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import { useCallback, useEffect, useRef } from "react";
+import { useCallback } from "react";
 import { cn } from "@stigmer/theme";
+import { DialogShell } from "../internal/DialogShell.js";
 import { useSkillDiff } from "./useSkillDiff.js";
 import { MultiFileDiffView } from "../version-history/MultiFileDiffView.js";
 import { ErrorMessage } from "../error/ErrorMessage.js";
@@ -57,31 +58,9 @@ export interface SkillDiffDialogProps {
  * ```
  */
 export function SkillDiffDialog({ state, onClose }: SkillDiffDialogProps) {
-  const dialogRef = useRef<HTMLDialogElement>(null);
-
-  useEffect(() => {
-    const dialog = dialogRef.current;
-    if (!dialog) return;
-    if (state && !dialog.open) {
-      dialog.showModal();
-    } else if (!state && dialog.open) {
-      dialog.close();
-    }
-  }, [state]);
-
-  const handleDialogCancel = useCallback(
-    (e: React.SyntheticEvent) => {
-      e.preventDefault();
-      onClose();
-    },
-    [onClose],
-  );
-
-  const handleBackdropClick = useCallback(
-    (e: React.MouseEvent<HTMLDialogElement>) => {
-      if (e.target === e.currentTarget) {
-        onClose();
-      }
+  const handleOpenChange = useCallback(
+    (open: boolean) => {
+      if (!open) onClose();
     },
     [onClose],
   );
@@ -94,15 +73,13 @@ export function SkillDiffDialog({ state, onClose }: SkillDiffDialogProps) {
   if (!state) return null;
 
   return (
-    <dialog
-      ref={dialogRef}
-      onCancel={handleDialogCancel}
-      onClick={handleBackdropClick}
-      className={cn(
-        "stg:fixed stg:inset-0 stg:z-50 stg:m-auto stg:h-[85vh] stg:w-full stg:max-w-4xl stg:rounded-lg stg:border stg:border-border stg:bg-popover stg:p-0 stg:text-popover-foreground stg:shadow-lg",
-        "stg:backdrop:bg-backdrop",
-        "stg:open:animate-in stg:open:fade-in-0 stg:open:zoom-in-95",
-      )}
+    <DialogShell
+      open
+      onOpenChange={handleOpenChange}
+      width="4xl"
+      dismissOnBackdrop
+      className="stg:h-[85vh]"
+      aria-label="Skill version diff"
     >
       <div className="stg:flex stg:h-full stg:flex-col">
         {/* Header */}
@@ -142,7 +119,7 @@ export function SkillDiffDialog({ state, onClose }: SkillDiffDialogProps) {
           ) : null}
         </div>
       </div>
-    </dialog>
+    </DialogShell>
   );
 }
 

package/src/skill/SkillFileBrowser.tsx

@@ -3,6 +3,7 @@
 import { useMemo, useState } from "react";
 import Markdown from "react-markdown";
 import { cn } from "@stigmer/theme";
+import { UNSTYLED_LIST } from "../internal/element-resets.js";
 import { MARKDOWN_COMPONENTS, REMARK_PLUGINS, stripFrontmatter } from "../internal/markdown-components.js";
 import { buildFileTree, FileTreeNode } from "../internal/file-tree/index.js";
 import { useSkillArtifact } from "./useSkillArtifact.js";
@@ -132,7 +133,7 @@ export function SkillFileBrowser({
           className="stg:border-b stg:border-border stg:md:border-b-0 stg:md:border-r stg:overflow-y-auto"
           aria-label="Skill package file tree"
         >
-          <ul className="stg:py-1" role="tree">
+          <ul className={cn(UNSTYLED_LIST, "stg:py-1")} role="tree">
             {treeNodes.map((node) => (
               <FileTreeNode
                 key={node.path}

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

@@ -2,7 +2,7 @@ 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 { StigmerError, type Stigmer } from "@stigmer/sdk";
 import { StigmerContext } from "../../context";
 import { SkillFileBrowser } from "../SkillFileBrowser";
 
@@ -12,14 +12,22 @@ function wrapperFor(stigmer: Stigmer) {
   );
 }
 
+/** Connect's Unimplemented code — what a pre-transfer-lane server answers. */
+const CODE_UNIMPLEMENTED = 12;
+
 /**
  * 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.
+ * The download-URL mint answers Unimplemented (a pre-transfer-lane server),
+ * pinning that the browser degrades to the unary lane it always used.
  */
 function makeStigmerServing(files: Record<string, Uint8Array>) {
   const getArtifact = vi.fn().mockResolvedValue({ artifact: zipSync(files) });
-  return { skill: { getArtifact } } as unknown as Stigmer;
+  const getArtifactDownloadUrl = vi
+    .fn()
+    .mockRejectedValue(new StigmerError("unknown", "unimplemented", CODE_UNIMPLEMENTED));
+  return { skill: { getArtifact, getArtifactDownloadUrl } } as unknown as Stigmer;
 }
 
 function renderBrowser(stigmer: Stigmer) {

package/src/skill/__tests__/fetchAndUnpackArtifact.test.ts

@@ -0,0 +1,90 @@
+// Pins for the artifact fetch lane selection (stigmer#701): URL-first via
+// getArtifactDownloadUrl, with the two deliberate browser degrade arms —
+// Unimplemented mint (pre-lane server) and a failed URL fetch (the shape a
+// missing bucket CORS policy takes in a browser).
+import { describe, expect, it, vi } from "vitest";
+import { strToU8, zipSync } from "fflate";
+import { StigmerError, type Stigmer } from "@stigmer/sdk";
+import { fetchAndUnpackArtifact } from "../internal/fetchAndUnpackArtifact.js";
+
+const CODE_UNIMPLEMENTED = 12;
+const ZIP = zipSync({ "SKILL.md": strToU8("# hi") });
+
+function stigmerWith(overrides: {
+  mint?: ReturnType<typeof vi.fn>;
+  unary?: ReturnType<typeof vi.fn>;
+  fetch?: unknown;
+}): Stigmer {
+  return {
+    skill: {
+      getArtifactDownloadUrl: overrides.mint,
+      getArtifact: overrides.unary,
+    },
+    fetch: overrides.fetch,
+  } as unknown as Stigmer;
+}
+
+describe("fetchAndUnpackArtifact lane selection", () => {
+  it("fetches via the minted download URL, never the unary lane", async () => {
+    const mint = vi.fn().mockResolvedValue({ url: "https://r2.example/skills/get" });
+    const unary = vi.fn();
+    const fetchImpl = vi.fn(async () => new Response(new Uint8Array(ZIP).buffer, { status: 200 }));
+
+    const result = await fetchAndUnpackArtifact(
+      stigmerWith({ mint, unary, fetch: fetchImpl }),
+      "skills/org/skill/hash.zip",
+    );
+
+    expect(fetchImpl).toHaveBeenCalledWith("https://r2.example/skills/get");
+    expect(unary).not.toHaveBeenCalled();
+    expect(result.contentMap.get("SKILL.md")).toBe("# hi");
+  });
+
+  it("degrades to the unary lane when the mint answers Unimplemented (pre-lane server)", async () => {
+    const mint = vi
+      .fn()
+      .mockRejectedValue(new StigmerError("unknown", "unimplemented", CODE_UNIMPLEMENTED));
+    const unary = vi.fn().mockResolvedValue({ artifact: ZIP });
+
+    const result = await fetchAndUnpackArtifact(
+      stigmerWith({ mint, unary }),
+      "skills/org/skill/hash.zip",
+    );
+
+    expect(unary).toHaveBeenCalledTimes(1);
+    expect(result.contentMap.get("SKILL.md")).toBe("# hi");
+  });
+
+  it("degrades to the unary lane when the URL fetch itself fails (browser CORS shape), warning once", async () => {
+    const mint = vi.fn().mockResolvedValue({ url: "https://r2.example/skills/get" });
+    const unary = vi.fn().mockResolvedValue({ artifact: ZIP });
+    const fetchImpl = vi.fn(async () => {
+      throw new TypeError("Failed to fetch");
+    });
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    try {
+      const result = await fetchAndUnpackArtifact(
+        stigmerWith({ mint, unary, fetch: fetchImpl }),
+        "skills/org/skill/hash.zip",
+      );
+      expect(unary).toHaveBeenCalledTimes(1);
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(result.contentMap.get("SKILL.md")).toBe("# hi");
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("propagates a non-Unimplemented mint failure — a real error must not be masked", async () => {
+    const mint = vi
+      .fn()
+      .mockRejectedValue(new StigmerError("not-found", "no such artifact", 5));
+    const unary = vi.fn();
+
+    await expect(
+      fetchAndUnpackArtifact(stigmerWith({ mint, unary }), "skills/org/skill/hash.zip"),
+    ).rejects.toThrow(/no such artifact/);
+    expect(unary).not.toHaveBeenCalled();
+  });
+});

package/src/skill/__tests__/useSkillUpload.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { zipSync, strToU8 } from "fflate";
+import { useSkillUpload } from "../useSkillUpload";
+
+const SKILL_MD = "---\nname: my-skill\ndescription: A test skill\n---\n# My Skill\n";
+
+/** Build a real ZIP (fflate, the same library the hook unpacks with) as a File. */
+function zipFile(files: Record<string, Uint8Array>): File {
+  return new File([zipSync(files)], "skill.zip", { type: "application/zip" });
+}
+
+async function process(files: Record<string, Uint8Array>) {
+  const { result } = renderHook(() => useSkillUpload());
+  await act(() => result.current.processFile(zipFile(files)));
+  return result;
+}
+
+describe("useSkillUpload", () => {
+  it("accepts a root SKILL.md and produces a preview", async () => {
+    const result = await process({
+      "SKILL.md": strToU8(SKILL_MD),
+      "references/schema.md": strToU8("# Schema"),
+    });
+
+    expect(result.current.validationError).toBeNull();
+    expect(result.current.preview?.name).toBe("my-skill");
+    expect(result.current.preview?.description).toBe("A test skill");
+    expect(result.current.artifact).not.toBeNull();
+  });
+
+  // The layout contract is root-only on both editions (DD-018, #452). The
+  // preview exists to catch the "zipped the folder instead of its contents"
+  // mistake BEFORE upload — accepting nested here and failing at push is the
+  // exact confusion issue #684 pins.
+  it("rejects a nested-only SKILL.md with the zip-the-contents hint", async () => {
+    const result = await process({
+      "my-skill/SKILL.md": strToU8(SKILL_MD),
+      "my-skill/references/schema.md": strToU8("# Schema"),
+    });
+
+    expect(result.current.preview).toBeNull();
+    expect(result.current.artifact).toBeNull();
+    expect(result.current.validationError).toBe(
+      "Found my-skill/SKILL.md — SKILL.md must be at the archive root. " +
+        "Zip the skill folder's contents, not the folder itself.",
+    );
+  });
+
+  it("detects a deeply nested SKILL.md for the hint (any depth, server parity)", async () => {
+    const result = await process({
+      "wrapper/my-skill/SKILL.md": strToU8(SKILL_MD),
+    });
+
+    expect(result.current.preview).toBeNull();
+    expect(result.current.validationError).toContain("Found wrapper/my-skill/SKILL.md");
+  });
+
+  it("rejects an archive with no SKILL.md anywhere with the plain root-level message", async () => {
+    const result = await process({
+      "README.md": strToU8("# Not a skill"),
+    });
+
+    expect(result.current.preview).toBeNull();
+    expect(result.current.validationError).toBe(
+      "ZIP must contain a SKILL.md file at the root level",
+    );
+  });
+});