@spunto/design-system 0.10.0 → 0.11.0

package/README.md

@@ -89,7 +89,7 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
   provider is also the umbrella that mounts the tooltip delay group and the overlay
   portal container the dialogs/selects render into.
 
-## Domain components — `@spunto/design-system/workers`
+## Domain components — `/workers`, `/devcontainer`, `/projects`
 
 Everything above is domain-free: a `Button` knows nothing about Spunto. Components
 that **do** know a Spunto concept live behind their own entry point, so the root
@@ -98,10 +98,14 @@ of a worker. **The rule for what comes next: any new component that knows a doma
 concept goes behind a domain sub-export, never in the root entry.**
 
 ```tsx
-import { Button, Card } from "@spunto/design-system"        // primitives
-import { WorkerCard } from "@spunto/design-system/workers"  // domain
+import { Button, Card } from "@spunto/design-system"                                        // primitives
+import { WorkerCard } from "@spunto/design-system/workers"                                  // domain
+import { ImageCard, FeatureCard, ExtensionCard } from "@spunto/design-system/devcontainer"  // domain
+import { ProjectForm } from "@spunto/design-system/projects"                                // domain
 ```
 
+### `@spunto/design-system/workers`
+
 - **`WorkerCard`** — a Spunto worker as a card: state, author, node, setup
   progress, git branches, resources, banners, actions. **Purely presentational** —
   hand it a snapshot plus slots and it draws. The rule that keeps it that way:
@@ -119,6 +123,84 @@ import { WorkerCard } from "@spunto/design-system/workers"  // domain
   minimum, everything optional but `id`, and an unknown state falls back to
   `pending` instead of throwing.
 
+### `@spunto/design-system/devcontainer`
+
+The three catalogs you compose an environment from. They exist identically in the
+dashboard and in Spunto Lite, and were hand-drawn as raw `<button>`/`<li>` on both
+sides — exactly the duplication this package is for.
+
+- **`ImageCard`** — a devcontainer base image: runtime mark, label, publisher +
+  avatar, image reference in mono, description.
+- **`FeatureCard`** — a devcontainer feature: the author's avatar (the GitHub org
+  behind the `ghcr.io` ref), label, description, option chips (`version=lts`…),
+  OCI reference.
+- **`ImageTile` / `FeatureTile`** (+ the shared `CatalogTile`) — the same entries
+  at chip size: a mark, a name, one trailing detail. What a catalog needs past a
+  dozen entries, where picking is a *logo* task and full cards become a wall.
+  They flow and wrap like tags; the pickers pair them with the full card of
+  what's selected.
+- **`ExtensionCard`** (+ `ExtensionCardSkeleton`) — a VS Code extension: its real
+  Open VSX icon, display name, publisher + verified badge, version, formatted
+  install count, rating.
+
+All three share one selectable state (flame check + ring), one **compact
+read-only** variant for the project sheet, and one **`custom`** variant for a
+hand-typed reference that degrades cleanly.
+
+- **Nothing here fetches anything.** `onSelect` is a callback, the option row
+  (`optionsSlot`) and the trailing control (`action`) are slots. The author and
+  the logo are **derived from the reference** by pure functions, because the
+  catalogs carry neither: `parseRegistryRef`, `derivePublisher`
+  (`ghcr.io/<owner>/…` → that GitHub org, avatar included via
+  `github.com/<owner>.png`; `mcr.microsoft.com/devcontainers/…` → Dev Containers)
+  and `resolveStackMark`. `publisher` / `mark` / `iconUrl` are the overrides for
+  the day the API knows better — no component change needed then.
+- **Brand marks ship with the package** as single-path SVGs drawn with
+  `currentColor` (`StackMark`, `STACK_MARK_PATHS`): no third-party CDN, and each
+  logo inherits the warm accent of its card instead of dragging 20 clashing brand
+  palettes into one grid.
+- **Its bricks, exported individually**: `CatalogCard` (the selectable shell),
+  `CatalogMark` (the icon → brand → avatar → monogram cascade), `CatalogChip`,
+  `PublisherBadge`/`PublisherAvatar`, `RegistryRef` (mono + copy button), plus the
+  pure helpers `parseRegistryRef`, `derivePublisher`, `githubAvatarUrl`,
+  `resolveStackMark`, `resolveFeatureOptions`, `formatCount`, `parseExtensionId`.
+- **Types are structural** here too: `DevcontainerImageEntry`,
+  `DevcontainerFeatureEntry` and `VscodeExtensionEntry` are all-optional, and an
+  unknown registry degrades to a monogram instead of an invented author.
+
+### `@spunto/design-system/projects`
+
+- **`ProjectForm`** — the whole "compose a dev environment" screen: identity,
+  base image, repos, features, extensions, lifecycle, ports, prewarm images,
+  docker-in-docker, secrets, plus the live **build manifest** that recaps it and
+  carries the submit button.
+- **Controlled by one value.** A single `ProjectFormValue` in, one `onChange`
+  out, `onSubmit(value)` at the end. Start from `emptyProjectFormValue()`, or
+  `toProjectFormValue(partial)` to fill the gaps of an existing project. The
+  value is *always* readable — which is what makes validation, drafts and
+  previews possible at all.
+- **Which sections show is a prop** (`CREATE_SECTIONS` / `EDIT_SECTIONS` / your
+  own list, in your own order). Creation and editing are the same component with
+  a different list, not two screens that drift apart.
+- **Everything past identity / base image / repos folds under "Advanced
+  options"** (`advancedSections`, `[]` to disable). Two rules keep that honest:
+  the closed fold *writes out what it holds* ("2 features · lifecycle · 3
+  secrets") instead of showing a bare chevron, and the form opens it by itself
+  when any of those sections already has a value — so editing a project never
+  hides a setting you made earlier.
+- **Nothing fetches.** Catalogs come in as data, the marketplace search is
+  `onSearchExtensions`, the GitHub combobox is `renderRepoField` (without it: a
+  plain `<input list>` + `<datalist>`, no dependency, keyboard-friendly), and
+  `extras` slips app-specific content *inside* a section — the deploy key card,
+  a warning — without forking the component.
+- **Its bricks, exported individually**: `FormSection`, `Field`,
+  `BuildManifest`, `RepoList` (+`deriveFromGitUrl`), `SecretList`,
+  `ImagePicker`/`FeaturePicker`/`ExtensionPicker`, and the pure `manifestRows`.
+- **Responsive by container query, not viewport.** The form is a full page in
+  one app and a 700 px panel in another; it reads its own width to decide
+  whether the manifest sits beside it and whether the catalogs are one column or
+  two.
+
 ## Toasts — `SpuntoProvider` + `toast()`
 
 `SpuntoProvider` is the design system's client umbrella provider. Mount it once

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",
@@ -37,6 +37,14 @@
       "types": "./src/components/workers/index.ts",
       "import": "./src/components/workers/index.ts"
     },
+    "./devcontainer": {
+      "types": "./src/components/devcontainer/index.ts",
+      "import": "./src/components/devcontainer/index.ts"
+    },
+    "./projects": {
+      "types": "./src/components/projects/index.ts",
+      "import": "./src/components/projects/index.ts"
+    },
     "./fonts": {
       "types": "./src/components/fonts.tsx",
       "import": "./src/components/fonts.tsx"

package/src/components/devcontainer/catalog-card.tsx

@@ -0,0 +1,269 @@
+"use client"
+
+import { useState, type ReactNode } from "react"
+import { CheckIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+import { monogram, PublisherAvatar } from "./publisher-badge"
+import { StackMark, type StackMarkName } from "./stack-mark"
+import type { CatalogPublisher } from "./types"
+
+/** Warm accents the catalogs use — one per pillar, plus the brand flame. */
+export type CatalogTone = "build" | "ship" | "run" | "flame"
+
+const TONE_TILE: Record<CatalogTone, string> = {
+  build: "bg-build/10 text-build",
+  ship: "bg-ship/10 text-ship",
+  run: "bg-run/10 text-run",
+  flame: "bg-primary/10 text-primary",
+}
+
+const TONE_WATERMARK: Record<CatalogTone, string> = {
+  build: "text-build",
+  ship: "text-ship",
+  run: "text-run",
+  flame: "text-primary",
+}
+
+export interface CatalogMarkProps {
+  /** A real logo (an extension icon, say). Beats every derived mark. */
+  iconUrl?: string | null
+  /** Embedded brand mark, when one could be derived. */
+  mark?: StackMarkName | string | null
+  /** Used as the mark when no brand matched — an author's avatar still says something. */
+  publisher?: CatalogPublisher
+  /** Last resort: initials. */
+  label?: string
+  tone?: CatalogTone
+  compact?: boolean
+  className?: string
+}
+
+/**
+ * The tile at the left of every catalog card, resolved by a single cascade —
+ * **real icon → brand mark → publisher avatar → monogram**. Each catalog has a
+ * different amount of truth available (Open VSX ships an icon, ghcr.io only
+ * implies a GitHub org, a hand-typed ref implies nothing), and this cascade is
+ * what makes all three grids look like one product anyway.
+ */
+export function CatalogMark({
+  iconUrl,
+  mark,
+  publisher,
+  label,
+  tone = "build",
+  compact = false,
+  className,
+}: CatalogMarkProps) {
+  const [broken, setBroken] = useState(false)
+  const box = compact ? "h-5 w-5 rounded" : "h-9 w-9 rounded-md"
+
+  if (iconUrl && !broken) {
+    return (
+      <img
+        src={iconUrl}
+        alt=""
+        loading="lazy"
+        onError={() => setBroken(true)}
+        className={cn(box, "shrink-0 bg-muted object-contain ring-1 ring-border/60", className)}
+      />
+    )
+  }
+
+  if (mark) {
+    return (
+      <span className={cn(box, "flex shrink-0 items-center justify-center", TONE_TILE[tone], className)}>
+        <StackMark name={mark} className={compact ? "h-3 w-3" : "h-5 w-5"} />
+      </span>
+    )
+  }
+
+  if (publisher?.avatarUrl) {
+    return <PublisherAvatar publisher={publisher} fallbackLabel={label} className={cn(box, "rounded-md", className)} />
+  }
+
+  return (
+    <span
+      aria-hidden
+      className={cn(
+        box,
+        "flex shrink-0 items-center justify-center font-semibold",
+        compact ? "text-[8px]" : "text-[11px]",
+        TONE_TILE[tone],
+        className
+      )}
+    >
+      {monogram(label || publisher?.name || publisher?.login)}
+    </span>
+  )
+}
+
+export interface CatalogCardProps {
+  /** The tile — usually a `CatalogMark`. */
+  mark?: ReactNode
+  title: ReactNode
+  /** Same line as the title, right after it: a version, a tag. */
+  titleMeta?: ReactNode
+  /** The publisher line, under the title. */
+  meta?: ReactNode
+  description?: ReactNode
+  /** Chips, refs — anything under the description. */
+  children?: ReactNode
+
+  selected?: boolean
+  /**
+   * Provided → the card is selectable (a stretched button covers it, and the
+   * flame check + ring appear when `selected`). Absent → a plain read-only
+   * card, which is exactly what the project sheet needs.
+   */
+  onSelect?: () => void
+  disabled?: boolean
+
+  /** One-line, denser rendering: no description, no watermark. */
+  compact?: boolean
+  /** Nothing was derivable (a hand-typed ref) → dashed border. */
+  custom?: boolean
+
+  /** Trailing control (a remove ✕). Sits above the selection overlay. */
+  action?: ReactNode
+  /** Brand mark bled large and faint into the background. */
+  watermark?: StackMarkName | string | null
+  tone?: CatalogTone
+  /** Accessible name of the selection button when the title isn't a string. */
+  selectLabel?: string
+  className?: string
+}
+
+/**
+ * The shell all three catalog cards share: tile, title, meta, description,
+ * extras — plus the selected state (flame check + ring) that the three pickers
+ * each used to re-implement in a `<button>` of their own.
+ *
+ * **Why the selection is a stretched overlay button rather than a `<button>`
+ * wrapping everything:** these cards carry controls of their own (copy the ref,
+ * remove a custom entry), and a button inside a button is invalid HTML —
+ * browsers unnest it and the inner control stops working. So the card is a
+ * `<div>`, selection is one `absolute inset-0` button covering it, and inner
+ * controls sit above that overlay on `z-10`. The card's own text is left
+ * *static* on purpose: static content paints below positioned siblings, so the
+ * overlay covers it and a click anywhere on the card still selects it.
+ */
+export function CatalogCard({
+  mark,
+  title,
+  titleMeta,
+  meta,
+  description,
+  children,
+  selected = false,
+  onSelect,
+  disabled = false,
+  compact = false,
+  custom = false,
+  action,
+  watermark,
+  tone = "build",
+  selectLabel,
+  className,
+}: CatalogCardProps) {
+  const selectable = Boolean(onSelect)
+
+  return (
+    <div
+      data-slot="catalog-card"
+      data-selected={selected || undefined}
+      // `isolate`: the watermark sits on a negative z-index so it stays behind
+      // the text, and without a stacking context here it would slide behind the
+      // card's own background instead.
+      className={cn(
+        "group relative isolate flex min-w-0 items-start gap-3 overflow-hidden border bg-card text-left transition-colors",
+        compact ? "gap-2 rounded-md px-2 py-1.5" : "rounded-lg px-3 py-2.5",
+        custom ? "border-dashed border-border" : "border-border",
+        selected && "border-primary bg-primary/5 ring-1 ring-primary",
+        selectable && !selected && !disabled && "hover:border-muted-foreground/40 hover:bg-muted/50",
+        disabled && "opacity-50",
+        className
+      )}
+    >
+      {/* The runtime's mark, bled large into the corner and almost invisible.
+          It's texture, not information — it's what lets you tell a Python card
+          from a Go one out of the corner of your eye, in a grid where every
+          card is otherwise the same three lines of text. */}
+      {watermark && !compact && (
+        <span
+          aria-hidden
+          className={cn(
+            "pointer-events-none absolute -top-5 -right-6 -z-10 transition-opacity",
+            selected ? "opacity-[0.08]" : "opacity-[0.04] group-hover:opacity-[0.06]",
+            TONE_WATERMARK[tone]
+          )}
+        >
+          <StackMark name={watermark} className="h-28 w-28" />
+        </span>
+      )}
+
+      {selectable && (
+        <button
+          type="button"
+          onClick={onSelect}
+          disabled={disabled}
+          aria-pressed={selected}
+          aria-label={selectLabel ?? (typeof title === "string" ? title : undefined)}
+          className={cn(
+            "absolute inset-0 cursor-pointer focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none disabled:cursor-not-allowed",
+            compact ? "rounded-md" : "rounded-lg"
+          )}
+        />
+      )}
+
+      {mark && <span className="mt-px">{mark}</span>}
+
+      <div className="min-w-0 flex-1 space-y-1">
+        <div className="flex min-w-0 items-center gap-2">
+          <span className={cn("min-w-0 truncate font-medium leading-tight", compact ? "text-xs" : "text-sm")}>
+            {title}
+          </span>
+          {titleMeta}
+        </div>
+
+        {meta && <div className="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1">{meta}</div>}
+
+        {description && !compact && <p className="line-clamp-2 text-xs text-muted-foreground">{description}</p>}
+
+        {children}
+      </div>
+
+      {/* The check sits in the flow rather than pinned absolutely: at 288 px a
+          title wrapping onto two lines used to slide under a pinned check. */}
+      {(selected || action) && (
+        <span className="relative z-10 flex shrink-0 items-center gap-1 self-start pt-px">
+          {selected && <CheckIcon className={cn("text-primary", compact ? "h-3.5 w-3.5" : "h-4 w-4")} aria-hidden />}
+          {action}
+        </span>
+      )}
+    </div>
+  )
+}
+
+/** Chip for a feature option, an extension version, a download count. */
+export function CatalogChip({
+  children,
+  title,
+  className,
+}: {
+  children: ReactNode
+  title?: string
+  className?: string
+}) {
+  return (
+    <span
+      title={title}
+      className={cn(
+        "inline-flex max-w-full items-center gap-1 truncate rounded border border-border bg-muted/60 px-1.5 py-0.5 font-mono text-[10px] leading-none text-muted-foreground",
+        className
+      )}
+    >
+      {children}
+    </span>
+  )
+}

package/src/components/devcontainer/catalog-tile.tsx

@@ -0,0 +1,133 @@
+"use client"
+
+import type { ReactNode } from "react"
+import { CheckIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+import type { CatalogTone } from "./catalog-card"
+
+const TONE = {
+  build: "text-build",
+  ship: "text-ship",
+  run: "text-run",
+  flame: "text-primary",
+} as const satisfies Record<CatalogTone, string>
+
+export interface CatalogTileProps {
+  /** The glyph — a brand mark, an avatar, a `+`. Sized by the tile. */
+  mark: ReactNode
+  label: string
+  /** Trailing detail: an image tag, a version. Dropped in `tile` when it doesn't fit. */
+  meta?: string
+  /** Full text for the native tooltip — the label truncates. */
+  title?: string
+
+  selected?: boolean
+  onSelect?: () => void
+  disabled?: boolean
+  custom?: boolean
+  variant?: "chip" | "tile"
+  tone?: CatalogTone
+  className?: string
+}
+
+/**
+ * The shell behind `ImageTile` and `FeatureTile`: a catalog entry reduced to a
+ * glyph, a name and one trailing detail.
+ *
+ * Extracted rather than copied, because the two only differ in what they *put*
+ * in it — an image derives a runtime mark and a tag, a feature derives its
+ * author's avatar — and this package exists to stop that kind of near-duplicate
+ * from drifting apart.
+ *
+ * `chip` flows and wraps like a tag; `tile` is a square-ish grid cell. Both
+ * carry the same flame check as the full cards, because a chip grid and a card
+ * grid are the same choice and "this one is picked" has to look the same.
+ */
+export function CatalogTile({
+  mark,
+  label,
+  meta,
+  title,
+  selected = false,
+  onSelect,
+  disabled = false,
+  custom = false,
+  variant = "chip",
+  tone = "ship",
+  className,
+}: CatalogTileProps) {
+  const Root = onSelect ? "button" : "div"
+
+  const common = {
+    "data-slot": "catalog-tile",
+    "data-selected": selected || undefined,
+    "data-variant": variant,
+    title: title ?? label,
+    ...(onSelect
+      ? { type: "button" as const, onClick: onSelect, disabled, "aria-pressed": selected, "aria-label": label }
+      : {}),
+  }
+
+  const state = cn(
+    custom ? "border-dashed border-border" : "border-border",
+    selected ? "border-primary bg-primary/5 ring-1 ring-primary" : "bg-card",
+    onSelect && !disabled && "cursor-pointer",
+    onSelect && !selected && !disabled && "hover:border-muted-foreground/40 hover:bg-muted/50",
+    disabled && "cursor-not-allowed opacity-50"
+  )
+
+  const markClass = cn(
+    "flex shrink-0 items-center justify-center transition-colors",
+    selected ? TONE[tone] : "text-muted-foreground group-hover:text-foreground"
+  )
+
+  if (variant === "chip") {
+    return (
+      <Root
+        {...common}
+        className={cn(
+          // `inline-flex` + the parent's `flex-wrap`: entries flow and break
+          // onto the next line like text, so a catalog of any length just takes
+          // the rows it needs — no column count to choose, no ragged grid.
+          "group inline-flex max-w-full min-w-0 items-center gap-2 rounded-md border py-1.5 pr-2.5 pl-2 text-left transition-colors",
+          state,
+          className
+        )}
+      >
+        <span className={cn(markClass, "h-5 w-5")}>{mark}</span>
+        <span className="min-w-0 truncate text-xs font-medium">{label}</span>
+        {meta && <span className="shrink-0 font-mono text-[10px] leading-none text-muted-foreground/60">{meta}</span>}
+        {selected && <CheckIcon className="h-3.5 w-3.5 shrink-0 text-primary" aria-hidden />}
+      </Root>
+    )
+  }
+
+  return (
+    <Root
+      {...common}
+      className={cn(
+        // Square-ISH, via a min-height rather than `aspect-square`: a strict
+        // square clipped "Node.js 20 (TypeScript)" the moment it wrapped onto a
+        // second line. Grid rows stretch their cells to the tallest anyway, so
+        // the row stays even without forcing the ratio.
+        "group relative flex min-h-[5.5rem] min-w-0 flex-col items-center justify-center gap-1.5 overflow-hidden rounded-lg border px-2 py-2.5 text-center transition-colors",
+        state,
+        className
+      )}
+    >
+      {selected && <CheckIcon className="absolute top-1.5 right-1.5 h-3.5 w-3.5 text-primary" aria-hidden />}
+
+      <span className={cn(markClass, "h-8 w-8")}>{mark}</span>
+
+      {/* Two lines then ellipsis: "Node.js 20 (TypeScript)" needs both, and a
+          single truncated line would cut every entry of a same runtime to the
+          identical, useless "Node.js 20 (Type…". */}
+      <span className="line-clamp-2 w-full text-[11px] leading-tight font-medium break-words">{label}</span>
+
+      {meta && (
+        <span className="max-w-full truncate font-mono text-[9px] leading-none text-muted-foreground/70">{meta}</span>
+      )}
+    </Root>
+  )
+}

package/src/components/devcontainer/extension-card.tsx

@@ -0,0 +1,146 @@
+"use client"
+
+import type { ReactNode } from "react"
+import { DownloadIcon, StarIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+import { CatalogCard, CatalogMark, type CatalogTone } from "./catalog-card"
+import { PublisherBadge } from "./publisher-badge"
+import { extensionId, formatCount, parseExtensionId } from "./registry"
+import { resolveStackMark } from "./stack-mark"
+import type { VscodeExtensionEntry } from "./types"
+
+export interface ExtensionCardProps {
+  extension: VscodeExtensionEntry
+  selected?: boolean
+  onSelect?: () => void
+  disabled?: boolean
+  compact?: boolean
+  /** An id typed by hand: no icon, no publisher, no counts to show. */
+  custom?: boolean
+  action?: ReactNode
+  tone?: CatalogTone
+  className?: string
+}
+
+/**
+ * A VS Code extension, as a card: its real Open VSX icon, its display name, the
+ * publisher (with the marketplace's verified check), version, install count and
+ * rating.
+ *
+ * Open VSX already returns every one of those on `/api/-/search` — the picker
+ * used to fetch them and throw them away, rendering `displayName` + `id`. Wiring
+ * them in is what turns a list of identifiers into a catalogue you can choose
+ * from.
+ */
+export function ExtensionCard({
+  extension,
+  selected = false,
+  onSelect,
+  disabled = false,
+  compact = false,
+  custom = false,
+  action,
+  tone = "flame",
+  className,
+}: ExtensionCardProps) {
+  const id = extensionId(extension)
+  // A project only ever stores the id, so a card drawn from the database has to
+  // split it back apart to have anything to say at all.
+  const fromId = parseExtensionId(id)
+  const namespace = extension.namespace ?? fromId.namespace
+  const name = extension.name ?? fromId.name
+  const title = extension.displayName || name || id || "Extension"
+  const iconUrl = custom ? undefined : (extension.iconUrl ?? extension.files?.icon ?? undefined)
+  // Only ever a *fallback* mark: an extension's own icon is always better than
+  // a guess made from its id, so this is what fills the tile when Open VSX has
+  // no icon (or the card is drawn from a stored id alone).
+  const mark = custom ? undefined : resolveStackMark(name, extension.displayName)
+  const publisher =
+    extension.publisher ??
+    (namespace ? { name: namespace, login: namespace, verified: extension.verified } : undefined)
+
+  const downloads = formatCount(extension.downloadCount)
+  const rating = extension.averageRating != null ? Math.round(extension.averageRating * 10) / 10 : undefined
+
+  return (
+    <CatalogCard
+      className={className}
+      compact={compact}
+      custom={custom}
+      selected={selected}
+      onSelect={onSelect}
+      disabled={disabled}
+      action={action}
+      tone={tone}
+      selectLabel={typeof title === "string" ? title : undefined}
+      mark={
+        <CatalogMark iconUrl={iconUrl} mark={mark} publisher={publisher} label={title} tone={tone} compact={compact} />
+      }
+      title={title}
+      titleMeta={
+        extension.version && !compact ? (
+          <span className="shrink-0 rounded border border-border bg-muted px-1.5 py-0.5 font-mono text-[10px] leading-none text-muted-foreground">
+            v{extension.version}
+          </span>
+        ) : undefined
+      }
+      meta={
+        !compact ? (
+          <>
+            {publisher && <PublisherBadge publisher={publisher} showAvatar={false} />}
+            {downloads && (
+              <span className="inline-flex items-center gap-1 text-[11px] text-muted-foreground/70" title="Installs">
+                <DownloadIcon className="h-3 w-3 shrink-0" />
+                {downloads}
+              </span>
+            )}
+            {rating != null && rating > 0 && (
+              <span
+                className="inline-flex items-center gap-1 text-[11px] text-muted-foreground/70"
+                title={extension.reviewCount ? `${extension.reviewCount} reviews` : "Average rating"}
+              >
+                <StarIcon className="h-3 w-3 shrink-0 fill-current" />
+                {rating.toFixed(1)}
+              </span>
+            )}
+          </>
+        ) : undefined
+      }
+      description={extension.description}
+    >
+      {id && (
+        <span
+          title={id}
+          className={cn(
+            "block max-w-full truncate font-mono text-[10px] leading-none text-muted-foreground/60",
+            compact ? "mt-0.5" : "mt-1.5"
+          )}
+        >
+          {id}
+        </span>
+      )}
+    </CatalogCard>
+  )
+}
+
+/**
+ * Placeholder while the Open VSX search is in flight. The search used to show a
+ * spinner in the input and nothing else, so the dropdown appeared to pop out of
+ * nowhere; three of these keep the space and let you see it coming.
+ */
+export function ExtensionCardSkeleton({ className }: { className?: string }) {
+  return (
+    <div
+      aria-hidden
+      className={cn("flex items-start gap-3 rounded-lg border border-border bg-card px-3 py-2.5", className)}
+    >
+      <span className="h-9 w-9 shrink-0 animate-pulse rounded-md bg-muted" />
+      <div className="min-w-0 flex-1 space-y-1.5 py-0.5">
+        <span className="block h-3 w-1/3 animate-pulse rounded bg-muted" />
+        <span className="block h-2.5 w-1/4 animate-pulse rounded bg-muted/70" />
+        <span className="block h-2.5 w-3/4 animate-pulse rounded bg-muted/70" />
+      </div>
+    </div>
+  )
+}