open-index/open-npm huggingface dataset:
npm package: @mdwrk/extension-catalog-hello
Description: Sample third-party external extension used to validate catalog discovery, installation, trust, and runtime activation.
Author: Jacob Stewart
Latest version: 1.1.1

# @mdwrk/extension-catalog-hello

Sample third-party external extension package used to validate the signed catalog installation path.

## Manifest and compatibility

- manifest export: `./manifest`
- manifest kind: external
- compatibility declarations: host API, runtime, app, and theme contract ranges are declared in `src/manifest.ts`
- distribution mode: external signed catalog artifact

## Capabilities

This sample demonstrates a deliberately small capability footprint:

- `view.register`
- `actionRail.register`
- `notification.publish`
- `settings.read`

## Settings schema

The sample manifest includes a minimal settings schema with a single `greeting` string field.
That keeps the package suitable as a catalog/install/activation fixture without dragging in extra runtime surface area.

## i18n readiness

The manifest uses `I18nLabel` descriptors for display name, description, view title, and action-rail title.
The shipped catalog sample keeps `en` as the only bundled locale, which is intentional for the minimal external-fixture path.

## Lifecycle and host/runtime tests

- `tests/run-smoke.mjs` validates the manifest export and extension entry shape
- `tests/integration.mjs` activates the extension against a mock host/runtime context and verifies view registration, action-rail registration, and notification behavior

## Installation / configuration guidance

This package is **not bundled** into `apps/client`.
It is published as a source package and transformed by the CI catalog/signing pipeline into an external browser-installable artifact.
Use it when validating:

- external catalog metadata generation
- signed-manifest verification
- install/enable/activate flows in the runtime
- minimal schema-backed settings behavior for external extensions

## API/reference docs

See the generated reference page at:

- `docs/reference/packages/mdwrk-extension-catalog-hello.md`
npm package: @mdwrk/extension-gemini-agent
Description: First-party Gemini workflow extension for Markdown Workspace with read-only document operations, draft-based writeback, and a bundled operator view.
Author: Jacob Stewart
Latest version: 1.1.2

# @mdwrk/extension-gemini-agent

First-party Gemini workflow extension for Markdown Workspace.

## Manifest and compatibility

- manifest export: `./manifest`
- bundled entry export: `./bundled`
- compatibility declarations: host API, runtime, app, theme contract, renderer, and editor ranges are declared in `src/manifest.ts`
- lifecycle model: bundled first-party extension activated through `@mdwrk/extension-runtime`

## Capabilities

- reads the active markdown document
- reads the current selection
- registers commands, a modal view, and an action-rail entry
- publishes notifications and diagnostics
- reads and writes extension configuration
- performs network fetches for Gemini API requests
- supports opt-in editor writeback through explicit user commands only

## Settings schema

The package ships a real settings schema with sections for:

- provider / endpoint / model / authentication
- context attachment behavior
- writeback control

Source anchors:

- `src/settings.ts`
- `src/manifest.ts`

## i18n readiness

The package ships package-local locale catalogs and loader definitions:

- `src/i18n.ts`
- `src/locales/en.ts`
- `src/locales/es.ts`

All user-facing labels in the manifest and settings schema are `I18nLabel` descriptors.

## Lifecycle and host/runtime integration tests

- `tests/run-smoke.mjs` exercises manifest structure, prompt building, provider helpers, configuration defaults, and service behavior against a mocked host/runtime context

## Install / configuration guidance

This package is intended for first-party bundling into `apps/client`.
Configuration is done through the shared settings surface after activation.
Writeback remains opt-in and disabled by default.

## API/reference docs

See the generated reference page at:

- `docs/reference/packages/mdwrk-extension-gemini-agent.md`
npm package: @mdwrk/extension-host
Description: Stable host API, lifecycle, and context contracts for Markdown Workspace extensions.
Author: Jacob Stewart
Latest version: 1.0.2

# mdwrk/extension-host

Stable host API, lifecycle, context, and registration contracts for Markdown Workspace extensions.

## Package purpose

This package is the extension-facing boundary for interacting with the host application.

## What it exports

- host API contracts
- extension context contract
- lifecycle contracts
- primitive utility types
- registration contracts for commands, views, components, settings sections, and action rail items
- i18n catalog and locale-loader registration contracts
- theme inspection, bridge, preview, and CSS export contracts

## Authoring rule

Extension packages must use this package rather than importing `apps/client/*` internals directly.

## Important Phase 9 APIs

### i18n
Use:
- `context.registerLocaleCatalog(...)`
- `context.registerLocaleCatalogLoader(...)`
- `host.i18n.ensureLocale()`
- `host.i18n.format(...)`

### theme
Use:
- `host.theme.getTokenMap()`
- `host.theme.getThemeBridge(target)`
- `host.theme.getThemeBridgeVariables(target)`
- `host.theme.previewTheme(...)`
- `host.theme.applyDraft()`
- `host.theme.exportThemeCss(...)`

## Build

```bash
npm run build -w @mdwrk/extension-host
```

## Publishability

This package is structured as a standalone publishable npm package with typed exports and generated build output under `dist/`.
npm package: @mdwrk/extension-language-pack-studio
Description: Bundled language-pack studio extension for Markdown Workspace.
Latest version: 1.0.3

# @mdwrk/extension-language-pack-studio

Bundled language-pack studio extension for Markdown Workspace.

## Capabilities

- pane-first language-pack management for built-in and installed packs
- settings-menu summary content that opens the full workspace pane
- enable / disable all language packs including built-ins
- IndexedDB-backed persistence for installed packs and built-in disablement
- single-pane, split-screen, and collapsible workspace-sidebar layouts
npm package: @mdwrk/extension-manager
Description: First-party bundled operator console extension for browsing, enabling, disabling, diagnosing, and configuring Markdown Workspace extensions.
Author: Jacob Stewart
Latest version: 1.1.7

# @mdwrk/extension-manager

First-party bundled operator console extension for Markdown Workspace.

## Manifest and compatibility

- manifest export: `./manifest`
- bundled entry export: `./bundled`
- compatibility declarations: host API, runtime, app, and theme contract ranges are declared in `src/manifest.ts`
- lifecycle model: bundled first-party extension activated through `@mdwrk/extension-runtime`

## Capabilities

The extension manager visualizes extension runtime state and operator metadata, including:

- bundled and installed extension inventory
- enabled / disabled state
- activation mode and activation status
- compatibility state
- granted and missing capabilities
- runtime diagnostics and last-error state
- schema-driven settings forms for extensions that declare `settingsSchema`

## Settings schema

The package now contributes its own settings section and manifest-backed settings schema.
Those settings cover manager-view defaults such as search, compatibility visibility, and diagnostics display preferences.

Source anchors:

- `src/manifest.ts`
- `src/createExtensionManagerBundledEntry.tsx`

## i18n readiness

The package ships locale labels and locale loaders under:

- `src/i18n.ts`
- `src/locales/en.ts`
- `src/locales/es.ts`

All user-facing manifest/view/settings labels are `I18nLabel` descriptors.

## Lifecycle and host/runtime integration tests

- `tests/extension-manager.test.tsx` exercises the bundled entry, runtime wiring, and extension inventory/state rendering helpers

## Install / configuration guidance

This package is intended for first-party bundling into `apps/client`.
Once active, it becomes the operator console for extension/runtime inventory, compatibility state, diagnostics, and settings visibility.

## API/reference docs

See the generated reference page at:

- `docs/reference/packages/mdwrk-extension-manager.md`
npm package: @mdwrk/extension-manifest
Description: Normative manifest, capability, settings, i18n, and contribution contracts for Markdown Workspace extensions.
Author: Jacob Stewart
Latest version: 1.0.1

# mdwrk/extension-manifest

Normative manifest, catalog, signature, settings, capability, i18n, icon, contribution, distribution, integrity, support, and compatibility contracts for Markdown Workspace extensions.

## Package purpose

This package is the authoring source of truth for extension metadata and manifest structure.

## What it exports

- manifest version constants
- extension manifest interface
- capabilities
- contribution descriptors
- settings schema types
- i18n label types
- icon descriptors
- compatibility declarations
- distribution and integrity metadata
- support declaration types
- external catalog document types
- signed-manifest and trusted-signer types

## Intended consumers

- extension packages
- extension runtime packages
- manifest validators
- catalog/signing tooling
- documentation and schema tooling

## Build

```bash
npm run build -w @mdwrk/extension-manifest
```

## Publishability

This package is structured as a standalone publishable npm package with typed exports and generated build output under `dist/`.
npm package: @mdwrk/extension-runtime
Description: Runtime registry, loader, compatibility checks, activation lifecycle, and persisted state for Markdown Workspace extensions.
Author: Jacob Stewart
Latest version: 1.1.3

# @mdwrk/extension-runtime

Portable extension runtime for Markdown Workspace hosts.

## Runtime responsibilities

- bundled extension registration
- external catalog registration and loading
- manifest validation and compatibility checks
- persisted enabled/config/install state with deterministic namespaced keys
- activation and deactivation lifecycle management
- capability-scoped host wrappers
- runtime diagnostics and state snapshots
- signed-manifest verification and integrity checks
- install / update / remove flows for external extensions
- installed extension cache rehydration

## Public API surface

The runtime exposes methods for:

- registering bundled entries
- registering or loading catalogs
- listing available catalog entries
- installing, updating, and removing external extensions
- enabling/disabling and activating/deactivating extensions
- reading configuration stores and runtime services

## Compatibility declarations

This package depends on the contract packages rather than app internals:

- `@mdwrk/extension-host`
- `@mdwrk/extension-manifest`
- `@mdwrk/theme-contract`

## Lifecycle and integration tests

- `tests/runtime.test.ts` covers lifecycle, install/cache, compatibility, and state-management behavior
- `tests/run-smoke.mjs` covers runtime exports and smoke-level integration
- `tests/prepare-workspace-links.mjs` keeps workspace package links usable for package-local test execution

## Install / host integration guidance

Hosts should provide the runtime with:

- a compliant host API implementation from `@mdwrk/extension-host`
- a registration sink that maps runtime registrations onto host surfaces
- a storage adapter for config/install state
- trust/signing policy for external catalog flows

## API/reference docs

See the generated reference page at:

- `docs/reference/packages/mdwrk-extension-runtime.md`
npm package: @mdwrk/extension-theme-studio
Description: First-party theme authoring extension for Markdown Workspace with token inspection, live renderer/editor previews, apply/revert flow, and export helpers.
Author: Jacob Stewart
Latest version: 1.1.5

# @mdwrk/extension-theme-studio

First-party Theme Studio extension package for Markdown Workspace.

## Manifest and compatibility

- manifest export: `./manifest`
- bundled entry export: `./bundled`
- compatibility declarations: host API, runtime, app, and theme contract ranges are declared in `src/manifest.ts`
- lifecycle model: bundled first-party extension activated through `@mdwrk/extension-runtime`

## Capabilities

- inspect formal theme tokens and stable class contracts
- edit token drafts without importing client internals
- preview renderer/editor bridge behavior against shared package contracts
- apply or revert theme drafts through host theme APIs
- export theme presets as JSON, CSS, and theme-package scaffold artifacts
- register commands, a pane-first workspace view, an action-rail item, and settings-menu content

## Settings schema

The package ships a settings schema covering:

- preview behavior
- export defaults
- package scaffold metadata

Source anchors:

- `src/settings.ts`
- `src/manifest.ts`

## i18n readiness

The package ships package-local locale catalogs and loader definitions:

- `src/i18n.ts`
- `src/locales/en.ts`
- `src/locales/es.ts`

All user-facing manifest/view/settings labels are `I18nLabel` descriptors.

## Lifecycle and host/runtime integration tests

- `tests/run-smoke.mjs` exercises manifest structure, settings resolution, class relationships, export generation, theme bridge previews, and service behavior against a mocked host/runtime context

## Install / configuration guidance

This package is intended for first-party bundling into `apps/client`.
Use it when validating the portable theme/token contract, editor/renderer bridge behavior, and generated theme export artifacts.

## API/reference docs

See the generated reference page at:

- `docs/reference/packages/mdwrk-extension-theme-studio.md`
npm package: @mdwrk/i18n
Description: Shared message descriptors, locale catalogs, and locale registry helpers for Markdown Workspace packages.
Author: Jacob Stewart
Latest version: 1.2.2

# mdwrk/i18n

Shared message descriptor, locale catalog, locale loader, and locale registry helpers for Markdown Workspace packages.

Phase 10 also adds the shared core shell locale helpers used by the client app to restore the shipped core locales `en`, `es`, `fr`, `pt`, and `ur`.

## Core features

- keyed message descriptors
- locale registries with fallback resolution
- namespaced catalog helpers for package-local message keys
- locale loader definitions for lazy per-locale imports

## Example

```ts
import {
  createLocaleRegistry,
  createNamespacedLocaleCatalog,
  loadLocaleCatalogs,
} from "@mdwrk/i18n";

const registry = createLocaleRegistry({ defaultLocale: "en", fallbackLocale: "en" });

const catalogs = await loadLocaleCatalogs({
  locale: "es-MX",
  namespace: "core.extension-manager",
  loaders: {
    en: async () => ({ locale: "en", messages: { "view.title": "Extension Manager" } }),
    es: async () => ({ locale: "es", messages: { "view.title": "Administrador de extensiones" } }),
  },
});

for (const catalog of catalogs) {
  registry.registerCatalog(catalog);
}

registry.setLocale("es-MX");
registry.resolve({
  key: "core.extension-manager.view.title",
  defaultMessage: "Extension Manager",
});
```

## Core shell locale helpers

This package now also exports:

- `CORE_SHELL_SUPPORTED_LOCALES`
- `CORE_SHELL_LOCALE_LOADER_DEFINITION`

These helpers are used by the client runtime to register the core shell locale inventory and to resolve locale fallbacks for the restored language selector surfaces.
npm package: @mdwrk/icons
Description: Shared icon identifiers and icon metadata for Markdown Workspace applications and packages.
Author: Jacob Stewart
Latest version: 1.0.1

# mdwrk/icons

Shared icon identifiers and icon metadata for Markdown Workspace applications and packages.

This package does not force a rendering library. Instead it provides a stable icon identifier and metadata catalog so applications and reusable packages can render icons with Lucide, SVG assets, or another adapter while keeping semantic IDs stable.

## Example

```ts
import { getWorkspaceIconDefinition } from "@mdwrk/icons";

const icon = getWorkspaceIconDefinition("extension.manager");
// => { id: "extension.manager", lucideName: "Puzzle", ... }
```
npm package: @mdwrk/markdown-editor-core
Description: Portable source-mode markdown editor state, selection transforms, command model, and undo/redo history for Markdown Workspace.
Author: Jacob Stewart
Latest version: 1.1.1

# @mdwrk/markdown-editor-core

Portable source-mode Markdown editor primitives for Markdown Workspace.

## Public responsibilities

- selection transforms
- formatting commands
- list/task insertion helpers
- indent/outdent helpers
- history state and undo/redo primitives
- editor class-name contract

## Typed public exports

- root module: `@mdwrk/markdown-editor-core`
- `./types`
- `./class-names`
- `./selection`
- `./transforms`
- `./commands`
- `./history`
- `./version`

## Integration fixtures / examples

- reusable consumer: `examples/editor-basic/`
- client integration: Phase 5 authoring checkpoint
- list/task/continuation behavior demonstrated in the editor example and package-level tests

## Semver / compatibility

- current version: `1.1.0`
- package boundary: editor logic only; no React or app-shell dependency

## Release evidence

- typed exports in `package.json`
- build/typecheck/test scripts in `package.json`
- checkpoint evidence in `artifacts/conformance/latest/`

## API/reference docs

See the generated reference page at:

- `docs/reference/packages/mdwrk-markdown-editor-core.md`
npm package: @mdwrk/markdown-editor-react
Description: React bindings, textarea editor surface, command wiring, history integration, and theme bridge for the Markdown Workspace portable markdown editor.
Author: Jacob Stewart
Latest version: 1.1.1

# @mdwrk/markdown-editor-react

React bindings for the portable Markdown Workspace source editor.

## Public responsibilities

- `MarkdownSourceEditor` React component
- controlled and uncontrolled editor modes
- keyboard shortcut and command wiring
- line-number gutter support
- theme bridge/style helpers
- stylesheet entry for package consumers

## Typed public exports

- root module: `@mdwrk/markdown-editor-react`
- `./types`
- `./theme`
- `./version`
- `./styles/default.css`

## Integration fixtures / examples

- reusable consumer: `examples/editor-basic/`
- client integration: Phase 5 authoring checkpoint
- line-number + task/list example coverage in the editor example app

## Semver / compatibility

- current version: `1.1.0`
- depends on `@mdwrk/markdown-editor-core` public exports rather than private workspace editor wiring

## Release evidence

- typed exports in `package.json`
- build/typecheck/test scripts in `package.json`
- checkpoint evidence in `artifacts/conformance/latest/`

## API/reference docs

See the generated reference page at:

- `docs/reference/packages/mdwrk-markdown-editor-react.md`
npm package: @mdwrk/markdown-renderer-core
Description: Self-contained markdown parsing, CommonMark-core-oriented HTML rendering, heading extraction, and HTML document serialization for MdWork.
Author: Jacob Stewart
Latest version: 1.1.2

# @mdwrk/markdown-renderer-core

Portable Markdown parser/renderer core for Markdown Workspace.

## Public responsibilities

- CommonMark-oriented parsing and AST generation
- default GFM rendering and optional-profile support
- heading extraction and slug generation
- HTML fragment rendering
- HTML document serialization for export/print flows
- raw HTML policy handling and empty-list normalization hooks

## Typed public exports

- root module: `@mdwrk/markdown-renderer-core`
- `./types`
- `./class-names`
- `./slug`
- `./frontmatter`
- `./headings`
- `./pipeline`
- `./html`
- `./engine`
- `./version`

## Integration fixtures / examples

- reusable consumer: `examples/renderer-basic/`
- client integration: `apps/client/tests/phase6-preview-export-policy.mjs`
- GFM/default-profile smoke: package-local test lane
- optional-profile smoke: package-local test lane

## Semver / compatibility

- current version: `1.1.0`
- package boundary: reusable parser/renderer core; must not depend on `apps/client/*`
- compatibility notes are recorded through the repository current-state and checkpoint artifacts

## Release evidence

- typed exports in `package.json`
- build/typecheck/test scripts in `package.json`
- Phase checkpoint evidence in `artifacts/conformance/latest/`

## API/reference docs

See the generated reference page at:

- `docs/reference/packages/mdwrk-markdown-renderer-core.md`
npm package: @mdwrk/markdown-renderer-react
Description: React bindings for the MdWork self-contained markdown renderer checkpoint.
Author: Jacob Stewart
Latest version: 1.1.2

# @mdwrk/markdown-renderer-react

React bindings for the portable Markdown Workspace renderer core.

## Public responsibilities

- `MarkdownRenderer` React component
- renderer theme-style helpers
- static HTML and HTML-document helpers
- default stylesheet for package consumers
- renderer-side bridge-variable mapping from shared theme tokens

## Typed public exports

- root module: `@mdwrk/markdown-renderer-react`
- `./types`
- `./theme`
- `./server`
- `./version`
- `./styles/default.css`

## Integration fixtures / examples

- reusable consumer: `examples/renderer-basic/`
- client integration: `apps/client/tests/phase6-preview-export-policy.mjs`
- theme/token parity evidence: Phase 9 checkpoint artifacts

## Semver / compatibility

- current version: `1.1.0`
- depends on the public renderer-core contract rather than app-private preview wiring
- public consumers should use the exported theme/style helpers rather than private app theme code

## Release evidence

- typed exports in `package.json`
- build/typecheck/test scripts in `package.json`
- Phase checkpoint evidence in `artifacts/conformance/latest/`

## API/reference docs

See the generated reference page at:

- `docs/reference/packages/mdwrk-markdown-renderer-react.md`
npm package: @mdwrk/testing
Description: Shared browser and React test helpers for Markdown Workspace packages.
Author: Jacob Stewart
Latest version: 1.0.1

# mdwrk/testing

Shared browser and timing test helpers for Markdown Workspace packages.

## Exports

- `mdwrk/testing` — browser and timing helpers
- `mdwrk/testing/browser` — memory storage and browser stubs
- `mdwrk/testing/timing` — async timing helpers
- `mdwrk/testing/vitest-setup` — installs common jsdom-friendly browser stubs

## Example

```ts
import { createMemoryStorage } from "@mdwrk/testing/browser";
import { flushMicrotasks } from "@mdwrk/testing/timing";
```
npm package: @mdwrk/theme-contract
Description: Portable token and class-name contract for Markdown Workspace themes, renderers, editors, and extensions.
Author: Jacob Stewart
Latest version: 1.1.1

# mdwrk/theme-contract

Portable token, class-name, and bridge-variable contract for Markdown Workspace themes, renderers, editors, and extensions.

## Package purpose

This package defines the shared styling surface that reusable packages and extensions must target.

## What it exports

- theme contract version
- canonical token names and definitions
- canonical class names and definitions
- canonical renderer/editor bridge-variable definitions
- compatibility metadata
- theme preset and draft shapes

## Derivation source

The initial contract is derived from:
- `apps/client/styles/base/root.css`
- `apps/client/styles/base/markdown.css`
- the extracted editor package surface

## Key contract surfaces

### Tokens
Examples:
- `bg-panel`
- `fg-primary`
- `accent`
- `font-mono`
- `editor-padding`
- `editor-line-height`
- `editor-line-rhythm`
- `line-number-gutter-width`
- `markdown-line-height`
- `markdown-heading-line-height`
- `mobile-rail-expanded-width`
- `mobile-expandable-rail-width`

### Stable renderer classes
Examples:
- `markdown-body`
- `md-table`
- `md-code-block`

### Stable editor classes
Examples:
- `mw-editor`
- `mw-editor-gutter`
- `mw-editor-textarea`

### Bridge variables
Examples:
- renderer: `--mw-bg-surface`, `--mw-fg-primary`, `--mw-code-bg`, `--mw-line-height`, `--mw-heading-line-height`
- editor: `--mwe-bg-surface`, `--mwe-fg-primary`, `--mwe-editor-padding`, `--mwe-line-height`, `--mwe-gutter-width`

## Build

```bash
npm run build -w @mdwrk/theme-contract
```

## Publishability

This package is structured as a standalone publishable npm package with typed exports and generated build output under `dist/`.
npm package: @mdwrk/ui-tokens
Description: Shared CSS tokens, markdown class names, and theme mapping helpers for Markdown Workspace packages and applications.
Author: Jacob Stewart
Latest version: 1.2.1

# mdwrk/ui-tokens

Shared CSS tokens, root variables, markdown/editor class names, and theme mapping helpers for Markdown Workspace applications and packages.

## What this package contains

- the reusable root CSS variable contract
- the reusable markdown rendering stylesheet
- token and class-name re-exports aligned to `mdwrk/theme-contract`
- theme CSS generation helpers for first-party and third-party consumers
- renderer/editor bridge variable helpers
- the Phase 9 rhythm/layout token surfaces used by editor gutters, preview heading rhythm, and responsive shell width

## CSS entry points

- `mdwrk/ui-tokens/styles/index.css`
- `mdwrk/ui-tokens/styles/root.css`
- `mdwrk/ui-tokens/styles/markdown.css`

## TypeScript entry points

- `mdwrk/ui-tokens`
- `mdwrk/ui-tokens/tokens`
- `mdwrk/ui-tokens/classes`
- `mdwrk/ui-tokens/theme-map`

## Example

```ts
import "@mdwrk/ui-tokens/styles/index.css";
import {
  renderThemeCssVariables,
  renderThemeBridgeCssVariables,
} from "@mdwrk/ui-tokens/theme-map";

const hostCss = renderThemeCssVariables(
  {
    "bg-app": "#111111",
    accent: "#7c3aed",
  },
  { selector: ".my-theme" },
);

const rendererCss = renderThemeBridgeCssVariables(
  "renderer",
  {
    "bg-panel": "#111111",
    "fg-primary": "#fafafa",
    accent: "#7c3aed",
  },
  { selector: ".my-theme .markdown-renderer" },
);
```

## Contract alignment

The exported token names, theme classes, and bridge definitions align with `mdwrk/theme-contract`. That keeps the implemented styling primitives aligned with the normative contract package.

Phase 9 expands that alignment to include editor/preview rhythm tokens and the mobile-width token surfaces consumed by the active client responsive shell.