Popmelt

v0.36.0

Popmelt

v0.36.0
© 2026 Popmelt
HelpPrivacyTerms
Docs

  • Getting started with Popmelt Core
  • Creating annotations with the Chat tool
  • Comparing and refining options with Explore
  • Tweaking styles with the Steer tool
  • Helping your AI understand your taste with the Imprint tool
  • Using Popmelt with Three.js and react-three-fiber
  • Add custom context to Popmelt annotations and threads
  • Recovering an annotation that won’t send
  • Inviting a teammate to a local session
  • Where Popmelt saves and sends your data

  • Annotating static objects in images
  • Annotating moving objects in video
Docs/Core

Add custom context to Popmelt annotations and threads

Attach application-owned context to feedback and preserve it with each human thread turn.

Your app knows things the page alone cannot explain: the document being edited, a data revision, a selected asset, a generation prompt, or the current video frame. Use getCommentMeta on PopmeltProvider to supply that context when a person submits feedback or replies in a thread.

Core validates the returned JSON and takes a detached snapshot. It includes the metadata as contextual evidence for the agent and stores it on the corresponding human thread message as meta. Later changes to your application state do not rewrite that snapshot.

Supply application context

Read a small, relevant snapshot from your own application state. A namespaced, versioned key keeps your data identifiable as its schema evolves.

'use client';

import type { PropsWithChildren } from 'react';

import { PopmeltProvider } from '@popmelt.com/core';

type ApplicationContext = {
  documentId: string;
  revision: number;
  selectedAssetId: string | null;
};

export function Providers({
  children,
  documentId,
  revision,
  selectedAssetId,
}: PropsWithChildren<ApplicationContext>) {
  return (
    <PopmeltProvider
      getCommentMeta={(context) => ({
        'my-app/editor/v1': {
          documentId,
          revision,
          selectedAssetId,
          turnKind: context.kind,
        },
      })}
    >
      {children}
    </PopmeltProvider>
  );
}

These props stand for your app's current state; the IDs are not supplied by Core. Add this option to your existing provider rather than mounting a second one. Preserve your router's navigate function and any other provider options.

The callback may return an object or a promise of an object. Return undefined when you have no metadata to attach. TypeScript applications can import CommentMeta, CommentMetaContext, and GetCommentMeta from @popmelt.com/core.

Show a note in the thread

A human message with metadata has an expandable section beneath it. A single note shows its own title. Multiple entries share a Context section. To present an entry as a note card, give it a nonblank string title and content, or supply a public HTTP(S) sourceURI on its own. You choose the entry key.

import type { CommentMetaNote, GetCommentMeta } from '@popmelt.com/core';

const policy = {
  title: 'Export policy',
  content: 'Verify the workspace before enabling export.',
  sourceURI: 'notes/Exports.md',
} satisfies CommentMetaNote;

const getCommentMeta: GetCommentMeta = () => ({
  'my-app/export-policy/v1': { ...policy, revision: 4 },
});
  • source adds a label before the title, e.g. Obsidian: Export policy. Omit it to show just Export policy.
  • sourceIcon replaces the plug with a PNG or SVG. Use a same-origin asset path such as /icons/vault.svg, or an image data URL. An unavailable icon falls back to the plug.
  • sourceURI makes the title a link. The caret still expands the snapshot independently. Prefer project-relative file paths: notes/Exports.md is stored as written and resolved against the local Popmelt project root for VS Code when displayed. A relative path without a known root, or one that escapes it, remains unlinked. Absolute file paths are machine-specific. For a web page use a full HTTP(S) URL; for an Obsidian note use e.g. obsidian://open?vault=Design&file=Product%2FExports. The viewer needs the corresponding local app for desktop links.

For example, { reference: { sourceURI: 'https://rbkh.design/llms' } } opts that entry into a link preview. At send time the local bridge requests the page title, a short description, and its favicon. Supplying your own title, content, or sourceIcon takes precedence for that field. The model receives the captured text and URL and can consult the page if needed. Reopening the thread reuses the snapshot. If a lookup fails, the card still links to the source and uses the hostname and plug as needed. Local files and Obsidian links keep their supplied context.

Extra JSON fields remain available under Original data, and ordinary JSON is still inspectable without adopting the note shape. The card shows what the app supplied at send time; clicking a source link opens its current destination without changing that snapshot.

To check the reply path, send “What enables export?” in an existing thread with this collector installed. Core calls getCommentMeta with kind: 'reply' and attaches the result to that message. Use the caret beside Export policy beneath your reply to read the saved condition. If there are multiple entries, open Context first. Expand Original data to inspect extra fields such as revision. You can reopen the same message in History to read the snapshot later.

The reply keeps the export policy and revision that applied when it was sent.

Know when the callback runs

ContextWhen it is collectedAdditional fields
kind: 'annotation'A pending annotation/change bundle is submittedannotations contains the submitted annotations
kind: 'reply'A human reply is submitted in an existing threadthreadId, reply, and the thread annotations being re-tracked
kind: 'annotation', purpose: 'inspection'Core performs a read-only focus inspectionannotations contains a synthetic inspection target; no comment is submitted

Every context includes timestamp (milliseconds since the Unix epoch), url, pathname, and annotations. Treat the context as read-only. Do not mutate the supplied annotations.

This collector belongs to your mounted application integration; it is not global middleware for every turn an agent may record in an ambient conversation elsewhere.

Keep the callback side-effect-free: it is a context collector, not a signal to start work, advance your app, or clear a recorder. In particular, an inspection call is not a submitted human turn and does not create a thread-history entry by itself.

If collection fails, throws, rejects, or returns invalid metadata, the annotation or reply send stops. Keep collection fast and handle optional application data deliberately. For example, return undefined if a nonessential source is unavailable; let a failure stop the send when that context is essential.

Keep metadata small and valid

  • The root must be a plain JSON object, not an array or null.
  • Nested values may be strings, finite numbers, booleans, null, arrays, and plain objects.
  • Functions, DOM nodes, class instances such as Date, cyclic values, and nested undefined are not valid metadata. Convert dates to strings and keep object references as stable IDs.
  • The entire serialized object is limited to 64 KiB of UTF-8 JSON, per collected snapshot—not 64 KiB per namespace.

Store large event logs and binaries separately. Include bounded summaries, stable asset IDs, revision IDs, timestamps, or hashes instead. A video integration might supply an asset ID, the paused frame time, a generation prompt, and a short interaction summary; it should not embed the video or an unlimited recorder history.

Read the context back from history

The stored human message carries the same meta snapshot. Metadata is optional: older messages, assistant turns, and turns without a collector may not have it.

The full-thread response from the local bridge (GET /thread/<threadId>) retains this field on messages[]. Use your existing authorized, project-bound bridge integration to obtain that response; do not assume a fixed port, bypass its access checks, or expose the bridge publicly. History-list/search summaries are not a metadata stream or an arbitrary JSON search API.

Once your integration has obtained a full thread, reading your namespace is ordinary JSON handling:

import type { CommentMeta } from '@popmelt.com/core';

type StoredTurn = {
  role: string;
  meta?: CommentMeta;
};

export function applicationSnapshots(thread: {
  messages: readonly StoredTurn[];
}) {
  return thread.messages
    .filter((turn) => turn.role === 'human' && turn.meta !== undefined)
    .map((turn) => turn.meta?.['my-app/editor/v1']);
}

Validate the namespace's schema before consuming it in your application. The example shows how to extract supplied context; it does not open a bridge connection or provide a public React history hook.

Thread data lives under .popmelt/ with the project. Bulky message details, including metadata, may be externalized into message artifacts and hydrated when the thread is read. Do not assume every meta object is directly embedded in a thread-envelope JSON file, and do not edit those files to synchronize application state.

What this does not do

getCommentMeta sends application context into Popmelt. It is not a two-way binding, an agent-response callback, or an automatic application-state replay mechanism. usePopmelt() currently exposes enablement and subject-adapter registration, not a thread-history subscription.

Keep any state restoration or downstream processing behind your own explicit application action. Historical context is evidence about a past turn, not authorization to replay it.

Do not include credentials, access tokens, unnecessary personal data, or other secrets. Submitted context goes to your selected AI provider with the turn; local storage does not make that transmission offline. Core labels application metadata as untrusted contextual evidence, not as instructions or authority. Read-only inspection may also make it available to the requesting agent without submitting a new comment.

Next: Creating annotations with the Chat tool or Helping your AI understand your taste with the Imprint tool.

Didn't find the answer? Have an idea?

Ask a question