@workbench-kit/react 0.0.2-prototype.0.1.4 → 0.0.2-prototype.0.2.11

package/README.md

@@ -0,0 +1,87 @@
+# `@workbench-kit/react`
+
+React primitives and workbench chrome for integrating hosts (browser, desktop
+shells, and other React hosts).
+
+Published on npm with the **`prototype`** dist tag.
+
+## Install
+
+```powershell
+pnpm add @workbench-kit/react@prototype @workbench-kit/tokens@prototype
+```
+
+Peer: React 19.
+
+## Styles
+
+Import once at app entry:
+
+```ts
+import '@workbench-kit/tokens/styles.css';
+import '@workbench-kit/react/styles.css';
+import '@workbench-kit/react/primitives.css';
+```
+
+## Quick start
+
+```tsx
+import { WorkbenchShell } from '@workbench-kit/react/workbench/shell';
+
+export function AppShell() {
+  return (
+    <div className="ui-workbench-host-root" style={{ height: '100vh' }}>
+      <WorkbenchShell
+        activityBar={{
+          items: [
+            { id: 'explorer', icon: <i className="codicon codicon-files" />, label: 'Explorer' },
+          ],
+        }}
+        rootClassName="ide-root"
+        secondaryArea={<main>Editor region</main>}
+        statusSections={[]}
+      />
+    </div>
+  );
+}
+```
+
+Full walkthrough: [Getting Started](../../docs/guides/getting-started.md).
+
+## Common subpaths
+
+| Subpath                                    | Purpose                                 |
+| ------------------------------------------ | --------------------------------------- |
+| `@workbench-kit/react/primitives`          | Buttons, editor chrome, library layouts |
+| `@workbench-kit/react/workbench/shell`     | Workbench shell / activity bar          |
+| `@workbench-kit/react/workbench/workspace` | Explorer, workspace editor panel        |
+| `@workbench-kit/react/workbench/chat`      | Chat panel and message surfaces         |
+| `@workbench-kit/react/overlay`             | Context menus, anchored overlays        |
+| `@workbench-kit/react/modal`               | Low-level modal frame                   |
+| `@workbench-kit/react/jdw`                 | JDW preview bridges                     |
+| `@workbench-kit/react/styles.css`          | Shell chrome CSS                        |
+
+Import **only** through `exports`. Do not deep-import `src/` paths.
+
+## Learn more
+
+| Doc                                                                    | Purpose                       |
+| ---------------------------------------------------------------------- | ----------------------------- |
+| [Getting Started](../../docs/guides/getting-started.md)                | Install + minimal shell       |
+| [Component Map](../../docs/guides/component-map.md)                    | Surface → Storybook / sample  |
+| [Sample Screens](../../docs/guides/sample-screens.md)                  | Example screen recipes        |
+| [Consumer Capabilities](../../docs/workbench/consumer-capabilities.md) | Props / when-to-use contracts |
+| [API Reference](../../docs/guides/api-reference.md)                    | Package export index          |
+
+## Local verification (this monorepo)
+
+```powershell
+pnpm install
+pnpm build:workbench-extensions
+pnpm dev
+pnpm dev:storybook
+```
+
+Storybook stays a curated set of interaction stories — not a full package gallery.
+Demo and story modules under this package are for development; published consumers
+rely on the `exports` map and CSS entry points above.

package/package.json

@@ -1,39 +1,53 @@
 {
   "name": "@workbench-kit/react",
-  "version": "0.0.2-prototype.0.1.4",
+  "version": "0.0.2-prototype.0.2.11",
   "private": false,
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./drag-mime": "./src/utils/dragMime.ts",
     "./modal": "./src/modal/Modal.tsx",
-    "./overlay": "./src/overlay/ContextMenu.tsx",
+    "./layout": "./src/layout/index.ts",
+    "./editor-tabs": "./src/workbench/editor-tabs/index.ts",
+    "./icons": "./src/icons/index.ts",
+    "./overlay": "./src/overlay/index.ts",
+    "./brand": "./src/brand/index.ts",
     "./primitives": "./src/primitives/index.ts",
     "./primitives.css": "./src/primitives/styles.css",
     "./workbench/auth": "./src/workbench/auth/index.ts",
+    "./workbench/bootstrap": "./src/workbench/bootstrap/index.ts",
     "./workbench/chat": "./src/workbench/chat/index.ts",
+    "./workbench/management": "./src/workbench/management/index.ts",
     "./workbench/settings": "./src/workbench/settings/index.ts",
     "./workbench": "./src/workbench/index.ts",
-    "./workbench/markdown-preview": "./src/workbench/MarkdownPreview.tsx",
-    "./workbench/shell": "./src/workbench/shell.ts",
-    "./workbench/split-view": "./src/workbench/SplitView.tsx",
+    "./workbench/activityBarOrder": "./src/workbench/shell/activityBarOrder.ts",
+    "./workbench/markdown-preview": "./src/workbench/markdown/MarkdownPreview.tsx",
+    "./workbench/shell": "./src/workbench/shell/shell.ts",
+    "./workbench/theme-provider": "./src/workbench/theme/WorkbenchThemeProvider.tsx",
+    "./workbench/themePresets": "./src/workbench/theme/themePresets.ts",
+    "./workbench/split-view": "./src/workbench/shell/SplitView.tsx",
     "./workbench/workspace": "./src/workbench/workspace/index.ts",
     "./workbench/workspace/editor": "./src/workbench/workspace/WorkspaceEditor.tsx",
     "./workbench/workspace/explorer": "./src/workbench/workspace/WorkspaceExplorer.tsx",
-    "./workbench/workspace/file-icon": "./src/workbench/workspace/WorkspaceFileIcon.tsx",
+    "./workbench/workspace/file-icon": "./src/icons/file-icon.ts",
+    "./workbench/commands": "./src/workbench/commands/commands.ts",
     "./jdw": "./src/jdw/index.ts",
     "./jdw/document": "./src/jdw/document.ts",
     "./jdw/parse": "./src/jdw/parse.ts",
     "./jdw/preview": "./src/jdw/JdwPreview.tsx",
+    "./jdw/preview-viewport": "./src/jdw/JdwPreviewViewport.tsx",
     "./jdw/samples": "./src/jdw/fixtures/jdw-sample-screens.ts",
-    "./jdw/config": "./src/json-config/index.ts",
+    "./json-config": "./src/json-config/index.ts",
     "./widget-tree": "./src/widget-tree/index.ts",
     "./widget-asset": "./src/widget-asset/index.ts",
     "./widget-studio": "./src/widget-studio/index.ts",
-    "./styles.css": "./src/styles.css"
+    "./styles.css": "./src/styles.css",
+    "./workbench-menu-surfaces.css": "./src/workbench-menu-surfaces.css"
   },
   "files": [
     "src",
     "!src/workbench/demo",
+    "!src/workbench/story",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
     "!src/**/*.stories.ts",
@@ -42,28 +56,23 @@
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
     "@vscode/codicons": "^0.0.45",
-    "@workbench-kit/adapters": "0.0.2-prototype.0.1.4",
-    "@workbench-kit/contracts": "0.0.2-prototype.0.1.4",
-    "@workbench-kit/runtime": "0.0.2-prototype.0.1.4",
-    "@workbench-kit/services": "0.0.2-prototype.0.1.4",
-    "@workbench-kit/workspace": "0.0.2-prototype.0.1.4",
-    "@workbench-kit/tokens": "0.0.2-prototype.0.1.4",
-    "@workbench-kit/platform": "0.0.2-prototype.0.1.4",
-    "@workbench-kit/jdw": "0.0.2-prototype.0.1.4"
+    "remark-gfm": "^4.0.1",
+    "rehype-sanitize": "^6.0.0",
+    "@workbench-kit/adapters": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/monaco": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/contracts": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/platform": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/runtime": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/services": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/tokens": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/workspace": "0.0.2-prototype.0.2.11",
+    "@workbench-kit/jdw": "0.0.2-prototype.0.2.11"
   },
   "peerDependencies": {
-    "@monaco-editor/react": "^4.7.0",
-    "monaco-editor": "^0.55.1",
-    "react-markdown": "^10.1.0",
-    "react": "^19.0.0"
+    "react": "^19.0.0",
+    "react-markdown": "^10.1.0"
   },
   "peerDependenciesMeta": {
-    "@monaco-editor/react": {
-      "optional": true
-    },
-    "monaco-editor": {
-      "optional": true
-    },
     "react-markdown": {
       "optional": true
     }
@@ -81,6 +90,7 @@
   },
   "scripts": {
     "test": "pnpm exec vitest run --config ../../vitest.config.ts src/widget-tree",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:exact-optional": "tsc -p typecheck-exact-optional/tsconfig.emit.json && tsc -p typecheck-exact-optional/tsconfig.json --noEmit"
   }
 }

package/src/brand/TilepaperAppIcon.tsx

@@ -0,0 +1,181 @@
+import { useId, type SVGProps } from 'react';
+import { cx } from '../utils/cx';
+import {
+  TILEPAPER_ICON_CANVAS,
+  TILEPAPER_ICON_GRADIENTS,
+  TILEPAPER_ICON_GRID,
+  TILEPAPER_ICON_ROOT_ELEVATION,
+  TILEPAPER_ICON_ROOT_PANEL,
+  TILEPAPER_ICON_TILES,
+  tilepaperPaperFoldPaths,
+} from './tilepaper-app-icon-geometry.js';
+
+export type TilepaperAppIconProps = Omit<SVGProps<SVGSVGElement>, 'viewBox'> & {
+  /** Flat rendering for small surfaces (e.g. titlebar) where elevation blur reads muddy. */
+  compact?: boolean;
+};
+
+export function TilepaperAppIcon({ className, compact = false, ...props }: TilepaperAppIconProps) {
+  const idPrefix = `tilepaper-icon-${useId().replace(/:/g, '')}`;
+  const bgId = `${idPrefix}-bg`;
+  const panelId = `${idPrefix}-panel`;
+  const elevationId = `${idPrefix}-elevation`;
+  const blueId = `${idPrefix}-blue`;
+  const paperId = `${idPrefix}-paper`;
+  const tealId = `${idPrefix}-teal`;
+  const violetId = `${idPrefix}-violet`;
+  const { tileRx, tileSize } = TILEPAPER_ICON_GRID;
+  const fold = tilepaperPaperFoldPaths(
+    TILEPAPER_ICON_TILES.paper.x,
+    TILEPAPER_ICON_TILES.paper.y,
+    tileSize,
+  );
+
+  return (
+    <svg
+      aria-hidden="true"
+      className={cx('tilepaper-app-icon', className)}
+      fill="none"
+      viewBox={`0 0 ${TILEPAPER_ICON_CANVAS.size} ${TILEPAPER_ICON_CANVAS.size}`}
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <defs>
+        {compact ? null : (
+          <filter
+            id={elevationId}
+            x="-12%"
+            y="-8%"
+            width="124%"
+            height="128%"
+            colorInterpolationFilters="sRGB"
+          >
+            <feDropShadow
+              dx="0"
+              dy={TILEPAPER_ICON_ROOT_ELEVATION.dy}
+              floodColor={TILEPAPER_ICON_ROOT_ELEVATION.floodColor}
+              floodOpacity={TILEPAPER_ICON_ROOT_ELEVATION.floodOpacity}
+              stdDeviation={TILEPAPER_ICON_ROOT_ELEVATION.stdDeviation}
+            />
+          </filter>
+        )}
+        <linearGradient
+          id={bgId}
+          x1={TILEPAPER_ICON_GRADIENTS.bg.x1}
+          x2={TILEPAPER_ICON_GRADIENTS.bg.x2}
+          y1={TILEPAPER_ICON_GRADIENTS.bg.y1}
+          y2={TILEPAPER_ICON_GRADIENTS.bg.y2}
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset="0" stopColor="#0A1020" />
+          <stop offset="1" stopColor="#121C33" />
+        </linearGradient>
+        <linearGradient
+          id={panelId}
+          x1={TILEPAPER_ICON_GRADIENTS.panel.x1}
+          x2={TILEPAPER_ICON_GRADIENTS.panel.x2}
+          y1={TILEPAPER_ICON_GRADIENTS.panel.y1}
+          y2={TILEPAPER_ICON_GRADIENTS.panel.y2}
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset="0" stopColor="#1A2C4D" />
+          <stop offset="0.42" stopColor="#162844" />
+          <stop offset="1" stopColor="#111D35" />
+        </linearGradient>
+        <linearGradient
+          id={blueId}
+          x1={TILEPAPER_ICON_GRADIENTS.blue.x1}
+          x2={TILEPAPER_ICON_GRADIENTS.blue.x2}
+          y1={TILEPAPER_ICON_GRADIENTS.blue.y1}
+          y2={TILEPAPER_ICON_GRADIENTS.blue.y2}
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset="0" stopColor="#5D88FF" />
+          <stop offset="1" stopColor="#3158D6" />
+        </linearGradient>
+        <linearGradient
+          id={paperId}
+          x1={TILEPAPER_ICON_GRADIENTS.paper.x1}
+          x2={TILEPAPER_ICON_GRADIENTS.paper.x2}
+          y1={TILEPAPER_ICON_GRADIENTS.paper.y1}
+          y2={TILEPAPER_ICON_GRADIENTS.paper.y2}
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset="0" stopColor="#FFF9EE" />
+          <stop offset="1" stopColor="#DDD9D1" />
+        </linearGradient>
+        <linearGradient
+          id={tealId}
+          x1={TILEPAPER_ICON_GRADIENTS.teal.x1}
+          x2={TILEPAPER_ICON_GRADIENTS.teal.x2}
+          y1={TILEPAPER_ICON_GRADIENTS.teal.y1}
+          y2={TILEPAPER_ICON_GRADIENTS.teal.y2}
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset="0" stopColor="#2FD6C1" />
+          <stop offset="1" stopColor="#149685" />
+        </linearGradient>
+        <linearGradient
+          id={violetId}
+          x1={TILEPAPER_ICON_GRADIENTS.violet.x1}
+          x2={TILEPAPER_ICON_GRADIENTS.violet.x2}
+          y1={TILEPAPER_ICON_GRADIENTS.violet.y1}
+          y2={TILEPAPER_ICON_GRADIENTS.violet.y2}
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset="0" stopColor="#8A67FF" />
+          <stop offset="1" stopColor="#5D3AC8" />
+        </linearGradient>
+      </defs>
+      <rect
+        width={TILEPAPER_ICON_CANVAS.size}
+        height={TILEPAPER_ICON_CANVAS.size}
+        rx={TILEPAPER_ICON_CANVAS.rx}
+        fill={`url(#${bgId})`}
+      />
+      <rect
+        filter={compact ? undefined : `url(#${elevationId})`}
+        fill={`url(#${panelId})`}
+        height={TILEPAPER_ICON_ROOT_PANEL.size}
+        rx={TILEPAPER_ICON_ROOT_PANEL.rx}
+        width={TILEPAPER_ICON_ROOT_PANEL.size}
+        x={TILEPAPER_ICON_ROOT_PANEL.x}
+        y={TILEPAPER_ICON_ROOT_PANEL.y}
+      />
+      <rect
+        x={TILEPAPER_ICON_TILES.blue.x}
+        y={TILEPAPER_ICON_TILES.blue.y}
+        width={tileSize}
+        height={tileSize}
+        rx={tileRx}
+        fill={`url(#${blueId})`}
+      />
+      <rect
+        x={TILEPAPER_ICON_TILES.teal.x}
+        y={TILEPAPER_ICON_TILES.teal.y}
+        width={tileSize}
+        height={tileSize}
+        rx={tileRx}
+        fill={`url(#${tealId})`}
+      />
+      <rect
+        x={TILEPAPER_ICON_TILES.violet.x}
+        y={TILEPAPER_ICON_TILES.violet.y}
+        width={tileSize}
+        height={tileSize}
+        rx={tileRx}
+        fill={`url(#${violetId})`}
+      />
+      <rect
+        x={TILEPAPER_ICON_TILES.paper.x}
+        y={TILEPAPER_ICON_TILES.paper.y}
+        width={tileSize}
+        height={tileSize}
+        rx={tileRx}
+        fill={`url(#${paperId})`}
+      />
+      <path d={fold.highlight} fill="white" fillOpacity="0.92" />
+      <path d={fold.shadow} fill="#C9C3B7" fillOpacity="0.74" />
+    </svg>
+  );
+}

package/src/brand/index.ts

@@ -0,0 +1,2 @@
+export { TilepaperAppIcon } from './TilepaperAppIcon';
+export type { TilepaperAppIconProps } from './TilepaperAppIcon';

package/src/brand/tilepaper-app-icon-geometry.ts

@@ -0,0 +1,201 @@
+/** Shared workbench app icon layout (1024 canvas, Material-style root surface). */
+export const TILEPAPER_ICON_CANVAS_SIZE = 1024;
+
+const REFERENCE_TILE_SIZE = 314;
+/** Unified squircle radius — bumped for a softer, rounder Material feel. */
+const REFERENCE_TILE_RX = 116;
+
+/** Base rhythm for canvas → root panel inset. */
+export const TILEPAPER_ICON_SPACING = 48;
+
+/** Pulls the motif slightly toward the canvas center (px): wider outer rim, tighter tile grid. */
+export const TILEPAPER_ICON_CENTER_CLUSTER = 8;
+
+/** Ambient backdrop around the elevated root surface. */
+export const TILEPAPER_ICON_CANVAS_MARGIN =
+  TILEPAPER_ICON_SPACING + TILEPAPER_ICON_CENTER_CLUSTER / 2;
+
+/** Inset of the 4 tiles inside the root surface. */
+export const TILEPAPER_ICON_GRID_MARGIN = TILEPAPER_ICON_SPACING - TILEPAPER_ICON_CENTER_CLUSTER;
+export const TILEPAPER_ICON_GRID_GAP = TILEPAPER_ICON_SPACING - TILEPAPER_ICON_CENTER_CLUSTER;
+
+/** Material-style elevation for the root surface panel. */
+export const TILEPAPER_ICON_ROOT_ELEVATION = {
+  dy: 8,
+  floodColor: '#020617',
+  floodOpacity: 0.42,
+  stdDeviation: 12,
+} as const;
+
+const TILE_GRADIENT_OFFSETS = {
+  x1: 20,
+  x2: 250,
+  y1: 22,
+  y2: 262,
+} as const;
+
+const panelSize = TILEPAPER_ICON_CANVAS_SIZE - TILEPAPER_ICON_CANVAS_MARGIN * 2;
+const panelX = TILEPAPER_ICON_CANVAS_MARGIN;
+const panelY = TILEPAPER_ICON_CANVAS_MARGIN;
+const tileSize = (panelSize - TILEPAPER_ICON_GRID_MARGIN * 2 - TILEPAPER_ICON_GRID_GAP) / 2;
+
+/** Same absolute corner radius on every rounded rect (matches the 4 tiles). */
+export const TILEPAPER_ICON_UNIFIED_RX = REFERENCE_TILE_RX;
+
+const panelRx = TILEPAPER_ICON_UNIFIED_RX;
+const tileRx = TILEPAPER_ICON_UNIFIED_RX;
+const tileOrigin = panelX + TILEPAPER_ICON_GRID_MARGIN;
+
+const gradientOffsetScale = tileSize / REFERENCE_TILE_SIZE;
+const gradientOffsets = {
+  x1: Math.round(TILE_GRADIENT_OFFSETS.x1 * gradientOffsetScale),
+  x2: Math.round(TILE_GRADIENT_OFFSETS.x2 * gradientOffsetScale),
+  y1: Math.round(TILE_GRADIENT_OFFSETS.y1 * gradientOffsetScale),
+  y2: Math.round(TILE_GRADIENT_OFFSETS.y2 * gradientOffsetScale),
+};
+
+export const TILEPAPER_ICON_CANVAS = {
+  size: TILEPAPER_ICON_CANVAS_SIZE,
+  rx: TILEPAPER_ICON_UNIFIED_RX,
+} as const;
+
+/** Material root surface — the primary app panel sitting above the backdrop. */
+export const TILEPAPER_ICON_ROOT_PANEL = {
+  x: panelX,
+  y: panelY,
+  size: panelSize,
+  rx: panelRx,
+} as const;
+
+export const TILEPAPER_ICON_GRID = {
+  margin: TILEPAPER_ICON_GRID_MARGIN,
+  gap: TILEPAPER_ICON_GRID_GAP,
+  tileSize,
+  tileRx,
+} as const;
+
+export const TILEPAPER_ICON_TILES = {
+  blue: { x: tileOrigin, y: tileOrigin },
+  paper: { x: tileOrigin + tileSize + TILEPAPER_ICON_GRID_GAP, y: tileOrigin },
+  teal: { x: tileOrigin, y: tileOrigin + tileSize + TILEPAPER_ICON_GRID_GAP },
+  violet: {
+    x: tileOrigin + tileSize + TILEPAPER_ICON_GRID_GAP,
+    y: tileOrigin + tileSize + TILEPAPER_ICON_GRID_GAP,
+  },
+} as const;
+
+export function tilepaperRootElevationFilterMarkup(filterId = 'root-elevation'): string {
+  const { dy, floodColor, floodOpacity, stdDeviation } = TILEPAPER_ICON_ROOT_ELEVATION;
+
+  return `<filter id="${filterId}" x="-12%" y="-8%" width="124%" height="128%" color-interpolation-filters="sRGB">
+      <feDropShadow dx="0" dy="${dy}" stdDeviation="${stdDeviation}" flood-color="${floodColor}" flood-opacity="${floodOpacity}" />
+    </filter>`;
+}
+
+/** Scale fold geometry from the original 286px tile art. */
+export function tilepaperPaperFoldPaths(paperX: number, paperY: number, tileSizePx: number) {
+  const scale = tileSizePx / 286;
+  const inset = Math.round(84 * scale);
+  const foldStart = Math.round(88 * scale);
+  const shadowStart = Math.round(103 * scale);
+  const curveOffset = Math.round(37.608 * scale);
+
+  const right = paperX + tileSizePx;
+  const foldX = right - foldStart;
+  const shadowX = right - shadowStart;
+
+  return {
+    highlight: `M${foldX} ${paperY}H${foldX + 4}C${right - curveOffset} ${paperY} ${right} ${paperY + curveOffset} ${right} ${paperY + inset}V${paperY + inset + 4}L${foldX} ${paperY}Z`,
+    shadow: `M${shadowX} ${paperY}H${foldX}L${right} ${paperY + inset}V${paperY + shadowStart}L${shadowX} ${paperY}Z`,
+  };
+}
+
+const panelGradientInset = 18;
+
+export const TILEPAPER_ICON_GRADIENTS = {
+  /** Dark ambient behind the elevated root surface. */
+  bg: { x1: 512, x2: 512, y1: 72, y2: 952 },
+  /** Material surface — slightly brighter toward the top edge. */
+  panel: {
+    x1: 512,
+    x2: 512,
+    y1: panelY + panelGradientInset,
+    y2: panelY + panelSize - panelGradientInset,
+  },
+  blue: {
+    x1: TILEPAPER_ICON_TILES.blue.x + gradientOffsets.x1,
+    x2: TILEPAPER_ICON_TILES.blue.x + gradientOffsets.x2,
+    y1: TILEPAPER_ICON_TILES.blue.y + gradientOffsets.y1,
+    y2: TILEPAPER_ICON_TILES.blue.y + gradientOffsets.y2,
+  },
+  paper: {
+    x1: 512 + (512 - (TILEPAPER_ICON_TILES.blue.x + gradientOffsets.x2)),
+    x2: 512 + (512 - (TILEPAPER_ICON_TILES.blue.x + gradientOffsets.x1)),
+    y1: TILEPAPER_ICON_TILES.blue.y + gradientOffsets.y1,
+    y2: TILEPAPER_ICON_TILES.blue.y + gradientOffsets.y2,
+  },
+  teal: {
+    x1: TILEPAPER_ICON_TILES.blue.x + gradientOffsets.x1,
+    x2: TILEPAPER_ICON_TILES.blue.x + gradientOffsets.x2,
+    y1: 512 + (512 - (TILEPAPER_ICON_TILES.blue.y + gradientOffsets.y2)),
+    y2: 512 + (512 - (TILEPAPER_ICON_TILES.blue.y + gradientOffsets.y1)),
+  },
+  violet: {
+    x1: 512 + (512 - (TILEPAPER_ICON_TILES.blue.x + gradientOffsets.x2)),
+    x2: 512 + (512 - (TILEPAPER_ICON_TILES.blue.x + gradientOffsets.x1)),
+    y1: 512 + (512 - (TILEPAPER_ICON_TILES.blue.y + gradientOffsets.y2)),
+    y2: 512 + (512 - (TILEPAPER_ICON_TILES.blue.y + gradientOffsets.y1)),
+  },
+} as const;
+
+/** Static favicon snapshot (keep in sync with geometry helpers above). */
+export function renderTilepaperAppIconSvgMarkup(): string {
+  const fold = tilepaperPaperFoldPaths(
+    TILEPAPER_ICON_TILES.paper.x,
+    TILEPAPER_ICON_TILES.paper.y,
+    TILEPAPER_ICON_GRID.tileSize,
+  );
+  const { bg, panel, blue, paper, teal, violet } = TILEPAPER_ICON_GRADIENTS;
+  const { tileSize: t, tileRx: tr } = TILEPAPER_ICON_GRID;
+  const root = TILEPAPER_ICON_ROOT_PANEL;
+
+  return `<svg fill="none" viewBox="0 0 1024 1024" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    ${tilepaperRootElevationFilterMarkup('root-elevation')}
+    <linearGradient id="bg" x1="${bg.x1}" x2="${bg.x2}" y1="${bg.y1}" y2="${bg.y2}" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#0A1020" />
+      <stop offset="1" stop-color="#121C33" />
+    </linearGradient>
+    <linearGradient id="panel" x1="${panel.x1}" x2="${panel.x2}" y1="${panel.y1}" y2="${panel.y2}" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#1A2C4D" />
+      <stop offset="0.42" stop-color="#162844" />
+      <stop offset="1" stop-color="#111D35" />
+    </linearGradient>
+    <linearGradient id="blue" x1="${blue.x1}" x2="${blue.x2}" y1="${blue.y1}" y2="${blue.y2}" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#5D88FF" />
+      <stop offset="1" stop-color="#3158D6" />
+    </linearGradient>
+    <linearGradient id="paper" x1="${paper.x1}" x2="${paper.x2}" y1="${paper.y1}" y2="${paper.y2}" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#FFF9EE" />
+      <stop offset="1" stop-color="#DDD9D1" />
+    </linearGradient>
+    <linearGradient id="teal" x1="${teal.x1}" x2="${teal.x2}" y1="${teal.y1}" y2="${teal.y2}" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#2FD6C1" />
+      <stop offset="1" stop-color="#149685" />
+    </linearGradient>
+    <linearGradient id="violet" x1="${violet.x1}" x2="${violet.x2}" y1="${violet.y1}" y2="${violet.y2}" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#8A67FF" />
+      <stop offset="1" stop-color="#5D3AC8" />
+    </linearGradient>
+  </defs>
+  <rect width="${TILEPAPER_ICON_CANVAS.size}" height="${TILEPAPER_ICON_CANVAS.size}" rx="${TILEPAPER_ICON_CANVAS.rx}" fill="url(#bg)" />
+  <rect x="${root.x}" y="${root.y}" width="${root.size}" height="${root.size}" rx="${root.rx}" fill="url(#panel)" filter="url(#root-elevation)" />
+  <rect x="${TILEPAPER_ICON_TILES.blue.x}" y="${TILEPAPER_ICON_TILES.blue.y}" width="${t}" height="${t}" rx="${tr}" fill="url(#blue)" />
+  <rect x="${TILEPAPER_ICON_TILES.teal.x}" y="${TILEPAPER_ICON_TILES.teal.y}" width="${t}" height="${t}" rx="${tr}" fill="url(#teal)" />
+  <rect x="${TILEPAPER_ICON_TILES.violet.x}" y="${TILEPAPER_ICON_TILES.violet.y}" width="${t}" height="${t}" rx="${tr}" fill="url(#violet)" />
+  <rect x="${TILEPAPER_ICON_TILES.paper.x}" y="${TILEPAPER_ICON_TILES.paper.y}" width="${t}" height="${t}" rx="${tr}" fill="url(#paper)" />
+  <path d="${fold.highlight}" fill="white" fill-opacity="0.92" />
+  <path d="${fold.shadow}" fill="#C9C3B7" fill-opacity="0.74" />
+</svg>
+`;
+}

package/src/icons/WorkbenchIcon.tsx

@@ -0,0 +1,57 @@
+import type { HTMLAttributes } from 'react';
+import { Codicon } from '../primitives/codicon/Codicon';
+import { useWorkbenchIconResolver } from './WorkbenchIconContext';
+import {
+  isWorkbenchIconDescriptor,
+  normalizeWorkbenchIconDescriptor,
+} from './resolveWorkbenchIcon';
+import type { WorkbenchIconInput } from './types';
+
+export interface WorkbenchIconProps extends HTMLAttributes<HTMLSpanElement> {
+  icon: WorkbenchIconInput;
+  /** When set, exposes the icon to assistive tech instead of aria-hidden. */
+  label?: string | undefined;
+}
+
+/**
+ * Renders a workbench icon. String ids default to codicon; hosts may override
+ * string resolution via `WorkbenchIconProvider`.
+ */
+export function WorkbenchIcon({ className, icon, label, ...props }: WorkbenchIconProps) {
+  const resolveStringIcon = useWorkbenchIconResolver();
+  const normalized = normalizeWorkbenchIconDescriptor(icon);
+
+  if (isWorkbenchIconDescriptor(normalized)) {
+    if (normalized.kind === 'node') {
+      return (
+        <span
+          aria-hidden={label ? undefined : true}
+          aria-label={label}
+          className={className}
+          {...props}
+        >
+          {normalized.node}
+        </span>
+      );
+    }
+
+    const codiconName = normalized.name;
+    const resolved = resolveStringIcon?.(codiconName, { className, label });
+    if (resolved !== undefined) {
+      return <>{resolved}</>;
+    }
+
+    return <Codicon className={className} icon={codiconName} label={label} />;
+  }
+
+  return (
+    <span
+      aria-hidden={label ? undefined : true}
+      aria-label={label}
+      className={className}
+      {...props}
+    >
+      {normalized}
+    </span>
+  );
+}

package/src/icons/WorkbenchIconContext.tsx

@@ -0,0 +1,25 @@
+import { createContext, useContext, type ReactNode } from 'react';
+import type { WorkbenchIconResolver } from './types';
+
+export interface WorkbenchIconProviderProps {
+  children: ReactNode;
+  /**
+   * When set, maps string icon ids to render output.
+   * Unhandled ids should fall back to codicon rendering (see `WorkbenchIcon`).
+   */
+  resolveStringIcon?: WorkbenchIconResolver | undefined;
+}
+
+const WorkbenchIconContext = createContext<WorkbenchIconResolver | undefined>(undefined);
+
+export function WorkbenchIconProvider({ children, resolveStringIcon }: WorkbenchIconProviderProps) {
+  return (
+    <WorkbenchIconContext.Provider value={resolveStringIcon}>
+      {children}
+    </WorkbenchIconContext.Provider>
+  );
+}
+
+export function useWorkbenchIconResolver(): WorkbenchIconResolver | undefined {
+  return useContext(WorkbenchIconContext);
+}