Share data between extensions by name, not by copy.

Who uses it

Infrastructure for the other extensions.

Named Data has almost no blocks of its own. Its value is the registry that data-owning extensions share. Separately bundled extensions find the same registry through the stable key Symbol.for('@kubohiroya/turbowarp-named-data/registry'), so load order and bundling do not split it.

Quick start

Enable, load, check.

The registry is a startup-fixed feature that is off by default. The flag is read once when the bundle starts, so it must be set before the extension loads.

1. Enable the feature flag

   In the host page, or in the editor's browser console for a quick test, set:

   globalThis.__TW_NAMED_DATA_FEATURE_FLAGS__ = {
     NAMED_DATA_REGISTRY_MVP: true
   };

2. Load the extension

   In TurboWarp, choose Add Extension → Custom Extension, use this file, and enable Run extension without sandbox:

   https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-named-data@0.4.0/dist/named-data.js

3. Check availability

   The single Boolean block confirms that the shared registry was installed.

   if <named data registry available?> then
     say [ready]

How it works

The registry routes; providers own the data.

The registry keeps only provider registrations, keyed by (namespace, kind), and the release callbacks of bodies that are currently open. Payload, storage, and caching stay inside each provider.

What a reference contains

What a provider returns

Composition API

Provide and consume from your own extension.

Other packages import the side-effect-free ESM entrypoint. Importing it does not register a TurboWarp extension; it only exposes the contract, registry functions, and feature-flag declarations.

pnpm add --save-exact @kubohiroya/turbowarp-named-data@0.4.0

import {
  installNamedDataRegistry,
  type NamedDataProvider
} from '@kubohiroya/turbowarp-named-data/composition';

const registry = installNamedDataRegistry(runtime);
const provider: NamedDataProvider = {
  namespace: 'com.example.notes',
  kind: 'document',
  canResolve: (ref, rep) => rep === 'markdown',
  stat: (ref, rep, ctx) => ({ /* metadata */ }),
  openBody: (ref, rep, ctx) => ({ /* metadata, body, release */ }),
  release: () => {}
};
const registration = registry.registerProvider(provider);

import {getNamedDataRegistry}
  from '@kubohiroya/turbowarp-named-data/composition';

const registry = getNamedDataRegistry(runtime);
const opened = await registry?.openBody(
  {namespace: 'com.example.notes', name: 'intro',
   kind: 'document', scope: 'project'},
  'markdown',
  {project: projectIdentity}
);
try {
  // read opened.body
} finally {
  await opened?.release('complete');
}

Types are published from dist/types/composition.d.ts. The wire-safe reference shape is also available as a JSON Schema.

Lifecycle and schema identity

Stop cleans up; schemas are named, never guessed.

When the project stops

1. Every open body handle is released.
2. Session providers are unregistered and released.
3. Persistent providers keep their registration and run clearSession().

Registrations are session-scoped unless registered with {lifetime: 'persistent'}. Release operations are idempotent, so a provider can safely be released more than once.

Optional schema references

Structured references may carry schemaRef: {id, version}, for example {id: 'com.example.profile', version: '1.2.0'}. The provider must return the exact same identity in its metadata. The registry transports the identity only; schema documents, validators, and JSON values remain the provider's and consumer's responsibility. Providers publish schema references only when the separate startup flag NAMED_DATA_SCHEMA_REF is enabled (default off).

Reference

Blocks, flags, and error codes

Error codes

Troubleshooting

When a reference does not resolve