@contractspec/bundle.library 3.9.8 → 3.9.9

package/dist/components/docs/libraries/LibrariesOverviewPage.js

@@ -1,2 +1,2 @@
 // @bun
-var s=Object.defineProperty;var o=(e)=>e;function c(e,t){this[e]=o.bind(null,t)}var p=(e,t)=>{for(var r in t)s(e,r,{get:t[r],enumerable:!0,configurable:!0,set:c.bind(t,r)})};var m=(e,t)=>()=>(e&&(t=e(e=0)),t);import n from"@contractspec/lib.ui-link";import{ChevronRight as l}from"lucide-react";import{jsx as i,jsxs as a}from"react/jsx-runtime";var d=[{title:"Contract and schema foundation",body:"Use these packages to define explicit contracts, schemas, and generated artifacts without inventing a new platform-specific language.",items:[{title:"@contractspec/lib.contracts-spec",description:"Define operations, events, policies, and generated surfaces in TypeScript.",href:"/docs/libraries/contracts"},{title:"@contractspec/lib.schema",description:"Share type-safe schema definitions across validation, clients, and runtime adapters.",href:"/docs/libraries/schema"}]},{title:"Runtime and surface libraries",body:"These packages execute the contract model across UI, data, observability, workflows, and generated runtime behavior.",items:[{title:"@contractspec/lib.runtime",description:"Run typed capability surfaces, execute policies, and connect runtime adapters.",href:"/docs/libraries/runtime"},{title:"@contractspec/lib.ui-kit",description:"Render shared surfaces across web and React Native without forking the contract layer.",href:"/docs/libraries/ui-kit"},{title:"@contractspec/lib.ui-kit-web",description:"Use the raw web primitive layer directly when you want the browser table, accessibility, and interaction model without the design-system shell.",href:"/docs/libraries/ui-kit-web"},{title:"@contractspec/lib.design-system",description:"Build higher-level product surfaces and documented marketing/docs primitives on top of the web and native UI packages.",href:"/docs/libraries/design-system"},{title:"Application shell",description:"Adopt the shared sidebar, topbar, command search, mobile navigation, and PageOutline patterns for product apps.",href:"/docs/libraries/application-shell"},{title:"Cross-platform UI",description:"See how the presentation runtimes, ui-kit-web, ui-kit, and design-system stay compatible across React and React Native.",href:"/docs/libraries/cross-platform-ui"},{title:"@contractspec/lib.data-views",description:"Generate and render list/detail style surfaces that stay aligned with data contracts.",href:"/docs/libraries/data-views"}]},{title:"Operator and system packages",body:"These packages matter once the system is live and you need governance, resilience, and observability.",items:[{title:"@contractspec/lib.observability",description:"Trace, log, and measure contract execution using the same system boundaries.",href:"/docs/libraries/observability"},{title:"@contractspec/lib.resilience",description:"Add circuit breakers, retries, and failure controls without hiding the integration model.",href:"/docs/libraries/resilience"},{title:"@contractspec/lib.multi-tenancy",description:"Keep tenant-specific config, policy, and surface resolution explicit.",href:"/docs/libraries/multi-tenancy"},{title:"@contractspec/lib.workflow-composer",description:"Compose and extend workflows without smearing orchestration concerns across apps.",href:"/docs/libraries/workflow-composer"}]}];function f(){return a("div",{className:"space-y-10",children:[a("div",{className:"space-y-3",children:[i("p",{className:"editorial-kicker",children:"Build"}),i("h1",{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"The OSS foundation is a library system, not a closed platform."}),i("p",{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"ContractSpec is assembled from libraries that remain useful on their own and stronger together. Start with the contract and schema foundation, then add runtime, UI, integration, and operator packages as your system grows."})]}),a("div",{className:"editorial-proof-strip",children:[a("div",{className:"editorial-stat",children:[i("span",{className:"editorial-label",children:"Layering rule"}),i("span",{className:"editorial-stat-value",children:"libs \u2192 bundles \u2192 apps"})]}),i("p",{className:"max-w-2xl text-muted-foreground text-sm leading-7",children:"Keep reusable behavior in libraries, compose it into bundle-level surfaces, and reserve app packages for concrete delivery shells."})]}),i("div",{className:"space-y-6",children:d.map((e)=>a("section",{className:"editorial-panel space-y-5",children:[a("div",{className:"space-y-2",children:[i("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:e.title}),i("p",{className:"text-muted-foreground text-sm leading-7",children:e.body})]}),i("div",{className:"grid gap-4 md:grid-cols-2",children:e.items.map((t)=>a(n,{href:t.href,className:"rounded-[24px] border border-border/75 bg-background/70 p-5 transition-colors hover:border-[color:rgb(162_79_42_/_0.45)]",children:[i("h3",{className:"font-semibold text-lg",children:t.title}),i("p",{className:"mt-2 text-muted-foreground text-sm leading-7",children:t.description}),a("div",{className:"mt-3 flex items-center gap-2 text-[color:var(--rust)] text-sm",children:["Learn more ",i(l,{size:14})]})]},t.title))})]},e.title))})]})}export{f as LibrariesOverviewPage};
+var s=Object.defineProperty;var o=(e)=>e;function n(e,t){this[e]=o.bind(null,t)}var p=(e,t)=>{for(var r in t)s(e,r,{get:t[r],enumerable:!0,configurable:!0,set:n.bind(t,r)})};var m=(e,t)=>()=>(e&&(t=e(e=0)),t);import c from"@contractspec/lib.ui-link";import{ChevronRight as l}from"lucide-react";import{jsx as i,jsxs as a}from"react/jsx-runtime";var d=[{title:"Contract and schema foundation",body:"Use these packages to define explicit contracts, schemas, and generated artifacts without inventing a new platform-specific language.",items:[{title:"@contractspec/lib.contracts-spec",description:"Define operations, events, policies, and generated surfaces in TypeScript.",href:"/docs/libraries/contracts"},{title:"@contractspec/lib.schema",description:"Share type-safe schema definitions across validation, clients, and runtime adapters.",href:"/docs/libraries/schema"}]},{title:"Runtime and surface libraries",body:"These packages execute the contract model across UI, data, observability, workflows, and generated runtime behavior.",items:[{title:"@contractspec/lib.runtime",description:"Run typed capability surfaces, execute policies, and connect runtime adapters.",href:"/docs/libraries/runtime"},{title:"@contractspec/lib.translation-runtime",description:"Resolve ContractSpec TranslationSpec catalogs with ICU formatting, SSR snapshots, BCP 47 locales, overrides, and optional i18next projection.",href:"/docs/libraries/translation-runtime"},{title:"@contractspec/lib.ui-kit",description:"Render shared surfaces across web and React Native without forking the contract layer.",href:"/docs/libraries/ui-kit"},{title:"@contractspec/lib.ui-kit-web",description:"Use the raw web primitive layer directly when you want the browser table, accessibility, and interaction model without the design-system shell.",href:"/docs/libraries/ui-kit-web"},{title:"@contractspec/lib.design-system",description:"Build higher-level product surfaces, actionable object references, adaptive panels, and documented marketing/docs primitives on top of the web and native UI packages.",href:"/docs/libraries/design-system"},{title:"Application shell",description:"Adopt the shared sidebar, topbar, command search, notifications, mobile navigation, and PageOutline patterns for product apps.",href:"/docs/libraries/application-shell"},{title:"Cross-platform UI",description:"See how the presentation runtimes, ui-kit-web, ui-kit, and design-system stay compatible across React and React Native.",href:"/docs/libraries/cross-platform-ui"},{title:"@contractspec/lib.data-views",description:"Generate and render list/detail style surfaces that stay aligned with data contracts.",href:"/docs/libraries/data-views"}]},{title:"Operator and system packages",body:"These packages matter once the system is live and you need governance, resilience, and observability.",items:[{title:"@contractspec/lib.observability",description:"Trace, log, and measure contract execution using the same system boundaries.",href:"/docs/libraries/observability"},{title:"@contractspec/lib.resilience",description:"Add circuit breakers, retries, and failure controls without hiding the integration model.",href:"/docs/libraries/resilience"},{title:"@contractspec/lib.multi-tenancy",description:"Keep tenant-specific config, policy, and surface resolution explicit.",href:"/docs/libraries/multi-tenancy"},{title:"@contractspec/lib.workflow-composer",description:"Compose and extend workflows without smearing orchestration concerns across apps.",href:"/docs/libraries/workflow-composer"}]}];function f(){return a("div",{className:"space-y-10",children:[a("div",{className:"space-y-3",children:[i("p",{className:"editorial-kicker",children:"Build"}),i("h1",{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"The OSS foundation is a library system, not a closed platform."}),i("p",{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"ContractSpec is assembled from libraries that remain useful on their own and stronger together. Start with the contract and schema foundation, then add runtime, UI, integration, and operator packages as your system grows."})]}),a("div",{className:"editorial-proof-strip",children:[a("div",{className:"editorial-stat",children:[i("span",{className:"editorial-label",children:"Layering rule"}),i("span",{className:"editorial-stat-value",children:"libs \u2192 bundles \u2192 apps"})]}),i("p",{className:"max-w-2xl text-muted-foreground text-sm leading-7",children:"Keep reusable behavior in libraries, compose it into bundle-level surfaces, and reserve app packages for concrete delivery shells."})]}),i("div",{className:"space-y-6",children:d.map((e)=>a("section",{className:"editorial-panel space-y-5",children:[a("div",{className:"space-y-2",children:[i("h2",{className:"font-serif text-3xl tracking-[-0.03em]",children:e.title}),i("p",{className:"text-muted-foreground text-sm leading-7",children:e.body})]}),i("div",{className:"grid gap-4 md:grid-cols-2",children:e.items.map((t)=>a(c,{href:t.href,className:"rounded-[24px] border border-border/75 bg-background/70 p-5 transition-colors hover:border-[color:rgb(162_79_42_/_0.45)]",children:[i("h3",{className:"font-semibold text-lg",children:t.title}),i("p",{className:"mt-2 text-muted-foreground text-sm leading-7",children:t.description}),a("div",{className:"mt-3 flex items-center gap-2 text-[color:var(--rust)] text-sm",children:["Learn more ",i(l,{size:14})]})]},t.title))})]},e.title))})]})}export{f as LibrariesOverviewPage};

package/dist/components/docs/libraries/LibrariesPersonalizationPage.js

@@ -1,5 +1,53 @@
 // @bun
-var l=Object.defineProperty;var c=(a)=>a;function s(a,t){this[a]=c.bind(null,t)}var m=(a,t)=>{for(var o in t)l(a,o,{get:t[o],enumerable:!0,configurable:!0,set:s.bind(t,o)})};var f=(a,t)=>()=>(a&&(t=a(a=0)),t);import{CodeBlock as i,InstallCommand as d}from"@contractspec/lib.design-system";import n from"@contractspec/lib.ui-link";import{ChevronRight as p}from"lucide-react";import{jsx as e,jsxs as r}from"react/jsx-runtime";function u(){return r("div",{className:"space-y-8",children:[r("div",{className:"space-y-4",children:[e("h1",{className:"font-bold text-4xl",children:"@contractspec/lib.personalization"}),e("p",{className:"text-lg text-muted-foreground",children:"Track field/feature/workflow usage, analyze drop-offs, and convert insights into OverlaySpecs or workflow tweaks."})]}),r("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Installation"}),e(d,{package:"@contractspec/lib.personalization"})]}),r("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Tracker"}),e("p",{className:"text-muted-foreground",children:"Buffer events per tenant/user and emit OpenTelemetry counters automatically."}),e(i,{language:"typescript",code:`import { createBehaviorTracker } from '@contractspec/lib.personalization';
+var u=Object.defineProperty;var v=(e)=>e;function w(e,g){this[e]=v.bind(null,g)}var $=(e,g)=>{for(var o in g)u(e,o,{get:g[o],enumerable:!0,configurable:!0,set:w.bind(g,o)})};var F=(e,g)=>()=>(e&&(g=e(e=0)),g);import{CodeBlock as m,InstallCommand as y}from"@contractspec/lib.design-system";import{HStack as z,VStack as f}from"@contractspec/lib.design-system/layout";import{Code as r,H1 as B,H2 as h,P as l,Text as p}from"@contractspec/lib.design-system/typography";import q from"@contractspec/lib.ui-link";import{ChevronRight as J}from"lucide-react";import{jsx as b,jsxs as d}from"react/jsx-runtime";var Q=`import { DataViewRenderer } from '@contractspec/lib.design-system';
+import { resolveDataViewPreferences } from '@contractspec/lib.personalization/data-view-preferences';
+
+const resolved = resolveDataViewPreferences({
+  spec: AccountsDataView,
+  preferences: profile.canonical,
+  insights,
+  record: savedAccountViewPreference,
+});
+
+return (
+  <DataViewRenderer
+    spec={AccountsDataView}
+    items={accounts}
+    defaultViewMode={resolved.viewMode}
+    defaultDensity={resolved.density}
+    defaultDataDepth={resolved.dataDepth}
+    pagination={{
+      page,
+      pageSize: resolved.pageSize ?? 25,
+      total,
+    }}
+  />
+);`,U=`tracker.trackDataViewInteraction({
+  dataViewKey: AccountsDataView.meta.key,
+  dataViewVersion: AccountsDataView.meta.version,
+  action: 'view_mode_changed',
+  viewMode: 'grid',
+});
+
+tracker.trackDataViewInteraction({
+  dataViewKey: AccountsDataView.meta.key,
+  action: 'data_depth_changed',
+  dataDepth: 'detailed',
+});
+
+tracker.trackDataViewInteraction({
+  dataViewKey: AccountsDataView.meta.key,
+  action: 'filter_changed',
+  filterKey: 'status',
+});`,Y=`Add DataView personalization for <screen>.
+
+Acceptance criteria:
+- Resolve viewMode, density, dataDepth, and pageSize with resolveDataViewPreferences.
+- Apply resolved values to DataViewRenderer as default or controlled props.
+- Track opened, view_mode_changed, density_changed, data_depth_changed, search_changed, filter_changed, sort_changed, and page_changed actions with trackDataViewInteraction.
+- Persist only the dimensions allowed by view.collection.personalization.persist.
+- Ignore behavior-derived modes that are not allowed by view.collection.viewModes.allowedModes.
+- Do not import React or design-system code into @contractspec/lib.personalization helpers.`;function i(){return d(f,{className:"space-y-8",children:[d(f,{className:"space-y-4",children:[b(B,{className:"font-bold text-4xl",children:"@contractspec/lib.personalization"}),b(l,{className:"text-lg text-muted-foreground",children:"Track field/feature/workflow usage, analyze drop-offs, and convert insights into OverlaySpecs or workflow tweaks."})]}),d(f,{className:"space-y-4",children:[b(h,{className:"font-bold text-2xl",children:"Installation"}),b(y,{package:"@contractspec/lib.personalization"})]}),d(f,{className:"space-y-4",children:[b(h,{className:"font-bold text-2xl",children:"Tracker"}),b(l,{className:"text-muted-foreground",children:"Buffer events per tenant/user and emit OpenTelemetry counters automatically."}),b(m,{language:"typescript",code:`import { createBehaviorTracker } from '@contractspec/lib.personalization';
 
 const tracker = createBehaviorTracker({
   store,
@@ -7,14 +55,20 @@ const tracker = createBehaviorTracker({
 });
 
 tracker.trackFieldAccess({ operation: 'billing.createOrder', field: 'items' });
-tracker.trackWorkflowStep({ workflow: 'invoice', step: 'review', status: 'entered' });`})]}),r("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Analyzer"}),e("p",{className:"text-muted-foreground",children:"Summarize events and highlight unused UI, frequent fields, and workflow bottlenecks."}),e(i,{language:"typescript",code:`import { BehaviorAnalyzer } from '@contractspec/lib.personalization/analyzer';
+tracker.trackWorkflowStep({ workflow: 'invoice', step: 'review', status: 'entered' });`})]}),d(f,{className:"space-y-4",children:[b(h,{className:"font-bold text-2xl",children:"DataView Preferences"}),d(l,{className:"text-muted-foreground",children:["Use ",b(r,{children:"resolveDataViewPreferences"})," when a collection DataView should honor a user's preferred list/grid/table mode, compact or comfortable density, data depth, and page size. The helper returns plain values that can be passed into the renderer without coupling the design-system package to personalization. Start from the"," ",b(q,{href:"/docs/libraries/data-views",className:"text-[color:var(--rust)] underline underline-offset-4",children:b(p,{children:"DataViews runtime guide"})})," ","when you need the contract and renderer shape."]}),b(m,{language:"tsx",code:Q})]}),d(f,{className:"space-y-4",children:[b(h,{className:"font-bold text-2xl",children:"DataView Interaction Events"}),d(l,{className:"text-muted-foreground",children:["Track ",b(r,{children:"data_view_interaction"})," events for view mode, density, data depth, search, filters, sorting, and pagination. The in-memory store summarizes those events, and the analyzer can derive a scoped preferred collection mode from valid interaction counts."]}),b(m,{language:"typescript",code:U})]}),d(f,{className:"space-y-4",children:[b(h,{className:"font-bold text-2xl",children:"Analyzer"}),b(l,{className:"text-muted-foreground",children:"Summarize events and highlight unused UI, frequent fields, and workflow bottlenecks."}),b(m,{language:"typescript",code:`import { BehaviorAnalyzer } from '@contractspec/lib.personalization/analyzer';
 
 const analyzer = new BehaviorAnalyzer(store);
 const insights = await analyzer.analyze({ tenantId: 'acme', userId: 'ops-42' });
-// { unusedFields: ['internalNotes'], workflowBottlenecks: [...] }`})]}),r("div",{className:"space-y-4",children:[e("h2",{className:"font-bold text-2xl",children:"Adapter"}),e("p",{className:"text-muted-foreground",children:"Convert insights into overlays or workflow extension hints."}),e(i,{language:"typescript",code:`import { insightsToOverlaySuggestion } from '@contractspec/lib.personalization/adapter';
+// {
+//   unusedFields: ['internalNotes'],
+//   workflowBottlenecks: [...],
+//   dataViewPreferences: {
+//     'crm.accounts': { preferredViewMode: 'grid' }
+//   }
+// }`})]}),d(f,{className:"space-y-4",children:[b(h,{className:"font-bold text-2xl",children:"Adapter"}),b(l,{className:"text-muted-foreground",children:"Convert insights into overlays or workflow extension hints."}),b(m,{language:"typescript",code:`import { insightsToOverlaySuggestion } from '@contractspec/lib.personalization/adapter';
 
 const overlay = insightsToOverlaySuggestion(insights, {
   overlayId: 'acme-order-form',
   tenantId: 'acme',
   capability: 'billing.createOrder',
-});`})]}),r("div",{className:"flex items-center gap-4 pt-4",children:[e(n,{href:"/docs/libraries",className:"btn-ghost",children:"Back to Libraries"}),r(n,{href:"/docs/libraries/overlay-engine",className:"btn-primary",children:["Next: Overlay Engine ",e(p,{size:16})]})]})]})}export{u as LibrariesPersonalizationPage};
+});`})]}),d(f,{className:"space-y-4",children:[b(h,{className:"font-bold text-2xl",children:"Agent Prompt"}),b(l,{className:"text-muted-foreground",children:"Use this when asking an agent to wire DataView preferences while preserving the personalization/design-system boundary."}),b(m,{language:"markdown",code:Y})]}),d(z,{className:"items-center gap-4 pt-4",children:[b(q,{href:"/docs/libraries",className:"btn-ghost",children:b(p,{children:"Back to Libraries"})}),d(q,{href:"/docs/libraries/overlay-engine",className:"btn-primary",children:[b(p,{children:"Next: Overlay Engine"})," ",b(J,{size:16})]})]})]})}export{i as LibrariesPersonalizationPage};

package/dist/components/docs/libraries/LibrariesTranslationRuntimePage.content.d.ts

@@ -0,0 +1,10 @@
+export declare const translationRuntimeInstall: string[];
+export declare const translationRuntimeExample = "import { createTranslationRuntime } from '@contractspec/lib.translation-runtime';\nimport { checkoutMessages } from './translations/checkout.messages';\n\nconst runtime = createTranslationRuntime({\n  catalogs: [checkoutMessages],\n  locale: 'fr-FR',\n  fallbackLocales: ['fr', 'en-US'],\n  onDiagnostic: (diagnostic) => reportTranslationIssue(diagnostic),\n});\n\nconst label = runtime.t('checkout.pay', {\n  amount: 4200,\n  currency: 'EUR',\n});";
+export declare const i18nextAdapterExample = "import { createInstance } from 'i18next';\nimport {\n  createI18nextInitOptions,\n  exportContractSpecToI18next,\n} from '@contractspec/lib.translation-runtime/i18next';\n\nconst exported = exportContractSpecToI18next([checkoutMessages], {\n  locale: 'en-US',\n  assumeIcuFormatter: true,\n});\nconst { options, diagnostics } = createI18nextInitOptions(exported, {\n  lng: 'en-US',\n});\n\nconst i18next = createInstance();\nawait i18next.init(options);\nreportAdapterDiagnostics(diagnostics);";
+export declare const ssrHydrationExample = "// Server: negotiate once, preload catalogs, and serialize the runtime snapshot.\nconst runtime = createTranslationRuntime({\n  catalogs,\n  locale: negotiatedLocale,\n  fallbackLocales,\n});\nconst snapshot = runtime.createSnapshot();\n\n// Client: hydrate from the same snapshot so locale, resources, and fallback state match.\nconst hydratedRuntime = createTranslationRuntime({ snapshot });";
+export declare const translationRuntimeChecks: string[];
+export declare const translationRuntimePrompt = "You are integrating ContractSpec translations into a production app.\nUse @contractspec/lib.contracts-spec/translations as the canonical contract layer and @contractspec/lib.translation-runtime as the runtime layer.\nKeep locale variants separate from stable bundle keys, support BCP 47 tags, preserve ICU plural/select/selectordinal messages, and use request-scoped runtime instances for SSR.\nIf the app already uses i18next, use @contractspec/lib.translation-runtime/i18next only as a downstream adapter. Do not make i18next the canonical translation model. Include diagnostics, fallback behavior, tenant/user override isolation, and hydration snapshot handling in the implementation and tests.";
+export declare const translationRuntimeLayers: {
+    title: string;
+    body: string;
+}[];

package/dist/components/docs/libraries/LibrariesTranslationRuntimePage.content.js

@@ -0,0 +1,43 @@
+// @bun
+var n=Object.defineProperty;var s=(e)=>e;function o(e,t){this[e]=s.bind(null,t)}var r=(e,t)=>{for(var a in t)n(e,a,{get:t[a],enumerable:!0,configurable:!0,set:o.bind(t,a)})};var i=(e,t)=>()=>(e&&(t=e(e=0)),t);var l=["@contractspec/lib.contracts-spec","@contractspec/lib.translation-runtime"],p=`import { createTranslationRuntime } from '@contractspec/lib.translation-runtime';
+import { checkoutMessages } from './translations/checkout.messages';
+
+const runtime = createTranslationRuntime({
+  catalogs: [checkoutMessages],
+  locale: 'fr-FR',
+  fallbackLocales: ['fr', 'en-US'],
+  onDiagnostic: (diagnostic) => reportTranslationIssue(diagnostic),
+});
+
+const label = runtime.t('checkout.pay', {
+  amount: 4200,
+  currency: 'EUR',
+});`,d=`import { createInstance } from 'i18next';
+import {
+  createI18nextInitOptions,
+  exportContractSpecToI18next,
+} from '@contractspec/lib.translation-runtime/i18next';
+
+const exported = exportContractSpecToI18next([checkoutMessages], {
+  locale: 'en-US',
+  assumeIcuFormatter: true,
+});
+const { options, diagnostics } = createI18nextInitOptions(exported, {
+  lng: 'en-US',
+});
+
+const i18next = createInstance();
+await i18next.init(options);
+reportAdapterDiagnostics(diagnostics);`,m=`// Server: negotiate once, preload catalogs, and serialize the runtime snapshot.
+const runtime = createTranslationRuntime({
+  catalogs,
+  locale: negotiatedLocale,
+  fallbackLocales,
+});
+const snapshot = runtime.createSnapshot();
+
+// Client: hydrate from the same snapshot so locale, resources, and fallback state match.
+const hydratedRuntime = createTranslationRuntime({ snapshot });`,u=["Keep TranslationSpec as the source of truth; do not flatten metadata into i18next JSON as the canonical model.","Keep stable bundle identity in TranslationSpec.meta.key and keep BCP 47 language tags in TranslationSpec.locale.","Use ICU messages for plural, select, selectordinal, number, date, currency, list, and relative-time formatting.","Create one runtime per SSR request when tenant, project, or user overrides are involved.","Serialize the same runtime snapshot or exported adapter resources used by the server for hydration.","Configure an ICU-capable i18next formatter plugin when rendering ContractSpec ICU messages through i18next.","Treat adapter diagnostics as release blockers in production pipelines instead of silently rendering raw keys."],h=`You are integrating ContractSpec translations into a production app.
+Use @contractspec/lib.contracts-spec/translations as the canonical contract layer and @contractspec/lib.translation-runtime as the runtime layer.
+Keep locale variants separate from stable bundle keys, support BCP 47 tags, preserve ICU plural/select/selectordinal messages, and use request-scoped runtime instances for SSR.
+If the app already uses i18next, use @contractspec/lib.translation-runtime/i18next only as a downstream adapter. Do not make i18next the canonical translation model. Include diagnostics, fallback behavior, tenant/user override isolation, and hydration snapshot handling in the implementation and tests.`,g=[{title:"Spec layer",body:"TranslationSpec owns keys, locales, domains, versions, owners, fallback declarations, direction, and validation metadata."},{title:"Runtime layer",body:"Runtime instances negotiate locales, apply fallback chains, resolve overrides, cache compiled messages, report diagnostics, and serialize SSR snapshots."},{title:"Adapter layer",body:"The i18next adapter projects ContractSpec specs or snapshots to resources and manifests for caller-owned i18next instances."}];export{h as translationRuntimePrompt,g as translationRuntimeLayers,l as translationRuntimeInstall,p as translationRuntimeExample,u as translationRuntimeChecks,m as ssrHydrationExample,d as i18nextAdapterExample};

package/dist/components/docs/libraries/LibrariesTranslationRuntimePage.d.ts

@@ -0,0 +1 @@
+export declare function LibrariesTranslationRuntimePage(): import("react/jsx-runtime").JSX.Element;

package/dist/components/docs/libraries/LibrariesTranslationRuntimePage.js

@@ -0,0 +1,43 @@
+// @bun
+var v=Object.defineProperty;var S=(a)=>a;function R(a,r){this[a]=S.bind(null,r)}var M=(a,r)=>{for(var l in r)v(a,l,{get:r[l],enumerable:!0,configurable:!0,set:R.bind(r,l)})};var O=(a,r)=>()=>(a&&(r=a(a=0)),r);var d=["@contractspec/lib.contracts-spec","@contractspec/lib.translation-runtime"],u=`import { createTranslationRuntime } from '@contractspec/lib.translation-runtime';
+import { checkoutMessages } from './translations/checkout.messages';
+
+const runtime = createTranslationRuntime({
+  catalogs: [checkoutMessages],
+  locale: 'fr-FR',
+  fallbackLocales: ['fr', 'en-US'],
+  onDiagnostic: (diagnostic) => reportTranslationIssue(diagnostic),
+});
+
+const label = runtime.t('checkout.pay', {
+  amount: 4200,
+  currency: 'EUR',
+});`,m=`import { createInstance } from 'i18next';
+import {
+  createI18nextInitOptions,
+  exportContractSpecToI18next,
+} from '@contractspec/lib.translation-runtime/i18next';
+
+const exported = exportContractSpecToI18next([checkoutMessages], {
+  locale: 'en-US',
+  assumeIcuFormatter: true,
+});
+const { options, diagnostics } = createI18nextInitOptions(exported, {
+  lng: 'en-US',
+});
+
+const i18next = createInstance();
+await i18next.init(options);
+reportAdapterDiagnostics(diagnostics);`,h=`// Server: negotiate once, preload catalogs, and serialize the runtime snapshot.
+const runtime = createTranslationRuntime({
+  catalogs,
+  locale: negotiatedLocale,
+  fallbackLocales,
+});
+const snapshot = runtime.createSnapshot();
+
+// Client: hydrate from the same snapshot so locale, resources, and fallback state match.
+const hydratedRuntime = createTranslationRuntime({ snapshot });`,g=["Keep TranslationSpec as the source of truth; do not flatten metadata into i18next JSON as the canonical model.","Keep stable bundle identity in TranslationSpec.meta.key and keep BCP 47 language tags in TranslationSpec.locale.","Use ICU messages for plural, select, selectordinal, number, date, currency, list, and relative-time formatting.","Create one runtime per SSR request when tenant, project, or user overrides are involved.","Serialize the same runtime snapshot or exported adapter resources used by the server for hydration.","Configure an ICU-capable i18next formatter plugin when rendering ContractSpec ICU messages through i18next.","Treat adapter diagnostics as release blockers in production pipelines instead of silently rendering raw keys."],f=`You are integrating ContractSpec translations into a production app.
+Use @contractspec/lib.contracts-spec/translations as the canonical contract layer and @contractspec/lib.translation-runtime as the runtime layer.
+Keep locale variants separate from stable bundle keys, support BCP 47 tags, preserve ICU plural/select/selectordinal messages, and use request-scoped runtime instances for SSR.
+If the app already uses i18next, use @contractspec/lib.translation-runtime/i18next only as a downstream adapter. Do not make i18next the canonical translation model. Include diagnostics, fallback behavior, tenant/user override isolation, and hydration snapshot handling in the implementation and tests.`,b=[{title:"Spec layer",body:"TranslationSpec owns keys, locales, domains, versions, owners, fallback declarations, direction, and validation metadata."},{title:"Runtime layer",body:"Runtime instances negotiate locales, apply fallback chains, resolve overrides, cache compiled messages, report diagnostics, and serialize SSR snapshots."},{title:"Adapter layer",body:"The i18next adapter projects ContractSpec specs or snapshots to resources and manifests for caller-owned i18next instances."}];import{CodeBlock as s,InstallCommand as U}from"@contractspec/lib.design-system";import{HStack as y,VStack as n}from"@contractspec/lib.design-system/layout";import{List as w,ListItem as C}from"@contractspec/lib.design-system/list";import{Code as p,H1 as z,H2 as c,H3 as D,P as i,Text as o}from"@contractspec/lib.design-system/typography";import I from"@contractspec/lib.ui-link";import{ChevronRight as K}from"lucide-react";import{jsx as e,jsxs as t}from"react/jsx-runtime";function G(){return t(n,{className:"space-y-8",children:[t(n,{className:"space-y-4",children:[e(o,{className:"editorial-kicker",children:"Runtime and adapters"}),e(z,{className:"font-serif text-4xl tracking-[-0.04em] md:text-5xl",children:"Translation runtime and i18next adapter"}),e(i,{className:"max-w-3xl text-lg text-muted-foreground leading-8",children:"Use ContractSpec as the canonical translation contract layer, then resolve and format messages through a framework-independent runtime. i18next is supported as an optional downstream adapter, not as the source of truth."})]}),t(n,{className:"space-y-4",children:[e(c,{className:"font-bold text-2xl",children:"Install the runtime"}),e(U,{package:d}),t(i,{className:"text-muted-foreground",children:[e(o,{children:"Add "}),e(p,{children:"i18next"}),t(o,{children:[" ","only when an app imports the adapter subpath. Core server, React, React Native, CLI, and test code can use the runtime without loading i18next."]})]})]}),e(y,{className:"grid gap-4 md:grid-cols-3",children:b.map((a)=>t(n,{className:"card-subtle space-y-2 p-5",children:[e(D,{className:"font-semibold text-lg",children:a.title}),e(i,{className:"text-muted-foreground text-sm leading-7",children:a.body})]},a.title))}),t(n,{className:"space-y-4",children:[e(c,{className:"font-bold text-2xl",children:"Use the ContractSpec runtime"}),t(i,{className:"text-muted-foreground",children:[e(o,{children:"The runtime consumes canonical "}),e(p,{children:"TranslationSpec[]"}),t(o,{children:[" ","catalogs, supports BCP 47 tags such as en-US, ar-EG, and zh-Hans, and delegates ICU parsing/formatting to a mature formatter engine instead of a custom parser."]})]}),e(s,{language:"typescript",code:u})]}),t(n,{className:"space-y-4",children:[e(c,{className:"font-bold text-2xl",children:"Project to i18next when needed"}),t(i,{className:"text-muted-foreground",children:[e(o,{children:"Import from "}),e(p,{children:"@contractspec/lib.translation-runtime/i18next"}),t(o,{children:[" ","to export resources by locale, namespace, and message key. The namespace defaults to the stable bundle key, dotted message keys stay flat with keySeparator false, and metadata remains in a sidecar manifest."]})]}),e(s,{language:"typescript",code:m})]}),t(n,{className:"space-y-4",children:[e(c,{className:"font-bold text-2xl",children:"SSR, streaming, and hydration"}),e(i,{className:"text-muted-foreground",children:"Negotiate locale on the server, preload catalogs needed for streamed content, and hydrate the client from the same serialized state. Never let client-only language detection choose a different locale after the server has rendered."}),e(s,{language:"typescript",code:h})]}),t(n,{className:"space-y-4",children:[e(c,{className:"font-bold text-2xl",children:"Production checklist"}),e(w,{className:"list-disc space-y-2 pl-6 text-muted-foreground",children:g.map((a)=>e(C,{children:a},a))})]}),t(n,{className:"space-y-4 rounded-xl border border-border p-6",children:[e(c,{className:"font-bold text-2xl",children:"Agent implementation prompt"}),e(i,{className:"text-muted-foreground",children:"Use this prompt when asking an agent to wire translations into a web, server, or React Native surface without losing ContractSpec ownership."}),e(s,{language:"markdown",code:f})]}),t(y,{className:"flex flex-wrap items-center gap-4 pt-4",children:[e(I,{href:"/docs/libraries/contracts",className:"btn-ghost",children:e(o,{children:"Translation contracts"})}),t(I,{href:"/docs/libraries/design-system",className:"btn-primary",children:[e(o,{children:"Design-system integration"}),e(K,{size:16})]})]})]})}export{G as LibrariesTranslationRuntimePage};

package/dist/components/docs/libraries/index.d.ts

@@ -24,6 +24,7 @@ export { LibrariesSchemaPage } from './LibrariesSchemaPage';
 export { LibrariesSLOPage } from './LibrariesSLOPage';
 export { LibrariesSupportBotPage } from './LibrariesSupportBotPage';
 export { LibrariesTestingPage } from './LibrariesTestingPage';
+export { LibrariesTranslationRuntimePage } from './LibrariesTranslationRuntimePage';
 export { LibrariesUIKitPage } from './LibrariesUIKitPage';
 export { LibrariesUIKitWebPage } from './LibrariesUIKitWebPage';
 export { LibrariesWorkflowComposerPage } from './LibrariesWorkflowComposerPage';