SwimmerNerveKit

An application-aware collaboration layer for PieAI. One companion helps a person point at real objects, retrieve originals, compare possibilities and choose the next step. It is not another agent, model provider, task database or credential store.

Three common ways to connect

0.7.0 introduces a breaking host-language boundary. UIKit stays 2.11.0. Nerve keeps its phrasebook but no longer installs a language engine or requires one as a peer. See language and migration, University, Directing and CHANGELOG. Install the verified official version; no source aliases.

| Your application | Use | | --- | --- | | Fixed questions, deterministic help, no model | NerveLiquidInteraction with the host's questions and targets. Do not create an agent just to show help. | | Real AG-UI conversation | One createNerveConversation, shared by NerveLiquidConversation and NervePanel. Switching views never resends work. | | Settings and capability/connection information | Embed NerveDetailsPanel in the host's settings/side panel. Reuse Companion and Voice controls; opening settings never records audio. |

Wrap all three in NerveI18nProvider value={languageValue} name={hostName}. The host owns names, language, content, permissions, fees, persistence and placement.

Read only when needed

| Need | Guide | | --- | --- | | Connect the host engine once; migrate 0.6 language APIs | Host language | | Gesture, injected content order, liquid layout | Interaction | | A welcome, return or wrap-up message | Considerate openings | | Availability and touch hold-to-talk | Voice input | | Shared submission, admission, task recovery | Runtime | | Guide / Compare / Choice / Peek | Assistance | | Explicit DOM and spatial objects | Targets | | Appearance and opt-in Markdown | Companion | | Public imports | Entry points | | Older coordinated transition | 0.4 history |

The guides ship inside the package. Current implementation/release evidence is in Current Work, not another API source.

Ownership, not a pile of controllers

• Nerve owns bounded collaboration and request-time object references. All assistance sessions require an explicit host scope. controller.assistance is their one lifecycle, not a wrapper that creates a second task.
• The host owns its existing agent, durable tasks, authentication, cost, actual business actions, versioned saves, and recovery. It creates one createNerveConversation for the agent; liquid and full-record views share it.
• UIKit owns material, movement, controls and layout. The host places the companion. ProviderKit owns model/voice I/O and credentials.

A model response, animation callback, hover or display replay is not permission. Closing a view is not cancelling a task; stopping voice does not undo a save.

Primary interfaces

NerveLiquidInteraction works without an agent for deterministic quick help. NerveLiquidConversation and NervePanel take the same conversation owner when real AG-UI requests are available. Both share drafts, admission, amendments, unknown-result protection and stop; neither creates or restarts an agent on mount. NerveDetailsPanel is embeddable settings content, not a popup manager.

createObjectSelection captures up to two explicitly selected original objects. It exposes only semantic context to a model, with freshness checks for later commands. It does not infer course prerequisites, compare films or execute edits.

Language ownership

import { NerveI18nProvider } from "@pieai/swimmer-nerve-kit/i18n/react";

<NerveI18nProvider value={nerveLanguage(hostPreferences.locale)} name={hostCompanionName}>{existingNerveSurfaces}</NerveI18nProvider>;

The host's small nerveLanguage adapter is in the language guide. It registers Nerve's unchanged Chinese/English ICU catalogs with the host engine. ./i18n exports only structural types/validation; ./i18n/catalogs is plain data; ./i18n/react supplies context without choosing an engine or changing the document. Headless controllers require language: () => currentNerveLanguage; one-shot helpers take the value. Missing configuration is explicit, not hidden Chinese.

Default names stay 涟 / Ripple; saved names, memory and old observations are unchanged. A new outline uses createMemoryTemplate(language). Switching language or replacing a catalog updates expression, not task, microphone or editor identity. Do not add key={locale}. UI, settings and portals use the same provider tree.

Development still uses the existing I18nKit checker and generated parameter types. It is a devDependency only, not part of consumer runtime or peer requirements. pnpm i18n:check checks every catalog and visible TS/TSX literal; i18n:types regenerates the engine-independent types. Pseudo locales are explicitly supplied by development hosts. Formatters/locale selection belong to the host, not a copied parser in this package. Full contracts, helper signatures and exceptions are in the linked guide and swimmer-copy-scan.config.json.

Development and real demonstration

Use Node 24 and the package manager pinned in package.json.

pnpm install --frozen-lockfile
pnpm verify
pnpm test:browser
pnpm test:presence
pnpm docs:check
pnpm dev:liquid

The server prints a reserved loopback URL. / has genuine local retrieval, settings and liquid UI. /spatial has actual Three.js objects, bounded pair selection, pmndrs pointer/layout integration, and explicitly enabled IWER XR emulation. These dev-only dependencies are not imported by the runtime package. The main page does not download the spatial bundle. No real model or microphone is configured; emulation does not prove physical-headset comfort or accuracy.

Set NERVE_PEEK_UNIVERSITY=../University only on an explicitly intended demo or corpus test. User-chosen files remain in page memory; no default test discovers private accounts or reads neighbouring product data. Evidence uses disposable works; source tests are not provider/production acceptance.

Release

npm-publish.yml is manual and defaults to verification only. Publication uses the package's configured trusted publisher, after browser/type/package/doc gates. A local pack is not publication; registry tarball integrity and contents must be verified afterwards. Product integration and deployment are separate gates. Registry visibility may lag publication: verification retries reads only, checks the prepared archive's integrity and downloads its exact bytes. An uncertain verification is never permission to run npm publish a second time.

License: LICENSE. The package release does not change repository access.