Skip to content
ContractSpec
Start here

Package manual · platform

·Interfaces, presentations and design

lib.presentation-runtime-core

Core presentation runtime for contract-driven UIs

platformlibraryv7.0.4stableservernode
@lssm-tech/lib.presentation-runtime-core
bun add @lssm-tech/lib.presentation-runtime-core
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Website: https://contractspec.io

Core presentation runtime for contract-driven UIs.

What It Provides

  • Layer: lib.
  • Consumers: presentation-runtime-react, presentation-runtime-react-native.
  • Related ContractSpec packages include @lssm-tech/lib.contracts-spec, @lssm-tech/tool.bun, @lssm-tech/tool.typescript.
  • Related ContractSpec packages include @lssm-tech/lib.contracts-spec, @lssm-tech/tool.bun, @lssm-tech/tool.typescript.

Installation

npm install @lssm-tech/lib.presentation-runtime-core

or

bun add @lssm-tech/lib.presentation-runtime-core

Usage

Import the root entrypoint from @lssm-tech/lib.presentation-runtime-core, or choose a documented subpath when you only need one part of the package surface.

Adaptive Experiences

The ./adaptive-experience entrypoint maps ContractSpec adaptive experience primitives into presentation defaults that UI renderers can consume without importing product-specific code. It currently resolves DataView defaults such as collection view, density, data depth, and page size from ResolvedAdaptiveExperience.

Use this adapter at the boundary between product policy and rendering code. It should receive already-resolved preferences, behavior support, signals, constraints, and overrides; it should not store hidden user profiles or bypass permissions.

Bundler Helpers

Import Next configuration helpers from the existing configuration-only leaf. Root runtime forwards and the Metro CommonJS entry remain compatible.

ts
import {
  withPresentationTurbopackAliases,
  withPresentationWebpackAliases,
} from '@lssm-tech/lib.presentation-runtime-core/next';

Next.js Turbopack helper (default)

Use Turbopack as the default Next.js path:

ts
import { withPresentationTurbopackAliases } from '@lssm-tech/lib.presentation-runtime-core/next';

const nextConfig = withPresentationTurbopackAliases({
  turbopack: {
    resolveAlias: {
      fs: { browser: 'browserify-fs' },
    },
  },
});

export default nextConfig;

Next.js Webpack helper (fallback)

Use Webpack only when you opt in with next dev --webpack or next build --webpack:

ts
import { withPresentationWebpackAliases } from '@lssm-tech/lib.presentation-runtime-core/next';

const nextConfig = {
  webpack: (config) => withPresentationWebpackAliases(config),
};

export default nextConfig;

Expo / Metro helper

js
const { getDefaultConfig } = require('expo/metro-config');
const {
  withPresentationMetroAliases,
} = require('@lssm-tech/lib.presentation-runtime-core');

const projectRoot = __dirname;
const config = getDefaultConfig(projectRoot);

module.exports = withPresentationMetroAliases(config);

The helpers also keep shared UI imports platform-correct:

  • Metro rewrites @lssm-tech/lib.ui-kit-web/ui/* to @lssm-tech/lib.ui-kit/ui/*, @lssm-tech/lib.presentation-runtime-react to @lssm-tech/lib.presentation-runtime-react-native, and lucide-react to lucide-react-native for native platforms.
  • Metro also enables package exports and merges platform export conditions so ios, android, react-native, and browser package conditions can resolve platform-specific build-tool outputs.
  • Next.js Turbopack/Webpack rewrites the native package names back to the web packages, including lucide-react-native to lucide-react.

Architecture

  • src/index.ts is the root public barrel that builds the package entrypoint.
  • src/adaptive-experience.ts is part of the package's public or composition surface.
  • src/metro.ts is part of the package's public or composition surface.
  • src/next.ts is part of the package's public or composition surface.
  • src/table.ts is part of the package's public or composition surface.
  • src/visualization.echarts.ts is part of the package's public or composition surface.
  • src/visualization.model.builders.ts is part of the package's public or composition surface.
  • src/visualization.model.helpers.ts is part of the package's public or composition surface.

Public Entry Points

  • Export . publishes through ./dist/index.js; CommonJS require resolves to the generated Metro helper at ./dist/metro.cjs.
  • Export ./adaptive-experience builds from ./src/adaptive-experience.ts.
  • The existing ./next leaf owns Next configuration helpers; the root entrypoint keeps its compatibility forwards.
  • Export ./metro builds from ./src/metro.ts and publishes a generated CommonJS dist/metro.cjs require target for Metro config files.
  • Export ./next builds from ./src/next.ts.
  • Export ./presentation-aliases builds from the configuration-only alias primitives in ./src/presentation-aliases.ts.
  • Export ./table builds from ./src/table.ts.
  • Export ./visualization builds from ./src/visualization.ts.
  • Export ./visualization.echarts builds from ./src/visualization.echarts.ts.
  • Export ./visualization.model builds from ./src/visualization.model.ts.
  • Export ./visualization.model.builders builds from ./src/visualization.model.builders.ts.
  • Export ./visualization.model.helpers builds from ./src/visualization.model.helpers.ts.
  • Export ./visualization.types builds from ./src/visualization.types.ts.
  • Export ./visualization.utils builds from ./src/visualization.utils.ts.
  • Export ./marketing builds from ./src/marketing/index.ts: marketing meta builders, the SEO transform and the presentation descriptor normalizer.

Marketing presentation descriptors

normalizeMarketingPresentationDescriptor turns a marketing page (and optional site bindings, evidence and global CTAs) into a serializable MarketingPresentationDescriptor. Its input is structural: MarketingPresentationPageInput and MarketingPresentationSiteInput name only the fields the normalizer reads, over a MarketingPresentation* vocabulary that mirrors the growth marketing site vocabulary. Growth MarketingPageContract and MarketingSiteContract values satisfy them as-is, so hosts pass growth contracts directly. This platform package has no runtime dependency on @lssm-tech/lib.growth-spec; a type-only parity test (src/marketing/descriptor-vocabulary.test.ts, growth-spec as a devDependency) fails typecheck if the two vocabularies drift.

Local Commands

  • bun run dev — contractspec-bun-build dev
  • bun run build — bun run prebuild && bun run build:bundle && bun run build:types
  • bun run lint — bun run lint:fix
  • bun run lint:check — biome check .
  • bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
  • bun run typecheck — tsgo --noEmit -p tsconfig.json
  • bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
  • bun run publish:pkg:canary — bun publish:pkg --tag canary
  • bun run clean — rimraf dist .turbo
  • bun run build:bundle — contractspec-bun-build transpile
  • bun run build:types — contractspec-bun-build types
  • bun run prebuild — contractspec-bun-build prebuild

Recent Updates

  • Replace eslint+prettier by biomejs to optimize speed.
  • Add data visualization capabilities.
  • Add table capabilities.
  • Add table overflow metadata to controller render models so web and native renderers can apply consistent cell overflow behavior.
  • Add adaptive experience adapters for DataView presentation defaults.

Notes

  • Core runtime interface is consumed by all presentation runtimes — changes here affect both web and mobile.
  • Must remain platform-agnostic; no React or React Native imports allowed.
  • API surface changes require coordinated updates in both downstream runtimes.

Whole canonical adaptive and presentation ownership

Preserve the complete existing adaptive policy, permissions, constraints, override and event families; schema-to-markdown and structured-data implementations; rich-code preferences; all rendering and marketing behavior, defaults and original test assertions. Bind each whole family to its genuine existing Core, Kernel, Growth, DesignCatalog or complete RuntimeCore host supplier. Historical imports remain exact canonical forwards.

This is a Source-only compatible ownership proposal. Fresh task-bound adoption, owning production, declarations, affected runtime tests and platform qualification remain required.

The complete SEO integration test and snapshot live in the Legacy app-config test directory because they exercise its original resolveAppConfig implementation. Pure presentation tests remain with this package; the Legacy test declares its canonical presentation dependency.

Relationships

THIS PACKAGElib.presentation-runtime-core38 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

8 declarations

Declared capabilities

Lib Presentation Runtime Core

Core presentation runtime for contract-driven UIs

Scripts

  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose
  • publish:pkg:canarybun publish:pkg --tag canary
  • buildbun run build:bundle && bun run build:require && bun run build:types
  • build:bundlecontractspec-bun-build transpile
  • build:requirebun build src/metro.ts --target node --format cjs --packages external --outfile dist/metro.cjs
  • build:typescontractspec-bun-build types
  • cleanrimraf dist .turbo
  • devcontractspec-bun-build dev
  • lintbun run lint:fix
  • lint:fixnode ../../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../../scripts/biome.cjs check --write .
  • lint:checknode ../../../../scripts/biome.cjs check .
  • testbun test --pass-with-no-tests
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit -p tsconfig.json