@popmelt.com/core 0.22.1 → 0.24.0

package/dist/server.d.mts

@@ -1,5 +1,73 @@
+import * as node_http from 'node:http';
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+declare const STICKER_COLOR_NAMES: readonly ["slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose"];
+type StickerColorName = (typeof STICKER_COLOR_NAMES)[number];
+
+declare const STICKER_FAMILIES: readonly ["padding", "margin", "border", "radius", "stack", "grid", "text", "color", "transform", "opacity"];
+type StickerFamily = (typeof STICKER_FAMILIES)[number];
+type StickerSubproperty = 'all' | 'x' | 'y' | 'top' | 'right' | 'bottom' | 'left' | 'top-left' | 'top-right' | 'bottom-right' | 'bottom-left' | 'vertical' | 'horizontal' | 'direction' | 'gap' | 'align' | 'justify' | 'rows' | 'columns' | 'size' | 'weight' | 'line-height' | 'letter-spacing' | 'text-align' | 'color' | 'translate' | 'scale' | 'rotate' | 'opacity' | 'mix-blend' | StickerColorName;
+
 type Provider = 'claude' | 'codex' | 'copilot' | 'omp';
 
+/** Renderer-owned identity for a target that does not exist as a DOM node. */
+type OpaqueTargetReference = {
+    adapter: string;
+    key: string;
+};
+
+/** Local preview protocol. Peers never supply reducer actions or host authority. */
+type PeerAction = {
+    type: 'tokens';
+    family?: StickerFamily;
+    subproperty?: StickerSubproperty;
+} | {
+    type: 'inspect';
+    selector: string;
+    target?: OpaqueTargetReference;
+    properties?: string[];
+    plane?: 'own' | 'host';
+} | {
+    type: 'comment';
+    selector: string;
+    target?: OpaqueTargetReference;
+    text: string;
+} | {
+    type: 'clear';
+    selector: string;
+    kind: 'comment' | 'style' | 'all';
+} | {
+    type: 'style';
+    selector: string;
+    property: string;
+    value: string;
+} | {
+    type: 'style';
+    selector: string;
+    token: string;
+    family?: StickerFamily;
+} | {
+    type: 'attention';
+    selector: string | null;
+    target?: OpaqueTargetReference;
+    activity?: 'looking' | 'working';
+} | {
+    type: 'undo' | 'redo' | 'send' | 'rebase';
+};
+
+/** A capability for a person/agent. Keep out of URLs, logs, and peer snapshots. */
+type ParticipantCredential = {
+    participantId: string;
+    token: string;
+};
+
+/** Browser hosting is replaceable; this boundary owns only local agent enrollment. */
+type ParticipantAgentView = {
+    act(action: PeerAction): Promise<unknown>;
+    close(): Promise<void>;
+};
+type ParticipantAgentAdapter = (credential: ParticipantCredential) => Promise<ParticipantAgentView>;
+
 type ImprintExplanationKind = 'intention' | 'principle' | 'pattern';
 type ImprintExplanationState = 'emerging' | 'testing' | 'grounded' | 'challenged' | 'retired';
 type ImprintScopeKind = 'project' | 'route' | 'component' | 'selector' | 'file';
@@ -200,14 +268,66 @@ type PopmeltOptions = {
     /** Optional Chromium DevTools endpoint, e.g. http://127.0.0.1:9222. */
     nativeCaptureUrl?: string;
     restartMode?: 'embedded' | 'detached';
+    /** Internal opt-in. Collaboration authority is independent of app revisions. */
+    participantSessions?: {
+        /** Optional context metadata. Never used as a save, Send, or approval gate. */
+        sourceRevision?: () => Promise<string>;
+        agentAdapter?: ParticipantAgentAdapter;
+    };
 };
 type PopmeltHandle = {
     port: number;
     projectId: string;
     storeId?: string;
+    /** Trusted local launch/recovery only; never publish this capability in HTML. */
+    participantHost?: () => Promise<ParticipantCredential>;
     close: () => Promise<void>;
 };
 
+/** One disposable, local Chrome profile per agent. Never attaches to a user's browser. */
+declare function managedParticipantBrowser(url: string): ParticipantAgentAdapter;
+
+/** Same-origin host continuity adapter. A private claim or existing host proof is
+ * mandatory before issuing the HttpOnly recovery capability. Localhost is not proof. */
+declare function createParticipantHostEntry(options: {
+    projectRoot: string;
+    projectId: string;
+    origin: string;
+    host: () => Promise<ParticipantCredential>;
+}): Promise<{
+    handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+    claimUrl: string;
+}>;
+
+/** Public, credential-free description stamped by the application's dev server.
+ * The revision is context metadata (or `unversioned`), never sync/Send authority.
+ */
+type ParticipantBootstrapConfig = {
+    version?: 1;
+    url: string;
+    projectId: string;
+    revision: string;
+};
+declare global {
+    interface Window {
+        __POPMELT_PARTICIPANTS__?: ParticipantBootstrapConfig;
+    }
+}
+
+/** Dev-server boundary: identify the project and optional source context, and
+ * keep host proof in a private local file, never in public bootstrap metadata.
+ * The framework owns the bridge lifecycle. No source hashing is required.
+ */
+declare function createParticipantDevBootstrap(options: {
+    projectRoot: string;
+    origin: string;
+    bridge: PopmeltHandle;
+    sourceRevision?: () => Promise<string>;
+}): Promise<{
+    hostEntry: (req: node_http.IncomingMessage, res: node_http.ServerResponse) => Promise<void>;
+    read(): Promise<ParticipantBootstrapConfig>;
+}>;
+
 type ImprintManifest = {
     version: 1;
     topologyVersion?: 2;
@@ -372,6 +492,7 @@ declare function parseImprintDraft(responseText: string, parseContext?: ImprintP
 };
 declare function formatImprintPrompt(context: ImprintContext | undefined, options?: {
     requestText?: string;
+    delivery?: 'bridge' | 'ambient';
 }): string;
 declare class ImprintService {
     readonly store: ImprintStore;
@@ -415,4 +536,4 @@ type StartPopmeltOptions = PopmeltOptions & {
 };
 declare function startPopmelt(options?: StartPopmeltOptions): Promise<PopmeltHandle>;
 
-export { type ImprintConcrete, type ImprintContext, type ImprintEvidence, type ImprintExplanation, type ImprintExplanationKind, type ImprintExplanationRef, type ImprintExplanationState, type ImprintGraph, type ImprintGroundingAction, type ImprintMutation, type ImprintRelation, type ImprintRelationType, type ImprintScope, ImprintService, ImprintStore, type ImprintThreadSummary, type ImprintTransaction, type PopmeltHandle, type PopmeltOptions, type QualifiedImprintRelation, type StartPopmeltOptions, formatImprintPrompt, imprintExplanationRef, parseImprintDraft, qualifyImprintRelation, startPopmelt };
+export { type ImprintConcrete, type ImprintContext, type ImprintEvidence, type ImprintExplanation, type ImprintExplanationKind, type ImprintExplanationRef, type ImprintExplanationState, type ImprintGraph, type ImprintGroundingAction, type ImprintMutation, type ImprintRelation, type ImprintRelationType, type ImprintScope, ImprintService, ImprintStore, type ImprintThreadSummary, type ImprintTransaction, type ParticipantAgentAdapter, type ParticipantAgentView, type PopmeltHandle, type PopmeltOptions, type QualifiedImprintRelation, type StartPopmeltOptions, createParticipantDevBootstrap, createParticipantHostEntry, formatImprintPrompt, imprintExplanationRef, managedParticipantBrowser, parseImprintDraft, qualifyImprintRelation, startPopmelt };