module.examples
Example contract specifications collection
@lssm-tech/module.examplesbun add @lssm-tech/module.examplesManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
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-consoleis the default autonomous-agent showcase surfaced through/sandbox.data-grid-showcaseis the canonical ContractSpec table showcase surfaced through/sandbox?template=data-grid-showcaseand/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:
| Entrypoint | Runtime | Contents |
|---|---|---|
./runtime/native-previews | native, browser, server | Example contracts, visualization specs and deterministic sample data for native preview panels. No web UI or template providers. |
./runtime/feature-hub-reference | native, server | installFeatureHubCompositionReference and FEATURE_HUB_REFERENCE_ROUTE_IDS. |
./runtime/companyos-ai-solutions-engineer-poc | browser, server | The hosted-demo contract: COMPANYOS_ACME_PROFILE, compileCanonicalPreparedProof, the outcome-pack schema and the demo runtime contract. |
./runtime/companyos-ai-solutions-engineer-poc/server | Node only | The proof runtime: call runtime, preflight probe, proof session authority, browser fixture and approved-proof runner. |
./runtime/companyos-ai-solutions-engineer-poc/ui | client components | RequestToVerifiedProofPreview. |
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/minimalPublic preview/export workflow
Template, docs, and sandbox previews are generated from package-owned example metadata:
- Example packages expose catalog metadata through
./exampleand docs through./docswhen they should appear in public template/docs surfaces. - Rich inline previews are opt-in public surfaces. A package that adds
./uimust keep that export package-native, deterministic, fixture-backed, and mirrored inpublishConfig.exports. scripts/generate-example-registry.tsis the only writer for generated catalog and preview registry artifacts; runbun run --cwd examples/registry generate:registryafter changing example exports.- 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. - Do not introduce live backend calls, provider credentials, or production actions in preview fixtures. Provider-oriented examples must render local replay/fixture data only.
Generation and build preflight
Registry generation is an explicit repository operation. Run the existing root bun run examples:sync-registry command, or the package's generate:registry, after changing example metadata, exports or runtime ports. It manages exactly the CLI catalog's src/example-catalog/builtins.ts, the registry's src/runtime/previews.generated.ts, src/preview-catalog.generated.ts, package.json optional peers and turbo.json dependency edges.
Package prebuild now runs check:registry before the canonical artifact builder. That comparison reports stale managed outputs and does not regenerate them. Output leaves and their ancestors must not be symlinks; generation rejects an unsafe output before evaluating example modules or changing another output.
Both explicit generation and comparison still import eligible declared workspace src/example.ts modules. Those are trusted executable project code, not inert JSON. Comparison's absence of managed writes is not a filesystem or network sandbox and does not replace the task's execution-authority review.
Architecture
src/builtins.tsis a generated literal catalog and must not statically import@lssm-tech/example.*packages.src/catalog.tsis the metadata-only public surface.src/index.tsis the root public barrel and package entrypoint.src/registry.test.tsis part of the package's public or composition surface.src/registry.tsis part of the package's public or composition surface.src/runtimeis the optional rich runtime surface for consumers that intentionally install example packages.
Public Entry Points
- Export
.resolves through./src/index.tsand is catalog-only. - Export
./catalogresolves through./src/catalog.ts. - Export
./runtimeresolves 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/serverand./runtime/companyos-ai-solutions-engineer-poc/uiare the host ports described under Usage.
Local Commands
bun run dev— contractspec-bun-build devbun run build— contractspec-bun-build buildbun run test— bun testbun run lint— bun lint:fixbun run lint:check— biome check .bun run lint:fix— biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .bun run typecheck— tsgo --noEmitbun run publish:pkg— bun publish --tolerate-republish --ignore-scripts --verbosebun run publish:pkg:canary— bun publish:pkg --tag canarybun run clean— rimraf dist .turbobun run build:bundle— contractspec-bun-build transpilebun run build:types— contractspec-bun-build typesbun run generate:registry— bun ../../scripts/generate-example-registry.ts --writebun run check:registry— bun ../../scripts/generate-example-registry.ts --checkbun run prebuild— bun run check: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-consolesandbox plus its replay proof lane. - The shared ContractSpec table stack is demonstrated directly by
data-grid-showcaseand reused inanalytics-dashboard,crm-pipeline,integration-hub, andagent-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.
Relationships
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
8 declarations
@apollo/clientcatalog:graphql
@lssm-tech/lib.contracts-runtime-client-reactworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-specworkspace:^
Read the package manual ↗@lssm-tech/lib.example-shared-uiworkspace:^
Read the package manual ↗@lssm-tech/lib.presentation-runtime-coreworkspace:^
Read the package manual ↗@lssm-tech/lib.runtime-sandboxworkspace:^
Read the package manual ↗
Declared capabilities
Example contract specifications collection
Scripts
publish:pkgbun publish --tolerate-republish --ignore-scripts --verbosepublish:pkg:canarybun publish:pkg --tag canarybuildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typesdevcontractspec-bun-build devcleanrimraf dist .turbolintbun lint:fixlint:fixnode ../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../scripts/biome.cjs check --write .lint:checknode ../../scripts/biome.cjs check .testbun testgenerate:registrybun ../../scripts/generate-example-registry.ts --writecheck:registrybun ../../scripts/generate-example-registry.ts --checkprebuildbun run check:registry && contractspec-bun-build prebuildtypechecktsgo --noEmit