@popmelt.com/core 0.18.1 → 0.19.0

package/README.md

@@ -158,6 +158,40 @@ export function Providers({ children }: { children: React.ReactNode }) {
 
 `navigate` is optional for single-page use. Pass your router's navigation function when Popmelt needs to restore annotations across routes.
 
+### Add application context to comments
+
+Use `getCommentMeta` to snapshot application-owned context whenever a human
+submits annotations or replies in a thread. Popmelt validates and detaches the
+JSON, includes it as contextual evidence for the model, and persists the same
+snapshot with the stored human turn.
+
+```tsx
+<PopmeltProvider
+  getCommentMeta={({ kind }) => ({
+    'my-app/video-ui/v1': {
+      kind,
+      generation: {
+        prompt: generation.prompt,
+        dataVersion: store.getState().version,
+      },
+      frame: {
+        assetId: video.id,
+        timeMs: Math.round(video.currentTime * 1000),
+      },
+      interactions: recorder.snapshot(),
+    },
+  })}
+>
+  {children}
+</PopmeltProvider>
+```
+
+The hook may be synchronous or asynchronous. Return a plain JSON object; use a
+namespaced, versioned key so multiple integrations can coexist. Comment
+metadata is limited to 64 KiB per human turn. Keep large binaries and long
+event logs in external storage or attachments and place their stable IDs,
+hashes, and timestamps in `meta`.
+
 ### Next.js
 
 Next.js needs both the command wrapper and the config wrapper.

package/codex-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "popmelt-core",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "Ambient project memory and shared understanding for Codex",
   "author": {
     "name": "Popmelt",

package/dist/adapter-react-three-fiber.d.mts

@@ -1,5 +1,5 @@
 import { Camera, Object3D, Raycaster } from 'three';
-import { P as PopmeltSubjectAdapter } from './subjects-CeqtFged.mjs';
+import { P as PopmeltSubjectAdapter } from './subjects-C6Bu8uSX.mjs';
 
 type ThreeSubjectAdapterOptions = {
     /** Unique adapter identity when a page owns more than one Three.js surface. */

package/dist/adapter-three.d.mts

@@ -87,6 +87,12 @@ type PopmeltSubjectTrackingAnchor = {
     /** Vertical position normalized within the subject bounds. */
     y: number;
 };
+type PopmeltSubjectOutlinePoint = {
+    /** Horizontal position normalized within the subject bounds. */
+    x: number;
+    /** Vertical position normalized within the subject bounds. */
+    y: number;
+};
 type PopmeltSubject = {
     key: string;
     label: string;
@@ -101,6 +107,8 @@ type PopmeltSubject = {
     videoObject?: VideoObjectContext;
     /** Optional provider-neutral foreground anchors used by motion tracking. */
     trackingAnchors?: readonly PopmeltSubjectTrackingAnchor[];
+    /** Optional provider-neutral contour normalized within the subject bounds. */
+    outline?: readonly PopmeltSubjectOutlinePoint[];
 };
 type PopmeltSurfaceSnapshot = {
     element: HTMLCanvasElement;
@@ -125,6 +133,13 @@ type PopmeltSubjectAdapter = {
     surfaceKind?: 'image' | 'video';
     /** Resolve once the adapter's persisted subject index is available. */
     whenReady?(): Promise<void>;
+    /** Notify Core when asynchronous perception changes hit-testable subjects. */
+    subscribe?(listener: () => void): () => void;
+    /** Ordered hit candidates, innermost/most-specific first. */
+    hitTestAll?(clientPoint: {
+        x: number;
+        y: number;
+    }): readonly PopmeltSubject[];
     hitTest(clientPoint: {
         x: number;
         y: number;
@@ -147,6 +162,8 @@ type PopmeltSubjectAdapter = {
     updateSubjectBounds?(key: string, bounds: PopmeltSubjectBounds): PopmeltSubject | null;
     /** Replace optional foreground anchors normalized within subject bounds. */
     updateSubjectTrackingAnchors?(key: string, anchors: readonly PopmeltSubjectTrackingAnchor[]): PopmeltSubject | null;
+    /** Promote a transient perception candidate into a durable subject. */
+    promoteSubject?(key: string): PopmeltSubject | null;
     /** Remove a user-created subject or hide an adapter-owned subject. */
     removeSubject?(key: string): void;
 };