OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

AI index

Presentations — Unified Descriptor & Transform Engine

How PresentationSpec and TransformEngine keep docs/renderers consistent.

field.key.label
Presentations — Unified Descriptor & Transform Engine
field.version.label
field.type.label
field.title.label
Presentations — Unified Descriptor & Transform Engine
field.description.label

How PresentationSpec and TransformEngine keep docs/renderers consistent.

field.tags.label
presentations,docs,mcp
field.owners.label
field.stability.label
public

Presentations V2 — Unified Descriptor & Transform Engine

Purpose

Unify presentations into one descriptor (`PresentationSpec`) that declares a single source (React component key or BlockNote doc) and a list of output targets (react, markdown, application/json, application/xml). A pluggable `TransformEngine` renders any target and applies PII redaction.

Types

type PresentationTarget =
  | 'react'
  | 'markdown'
  | 'application/json'
  | 'application/xml';

type PresentationSource =
  | {
      type: 'component';
      framework: 'react';
      componentKey: string;
      props?: AnySchemaModel;
    }
  | { type: 'blocknotejs'; docJson: unknown; blockConfig?: unknown };

interface PresentationSpec {
  meta: PresentationMeta; // includes partial OwnerShipMeta + description
  policy?: SurfacePolicyRequirement;
  source: PresentationSource;
  targets: PresentationTarget[];
}

// Shared ownership schema (source of truth in @lssm-tech/lib.contracts-spec/src/ownership.ts)
interface OwnerShipMeta {
  title: string;
  description: string;
  domain: string;
  owners: Owner[];
  tags: Tag[];
  stability: Stability;
}

type Stability = 'experimental' | 'beta' | 'stable' | 'deprecated';
type Owner = string; // curated list available in code (e.g., '@sigil-team', 'team-strit')
type Tag = string; // curated list available in code (e.g., 'auth', 'spots')

// For presentations, meta is a Partial<OwnerShipMeta> plus description, name, version
interface PresentationMeta extends Partial<OwnerShipMeta> {
  name: string;
  version: string;
  description?: string;
}

Engine

Use `createDefaultTransformEngine()` from `@lssm-tech/lib.presentation-runtime-core/transform-engine` and register custom renderers as needed. React hosts add `registerDefaultReactRenderer()` from `@lssm-tech/lib.contracts-runtime-client-react/transform-engine`. The core engine supports markdown/json/xml; the React renderer returns a serializable descriptor the host app renders via a `componentMap` or a BlockNote renderer. The canonical source type string is `blocknotejs` (not `blocknote`).

PII paths (JSON-like) are redacted from rendered outputs.

MCP Integration

`createMcpServer` accepts `presentationsV2`. Each descriptor is exposed under `presentation://<name>/v<version>` and negotiated variants (`.md/.json/.xml`) are rendered by the engine.

Migration

•

V1 `PresentationSpec` remains supported; a back-compat helper converts V1 → V2 when convenient.

•

Prefer V2 for new work.

Examples (Sigil)

•

`sigil.auth.webauth_tabs_v2`: component source (`componentKey: 'sigil.webauth.tabs'`), targets `react/json/xml`.

•

`sigil.signup.guide_v2`: BlockNote doc source, targets `react/markdown/json/xml`.

React Rendering

Host apps use a `componentMap` (e.g., `'sigil.webauth.tabs' → WebAuthTabs`) and a BlockNote renderer to turn the React render descriptor into elements.