module.examples

@lssm-tech/module.examples

Website: https://contractspec.io

Catalog-first ContractSpec example metadata, with optional runtime helpers for rich example surfaces.

What It Provides

• Layer: module.
• Consumers: CLIs, editor bridges, apps, docs, and rich sandbox/template surfaces.
• Related ContractSpec packages include @lssm-tech/example.agent-console, @lssm-tech/example.ai-chat-assistant, @lssm-tech/example.ai-support-bot, @lssm-tech/example.analytics-dashboard, @lssm-tech/example.calendar-google, @lssm-tech/example.content-generation, ...
• agent-console is the default autonomous-agent showcase surfaced through /sandbox.
• data-grid-showcase is the canonical ContractSpec table showcase surfaced through /sandbox?template=data-grid-showcase and /docs/examples/data-grid-showcase.

Installation

npm install @lssm-tech/module.examples

or

bun add @lssm-tech/module.examples

Usage

Use the root entrypoint or @lssm-tech/module.examples/catalog for metadata-only discovery. Use @lssm-tech/module.examples/runtime only when rendering rich template previews or sandbox runtime surfaces. The catalog also exposes shared preview-surface helpers so apps can show every discoverable example while loading rich UI only for packages that export ./ui.

import { getExample, listExamples } from '@lssm-tech/module.examples/catalog';

import { ExampleWebPreview, TemplateRuntimeProvider, listTemplates } from '@lssm-tech/module.examples/runtime';

Host ports

Apps and bundles that render a specific example read it through a named host port instead of importing @lssm-tech/example.* packages, which the package-layer boundary check rejects. Each port re-exports only what hosts use and is split by runtime:

import { CRM_PIPELINE_DEALS } from '@lssm-tech/module.examples/runtime/native-previews';
import { COMPANYOS_ACME_PROFILE } from '@lssm-tech/module.examples/runtime/companyos-ai-solutions-engineer-poc';

The example packages stay optional peers: a host installs the examples whose port it imports.

The catalog contains source metadata for each example. CLI users can fetch a full example only when needed:

contractspec examples download minimal --out-dir ./examples/minimal

Public preview/export workflow

Template, docs, and sandbox previews are generated from package-owned example metadata:

1. Example packages expose catalog metadata through ./example and docs through ./docs when they should appear in public template/docs surfaces.
2. Rich inline previews are opt-in public surfaces. A package that adds ./ui must keep that export package-native, deterministic, fixture-backed, and mirrored in publishConfig.exports.
3. scripts/generate-example-registry.ts is the only writer for generated catalog and preview registry artifacts; run bun run --cwd examples/registry generate:registry after changing example exports.
4. Preview consumers should use catalog helpers for discoverability and supportsInlineExamplePreview() / getExamplePreviewSurface() before loading runtime UI. Keep docs, sandbox, LLMS, and source fallback links available for examples without inline UI.
5. Do not introduce live backend calls, provider credentials, or production actions in preview fixtures. Provider-oriented examples must render local replay/fixture data only.

Architecture

• src/builtins.ts is a generated literal catalog and must not statically import @lssm-tech/example.* packages.
• src/catalog.ts is the metadata-only public surface.
• src/index.ts is the root public barrel and package entrypoint.
• src/registry.test.ts is part of the package's public or composition surface.
• src/registry.ts is part of the package's public or composition surface.
• src/runtime is the optional rich runtime surface for consumers that intentionally install example packages.

Public Entry Points

• Export . resolves through ./src/index.ts and is catalog-only.
• Export ./catalog resolves through ./src/catalog.ts.
• Export ./runtime resolves through ./src/runtime/index.ts.
• Exports ./runtime/native-previews, ./runtime/feature-hub-reference, ./runtime/companyos-ai-solutions-engineer-poc, ./runtime/companyos-ai-solutions-engineer-poc/server and ./runtime/companyos-ai-solutions-engineer-poc/ui are the host ports described under Usage.

Local Commands

• bun run dev — contractspec-bun-build dev
• bun run build — contractspec-bun-build build
• bun run test — bun test
• bun run lint — bun 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
• 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 generate:registry — bun ../../scripts/generate-example-registry.ts --write
• bun run prebuild — bun run generate:registry && contractspec-bun-build prebuild

Recent Updates

• Replace eslint+prettier by biomejs to optimize speed.
• Add table capabilities.
• Stability.
• Vnext ai-native.

Notes

• This module is a thin catalog/runtime bridge -- business logic belongs in individual example packages under examples/.
• Adding a new example requires creating the example package and regenerating the catalog with bun run generate:registry; do not add it as a direct dependency here.
• Root/catalog imports must remain metadata-only. Rich runtime consumers should import @lssm-tech/module.examples/runtime (or a host port) and own any required @lssm-tech/example.* dependencies directly.
• The meetup-ready autonomous-agent path is the deterministic agent-console sandbox plus its replay proof lane.
• The shared ContractSpec table stack is demonstrated directly by data-grid-showcase and reused in analytics-dashboard, crm-pipeline, integration-hub, and agent-console.

The registry generator also owns optional example-runtime peers and this package's Turbo task dependencies. Optional peers preserve catalog-only installation while letting declaration builds resolve the installed example declaration surfaces. The generated task edges build those declarations before the runtime bridge; example packages remain responsible for validating their own implementations. Run generate:registry after changing preview exports or runtime example imports. Do not hand-edit the managed example peers or turbo.json.