lib.contracts-runtime-client-react

@lssm-tech/lib.contracts-runtime-client-react

React runtime adapters for ContractSpec contracts.

Query/result primitives, feature and presentation declarations use their complete Core owners. Locale and translation factory exports use TranslationRuntime; feature registration retains the canonical Kernel FeatureRegistry class. The form renderer uses the complete Core Form contracts and FormsRuntime runtime helpers. Its tests retain the canonical DesignCatalog showcase singleton and Core identity/layout helpers. PWA update checks consume the complete portable Core /pwa/types contracts; all Source and test imports use their canonical owners. Public entrypoints and React peer requirements are unchanged. The canonical registry and Forms runtime bindings require Forms839a and the complete Kernel FeatureRegistry owner to be composed before qualification.

What It Provides

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

Installation

npm install @lssm-tech/lib.contracts-runtime-client-react

or

bun add @lssm-tech/lib.contracts-runtime-client-react

Usage

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

The form renderer supports the expanded FormSpec field set: readonly inputs, email, autocomplete, address, phone, date, time, datetime, semantic groups, repeated grouped arrays, grid layout hints, progressive layout.flow sections/steps, and text/textarea/email input groups. Drivers are expected to provide dedicated slots for rich widgets plus shadcn/Radix-style Field* and optional InputGroup* slots. Email fields render through the standard input slot with native email input behavior. When input-group slots are absent, text, email, and textarea fields fall back to plain controls.

Autocomplete fields support local filtering and resolver-backed search. Resolver calls receive the current query, watched dependency values, field name, and an AbortSignal through the existing resolver args object; stale responses are ignored and selected remote options remain visible when later searches return a different result set. Custom autocomplete driver slots can read optional loading, error, emptyText, loadingText, and errorText props to expose async state.

PWA update checks

usePwaUpdateChecker from @lssm-tech/lib.contracts-runtime-client-react/pwa-update-client checks the pwa.update.check API, exposes required/blocking versus optional update state, supports polling, and delegates actual service worker activation to a host-provided onApply callback.

LSSM OS durable-operation status

useLssmOsOperationStatusV1 from @lssm-tech/lib.contracts-runtime-client-react/lssm-os-operation-status accepts the provider-neutral Runtime Node operation client port and returns its ui projection unchanged. HTTP hosts may inject @lssm-tech/integration.lssm-os-operation-client, but this React library has no upward integration dependency. It polls only while the canonical operation is nonterminal or its canonical error is retryable, aborts obsolete scopes, and never derives a UI-specific status, receipt, or error mapping.

Adaptive form support

resolveAdaptiveFormExperience from @lssm-tech/lib.contracts-runtime-client-react/adaptive-form maps ResolvedAdaptiveExperience into generic form guidance, density, control, and recovery defaults. It is a lightweight adapter for form renderers and vertical applications that want adaptive behavior without coupling forms to analytics or product-specific labels.

Use the result as an editable runtime recommendation. It should not override permissions, validation, authorization, or business rules.

Query and mutation hooks

useContractQuery(envelope, options?) and useContractMutation(options?) are thin bindings over the in-house engine in @lssm-tech/lib.contracts-runtime-core^† — no @tanstack/*. Wrap the surface in ContractDataEngineProvider with a createDataEngine({ transport }), then:

• useContractQuery returns the canonical QueryState<TData> verbatim (status, fetchStatus, data, error, cacheStatus, isStale, isOffline, conflict, versionToken) plus refetch — so it flows straight into the I/O-free design-system QueryState components with zero adapter.
• useContractMutation returns the canonical mutation state (status, data, problem, conflictOutcome, isPending) plus mutate(request, { optimistic? }).

The engine owns the cache, request dedup, durable offline queue + replay, etag conflict resolution, optimistic apply/rollback, and recoverable auth-expiry. This package no longer ships cache-key/storage/policy helpers or a ./query-client subpath — they were removed in the data-fetching ecosystem reset (the engine owns all of it). parseContractResponse (structuredContent-first MCP/GraphQL decode) remains for non-engine response interpretation.

Provider props for the local/offline mode

ContractDataEngineProvider accepts either a host-composed engine or a transport from which it builds and owns the engine:

<ContractDataEngineProvider
  transport={transport}
  mode={offlineEnabled ? "offline-capable" : "online-only"}
  offline={{ storage, reachability }}
>
  <App />
</ContractDataEngineProvider>

• mode takes online-only, memory-cache or offline-capable, or a policy resolved with resolveLocalOfflinePolicy({ env, flag }). Without mode, offline.storage selects offline-capable and no storage keeps online-only.
• offline is passed to the engine as its advanced options. Durable offline.storage and offline.cacheStore are forwarded only in offline-capable mode and dropped in online-only and memory-cache, so the same offline object works while mode toggles.
• The engine is rebuilt only when transport, the resolved mode, the forwarded offline.storage or offline.reachability changes, so inline offline objects are safe.
• The host reachability source is followed only while the provider is mounted, so a replaced engine stops draining the offline queue.
• On the explicit path, engine keeps working unchanged. An optional transport there only feeds realtime subscriptions.

Realtime subscriptions

useContractSubscription(tags, options?) listens on the provider transport's subscribe() seam, for example createWebSocketTransport from @lssm-tech/lib.contracts-runtime-core. For each pushed event it marks the matching cached reads stale and, when any matched, runs the engine's maintenance.revalidateStale(), then calls onInvalidate. That pass refetches every stale cache entry, not only the reads for the pushed tags. It returns { supported, active, lastEvent, eventCount }. A transport without subscribe(), such as REST, reports supported: false. Reconnects, backpressure and resync stay in the transport. Revalidation runs on the engine's background path without a per-call ctx, and a failed invalidation or revalidation goes to onError. An online-only engine has no cache to revalidate, so in that mode use onInvalidate to refetch.

Architecture

• src/adaptive-form.ts is part of the package's public or composition surface.
• src/drivers is part of the package's public or composition surface.
• src/feature-render.ts is part of the package's public or composition surface.
• src/form-render.impl.tsx is part of the package's public or composition surface.
• src/form-render.ts is part of the package's public or composition surface.
• src/index.ts is the root public barrel and package entrypoint.

Public Entry Points

• Export . resolves through ./src/index.ts.
• Export ./adaptive-form resolves through ./src/adaptive-form.ts.
• Export ./drivers/rn-reusables resolves through ./src/drivers/rn-reusables.ts.
• Export ./drivers/shadcn resolves through ./src/drivers/shadcn.ts.
• Export ./feature-render resolves through ./src/feature-render.ts.
• Export ./form-render resolves through ./src/form-render.ts.
• Export ./form-render.impl resolves through ./src/form-render.impl.tsx.
• Export ./pwa-update-client resolves through ./src/pwa-update-client.tsx.
• Export ./lssm-os-operation-status resolves through ./src/lssm-os-operation-status.tsx.
• Export ./subscriptions/use-contract-subscription resolves through ./src/subscriptions/use-contract-subscription.tsx.

Local Commands

• bun run dev — contractspec-bun-build dev
• bun run build — contractspec-bun-build build
• 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
• bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
• bun run publish:pkg:canary — bun publish:pkg --tag canary
• bun run clean — rm -rf dist
• 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 generic adaptive form experience helpers for runtime guidance defaults.

Notes

• Driver interface must stay compatible with both shadcn and RN Reusables.
• Form rendering pipeline is a critical path; test thoroughly before changing.