Claude Workspace Package

@maya/claude-workspace is the private Claude Web product-kit package for the workspace composition platform. WCP-012 locked the package boundary, WCP-013 modeled Claude product defaults as composition fixtures, and WCP-019 implements a private package root with exported Claude built-in descriptors plus a deterministic runtime builder.

The durable responsibility split remains:

Host applications resolve runtime.
@maya/assistant-composition composes workspace structure.
@maya/assistant-ui executes React rendering through a scoped render runtime.
@maya/claude-workspace packages Claude Web product defaults.

Status

WCP-019 implements a private package root. It is still not a publishable npm artifact, and it still does not move Claude React page components out of @maya/assistant-ui.

v0 Installability

This package is not installable from npm in v0. It is private: true, built by pnpm build:packages, and consumed only by monorepo hosts, workspace-private guide consumers, and workspace-private smoke consumers from built workspace output. Possible publishability opens only if tools/workspace-package-registry.mjs explicitly changes its npmPublishable classification to true.

Implemented In WCP-019:

package root at projects/claude-workspace
public exports for claudeWorkspaceBuiltinOwner, claudeWorkspaceBuiltins, claudeWorkspaceDefaultPolicy, and createClaudeWorkspaceRuntime
package metadata export at @maya/claude-workspace/package.json
public .d.ts contract snapshot
source-boundary, public API, package-boundary, CODEOWNERS, and docs gates
deterministic builder path through composeWorkspace and createReactRenderRuntime

Implemented In WCP-025:

workspace-private product-kit consumer smoke for createClaudeWorkspaceRuntime
compile-only consumer coverage for AssistantWorkspace with explicit composition and scoped renderRuntime
manifest-driven public package entrypoint checks for Claude workspace and Data Lab imports
missing module render pack coverage failure with WCP-HANDLE-001

Deferred Beyond WCP-019:

ClaudeWorkspace high-level React entry
ClaudeWorkspaceRenderer low-level React entry
Claude built-in React render pack exports
@maya/claude-workspace/styles.css
npm publishability
host grant or configuration resolution helpers

React facades, built-in render packs, CSS asset exports, and npm publishability are not scheduled in v0. WCP-025 proves the current builder boundary from a workspace-private consumer using documented workspace package exports only; it does not make @maya/claude-workspace a publishable npm artifact.

Dependency Boundary

The package may depend on:

@maya/assistant-composition for composeWorkspace, contribution descriptor types, policies, diagnostics, and WorkspaceComposition
@maya/assistant-ui for scoped React render-runtime types and createReactRenderRuntime

It must not depend on:

@maya/assistant-protocol
projects/web
projects/claude-webbackend
host adapters, backend adapters, route loaders, auth clients, storage adapters, or fetch wrappers
package auto-discovery, remote ESM, iframe execution, module federation, or import-time registration

Dependency direction is one way:

@maya/claude-workspace -> @maya/assistant-composition
@maya/claude-workspace -> @maya/assistant-ui/render-runtime

@maya/assistant-composition and @maya/assistant-ui must not import @maya/claude-workspace.

Owned Product Defaults

@maya/claude-workspace owns Claude-specific defaults that should not live in the headless kernel or the generic renderer:

built-in owner identity, using builtin-claude-workspace
Claude route descriptors
Claude sidebar descriptors
Claude configuration surfaces
Claude integration surfaces
Claude transcript renderer claims and appenders
Claude tool renderer descriptors
Claude activity renderer descriptors
Claude fallback surfaces for non-ready states
Claude default composition policy

Ownership means descriptors and render handles are declared here. Host data, controllers, backend calls, credentials, persistent settings, tenant policy, user permissions, and runtime status resolution stay outside the package.

Descriptor Fixture Boundary

WCP-013 proved that Claude product defaults can enter composeWorkspace({ builtins, modules, policy }) through the same descriptor path as modules. WCP-019 exports that descriptor inventory from the package. The owner is builtin-claude-workspace with package identity @maya/claude-workspace.

The locked fixture inventory is:

fixture-claude-builtins-default-composition
fixture-kernel-builtins-and-modules-same-pipeline
fixture-builtin-any-non-ready-fallback-omitted
fixture-builtin-module-route-conflict-diagnostic
fixture-builtin-module-renderer-conflict-diagnostic
fixture-builtin-owner-shape-diagnostics

The default descriptors cover seven routes, seven sidebar items, eleven configuration surfaces, nine integration surfaces, one custom message renderer, six message appenders, two tool renderers, three activity renderers, and five status-specific fallback surfaces. pnpm verify:claude-builtins-fixture-parity compares the fixture's route, sidebar, settings-hash, and Customize-view descriptors against built @maya/assistant-ui/routes metadata while React component migration remains separate.

Export Status

Export	Status	Purpose
`createClaudeWorkspaceRuntime`	implemented	Combines Claude built-ins, host-resolved modules, explicit policy, and explicit render packs into composition plus scoped React render runtime.
`claudeWorkspaceBuiltins`	implemented	Built-in contribution set passed to `composeWorkspace({ builtins, modules, policy })`.
`claudeWorkspaceBuiltinOwner`	implemented	Shared owner identity for Claude built-in descriptors and future render packs.
`claudeWorkspaceDefaultPolicy`	implemented	Explicit empty v0 policy, with future policy input limited to `hide`, `reorder`, `replace`, `pathAlias`, and `rendererOverride`.
`CreateClaudeWorkspaceRuntimeOptions`	implemented	Builder input type for host-resolved modules, policy, explicit render packs, render-runtime options, and supported composition versions.
`ClaudeWorkspaceRuntime`	implemented	Builder result type for composition, scoped render runtime, diagnostics, policy effects, required handles, and coverage.
`ClaudeWorkspaceRenderRuntimeOptions`	implemented	Render-runtime options accepted by the builder after excluding the `packs` field.
`@maya/claude-workspace/package.json`	implemented	Tooling metadata for the private workspace package.
`ClaudeWorkspace`	deferred	Developer-friendly React entry that must call the same runtime builder and renderer.
`ClaudeWorkspaceRenderer`	deferred	Low-level React renderer for explicit `WorkspaceComposition` plus explicit scoped render runtime.
Claude built-in render pack	deferred	Handle providers for Claude built-in pages, surfaces, renderers, and fallbacks.
`@maya/claude-workspace/styles.css`	deferred	Product CSS composition under `.aui-root`.

Runtime Builder

createClaudeWorkspaceRuntime({ modules, policy, renderPacks, renderRuntimeOptions }) is the current executable entry. It:

calls composeWorkspace({ builtins: [claudeWorkspaceBuiltins], modules, policy })
creates a scoped React render runtime from explicit renderPacks
validates WorkspaceComposition.requiredRenderHandles
returns composition diagnostics, policy effects, required handles, and handle coverage

It requires explicit render packs. It does not discover packages, does not mutate a global render registry, does not resolve grants, does not render React, does not preload components, and does not hide composer diagnostics.

const runtime = createClaudeWorkspaceRuntime({
  modules: resolvedModules,
  policy,
  renderPacks: [hostProvidedClaudeRenderPack, dataLabRenderPack],
  renderRuntimeOptions: { mode: 'test' },
});

Lowest-level generic renderer use remains:

<AssistantWorkspace
  {...workspaceControllers}
  composition={runtime.composition}
  renderRuntime={runtime.renderRuntime}
/>

When React entries land, they must use this same builder and the same render runtime path. They must not bypass composeWorkspace, create a package-level runtime singleton, introduce hidden global state, add package auto-discovery, or make host grant decisions.

Render Pack Ownership

The future Claude render pack owner is builtin-claude-workspace. Its handles must be opaque values consumed by the scoped React render runtime. A render handle can identify a Claude page, surface, tool card, activity card, or fallback renderer, but it cannot contain a React component, callback, dynamic import, loader, or JSX.

Render pack coverage validation belongs to the render runtime. The product kit may pass Claude render packs to that runtime later, but it must not hide missing module render packs or install them automatically.

Host-Owned Runtime

The package receives host-resolved module instances. It does not own:

deployment capability checks
tenant policy
user authorization
API keys, credentials, or secrets
backend health checks
persistent settings
network requests
localStorage or other persistence
audit behavior
protocol mapping

Frontend grants remain UI activation contracts. Backend and host policy remain the real enforcement layer.

Current Surface Migration Map

The canonical WCP-014 surface map is .docs/architecture/workspace-composition-surface-migration-map.md. Later implementation issues must migrate current surfaces into this package boundary through that map without creating a second route or render path.

That map covers current route metadata, route execution, sidebar navigation, host-owned sidebar controls, Settings sections, Settings shell state, Customize surfaces, directory/custom connector surfaces, transcript rendering, message appenders, host-owned message controls, protocol tool cards, generic tool fallback, protocol activity cards, protocol stack sub-cards, workspace status, runtime fallback surfaces, and Claude default composition policy.

It also records explicit v0 gaps, including public-built-in-page-replacement-api, default-user-assistant-text-override, dynamic-and-hash-route-contributions, arbitrary-sidebar-slots, settings-search-provider-extension, project-detail-subroute-extension, protocol-stack-sub-card-claim-taxonomy, module-owned-persistent-settings-or-storage, runtime-untrusted-plugin-loading, and suspense-loading-as-runtime-fallback.

The first safe visual parity milestone is Descriptor-To-Render Shell Parity: route, sidebar, Settings, and Customize shell selection may be driven from WorkspaceComposition, but handles must still resolve to existing Claude UI React surfaces and host-owned controllers until visual parity is proven.

Verification

Changing this boundary requires:

pnpm --filter @maya/claude-workspace build
pnpm --filter @maya/claude-workspace typecheck
pnpm --filter @maya/claude-workspace test
pnpm verify:claude-workspace-runtime
node tools/verify-public-api-surface.mjs
node tools/verify-docs-structure.mjs
node tools/verify-docs-api-parity.mjs
pnpm verify:claude-builtins-fixture-parity
pnpm verify:surface-migration-map
pnpm verify:docs-dx
pnpm verify:source-boundaries

Canonical package boundary documentation stays in .docs/packages/claude-workspace.md. Package-root README copies, generated dist docs, and copied package docs are not allowed; the package must keep no second documentation truth.

Status​

v0 Installability​

Dependency Boundary​

Owned Product Defaults​

Descriptor Fixture Boundary​

Export Status​

Runtime Builder​

Render Pack Ownership​

Host-Owned Runtime​

Current Surface Migration Map​

Verification​