pmx-canvas 0.8.0 → 0.9.0

package/src/shared/agent-presence.ts

@@ -45,18 +45,26 @@ export interface AgentPresence {
   opCount: number;
   /**
    * The agent's REAL context window, when its host reports it (tokens used /
-   * window size). Null when no adapter reports — the top-bar meter then shows
-   * the pinned-context estimate against the configured budget instead, and
-   * says so.
+   * window size). Null when no adapter reports — the context chip then shows
+   * the brief's size against its budget instead.
    */
   contextUsage: { used: number; total: number } | null;
   lastSeenAt: string;
+  /**
+   * What this session has done since it attached (AgentContext.dc.html lens:
+   * "Claude · this session"): ids of the cards read, created, edited and
+   * pinned on the open board. Only on attached presences; counts every agent
+   * on the board, like the receipt.
+   */
+  session?: SessionTouches;
 }
 
-export interface ContextBudget {
-  /** Estimated tokens of the pinned-context payload. */
-  used: number;
-  total: number;
+export interface SessionTouches {
+  startedAt: string;
+  read: string[];
+  created: string[];
+  edited: string[];
+  pinned: string[];
 }
 
 /**
@@ -79,7 +87,6 @@ export interface AgentActivityEntry {
 
 export interface AgentPresenceSnapshot {
   presences: AgentPresence[];
-  budget: ContextBudget;
   /** True when any presence is attached — the master gate for agent chrome. */
   sessionActive: boolean;
   /** Most recent agent writes, newest first (bounded by MAX_ACTIVITY_ENTRIES). */
@@ -102,8 +109,6 @@ export const PRESENCE_TOOLING_SETTLE_MS = 4_000;
  * "Thinking" chips on a silent board. */
 export const PRESENCE_THINKING_SETTLE_MS = 3 * 60_000;
 export const MAX_PRESENCES = 16;
-/** Default `budget.total` when `PMX_CANVAS_CONTEXT_BUDGET_TOKENS` is unset. */
-export const CONTEXT_BUDGET_DEFAULT_TOKENS = 32_000;
 
 /**
  * Source labels that name a TRANSPORT, not an agent. A write arriving under
@@ -130,11 +135,6 @@ export function externalWriters(presences: readonly AgentPresence[]): AgentPrese
   return presences.filter((presence) => !presence.attached);
 }
 
-/** Rough token estimate for a JSON payload (chars / 4) — good enough for a meter. */
-export function estimateTokens(text: string): number {
-  return Math.ceil(text.length / 4);
-}
-
 /** Chip label per phase — shared by the top-bar chip and the on-canvas cursor chip. */
 export function agentPhaseLabel(presence: Pick<AgentPresence, 'phase' | 'detail'>): string {
   switch (presence.phase) {

package/src/shared/auto-arrange.ts

@@ -21,6 +21,7 @@ export interface ArrangeEdge {
   id: string;
   from: string;
   to: string;
+  toBoardId?: string;
 }
 
 export interface AutoArrangeResult {
@@ -184,6 +185,7 @@ function buildUnitGraphs(
   }
 
   for (const edge of edges) {
+    if (edge.toBoardId !== undefined) continue;
     const fromUnit = nodeToUnit.get(edge.from);
     const toUnit = nodeToUnit.get(edge.to);
     if (!fromUnit || !toUnit || fromUnit === toUnit) continue;

package/src/shared/boards.ts

@@ -1,8 +1,8 @@
-/** The Home category migrated 0.6 snapshots land on, so they do not bury the boards in use. */
-export const MIGRATED_SNAPSHOT_CATEGORY = 'From old snapshots';
+/** The Home folder migrated 0.6 snapshots land on, so they do not bury the boards in use. */
+export const MIGRATED_SNAPSHOT_FOLDER = 'From old snapshots';
 
 /** Slash-separated folder paths shared by the UI, HTTP/MCP and SDK. */
-export function normalizeBoardCategory(value: string | null): string | null {
+export function normalizeBoardFolder(value: string | null): string | null {
   if (!value?.trim()) return null;
   const parts = value.split('/').map((part) => part.trim());
   if (parts.length > 8) throw new Error('Folders can be nested up to 8 levels.');
@@ -13,6 +13,6 @@ export function normalizeBoardCategory(value: string | null): string | null {
 }
 
 /** Includes implicit parents, so a board in A/B can also be moved into A. */
-export function categoryAncestors(path: string): string[] {
+export function folderAncestors(path: string): string[] {
   return path.split('/').map((_, index, parts) => parts.slice(0, index + 1).join('/'));
 }

package/src/shared/knowledge-lifecycle.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+/** The same policy contract validates workspace writes and browser drafts. */
+export const lifecycleSchema = z
+  .strictObject({
+    decayType: z.enum(['reality', 'decision', 'dependency', 'relevance']),
+    rate: z.enum(['fast', 'medium', 'slow', 'durable']),
+    triggers: z.array(z.string().trim().min(1)),
+    revalidationMethod: z.string().trim().min(1),
+    cadenceDays: z.number().int().min(1).max(36500).optional(),
+  })
+  .refine((value) => value.rate !== 'medium' || value.cadenceDays !== undefined, {
+    path: ['cadenceDays'],
+    message: 'Medium lifecycle requires a cadence in days.',
+  });
+export const categorySchema = lifecycleSchema.safeExtend({
+  id: z.string().trim().min(1),
+  name: z.string().trim().min(1),
+  glyph: z.string().trim().min(1),
+});
+export type Lifecycle = z.infer<typeof lifecycleSchema>;
+export type KnowledgeCategory = z.infer<typeof categorySchema>;

package/src/shared/knowledge-presets.ts

@@ -0,0 +1,80 @@
+import type { KnowledgeCategory } from '../server/knowledge-lifecycle.js';
+
+const category = (
+  id: string,
+  name: string,
+  glyph: string,
+  decayType: KnowledgeCategory['decayType'],
+  rate: KnowledgeCategory['rate'],
+  revalidationMethod: string,
+): KnowledgeCategory => ({
+  id,
+  name,
+  glyph,
+  decayType,
+  rate,
+  revalidationMethod,
+  triggers: [],
+  ...(rate === 'medium' ? { cadenceDays: 90 } : {}),
+});
+const research = category(
+  'research',
+  'Research',
+  '⌕',
+  'reality',
+  'medium',
+  'Check the sources and conflicting evidence.',
+);
+const metric = category('metric', 'Metric', '▥', 'reality', 'fast', 'Re-read the source dashboard and compare.');
+const decision = category(
+  'decision',
+  'Decision',
+  '⚑',
+  'decision',
+  'durable',
+  'Check for a superseding decision and changed dependencies.',
+);
+const notes = category('notes', 'Notes', '✎', 'relevance', 'slow', 'Check relevance to the resumed task.');
+
+/** Editable starter data. No runtime behavior depends on these names or ids. */
+export const KNOWLEDGE_PRESETS: Record<string, { categories: KnowledgeCategory[]; folders: Record<string, string> }> = {
+  'Org · team · personal': {
+    categories: [
+      category('strategy', 'Strategy', '◎', 'relevance', 'slow', 'Check the current goals and decisions.'),
+      category('policy', 'Policy', '◇', 'decision', 'slow', 'Check with the policy owner.'),
+      decision,
+      research,
+      metric,
+      notes,
+    ],
+    folders: {
+      Org: 'strategy',
+      'Org/Policies': 'policy',
+      Team: 'research',
+      'Team/Decisions': 'decision',
+      'Team/Metrics': 'metric',
+      Personal: 'notes',
+    },
+  },
+  'Solo research': {
+    categories: [
+      category('question', 'Question', '?', 'relevance', 'slow', 'Check whether this question still matters.'),
+      category('source', 'Source', '▤', 'reality', 'medium', 'Re-read the original source.'),
+      category(
+        'finding',
+        'Finding',
+        '◉',
+        'dependency',
+        'durable',
+        'Compare the supporting and contradicting evidence.',
+      ),
+      category('note', 'Note', '✎', 'relevance', 'slow', 'Check relevance to the resumed task.'),
+    ],
+    folders: { Projects: 'question', 'Projects/Findings': 'finding', Sources: 'source', Notes: 'note' },
+  },
+  'Product team': {
+    categories: [research, metric, decision, notes],
+    folders: { Discovery: 'research', 'Discovery/Metrics': 'metric', Delivery: 'notes', Decisions: 'decision' },
+  },
+  Empty: { categories: [], folders: {} },
+};

package/src/shared/lifecycle-status.ts

@@ -0,0 +1,26 @@
+import type { MemoryTarget } from './memory-graph.js';
+
+export interface SourceQualification extends MemoryTarget {
+  title: string;
+  reasons: string[];
+  unavailable?: true;
+  contentRevision?: number;
+  observedRevision?: number;
+  observedAt?: string;
+}
+
+export interface LifecycleQualification {
+  retired: boolean;
+  unknown: boolean;
+  due: boolean;
+  reasons: string[];
+  changedSinceRead: boolean;
+  lastReadAt: string | null;
+  lastValidatedAt: string | null;
+  contentRevision: number;
+  contentChangedAt: string | null;
+  /** The revisions a validating reviewer must have inspected, qualified by source relation. */
+  observations: Record<string, number | null>;
+  sources: SourceQualification[];
+  relevance: 'card-pinned' | 'board-pinned' | 'not-selected';
+}

package/src/shared/memory-graph.ts

@@ -0,0 +1,74 @@
+/** Board-qualified identities: card IDs alone are not unique across a library. */
+export interface MemoryTarget {
+  boardId: string;
+  cardId?: string;
+}
+
+export interface WikiLink {
+  ref: string;
+  target?: MemoryTarget;
+}
+
+export function wikiLinksFromData(data: Record<string, unknown>): WikiLink[] {
+  if (!Array.isArray(data.wikiLinks)) return [];
+  return data.wikiLinks.flatMap((value: unknown) => {
+    if (!value || typeof value !== 'object') return [];
+    const link = value as Record<string, unknown>;
+    if (typeof link.ref !== 'string') return [];
+    const target = link.target as Record<string, unknown> | undefined;
+    return [
+      {
+        ref: link.ref,
+        ...(target && typeof target.boardId === 'string'
+          ? {
+              target: {
+                boardId: target.boardId,
+                ...(typeof target.cardId === 'string' ? { cardId: target.cardId } : {}),
+              },
+            }
+          : {}),
+      },
+    ];
+  });
+}
+
+export const memoryKey = (target: MemoryTarget): string => JSON.stringify([target.boardId, target.cardId ?? null]);
+
+export interface MemoryGraphNode extends MemoryTarget {
+  key: string;
+  kind: 'board' | 'card';
+  title: string;
+  summary: string;
+  folder: string | null;
+  inContext: boolean;
+  summaryOnly: true;
+  /** False when the focused view omits incident relations; cannot acknowledge all links. */
+  linksComplete?: boolean;
+  /** Card link revision captured with this projection. */
+  linksRevision?: number;
+  type?: string;
+  nodeCount?: number;
+  position?: { x: number; y: number };
+}
+
+export interface MemoryGraphEdge {
+  id: string;
+  from: string;
+  to: string;
+  kind: 'member' | 'portal' | 'wiki' | 'card' | 'previous';
+  relationKind?: string;
+  reason?: string;
+  label?: string;
+  type?: string;
+  source: MemoryTarget;
+  target: MemoryTarget;
+  missing: boolean;
+}
+
+export interface MemoryGraph {
+  nodes: MemoryGraphNode[];
+  edges: MemoryGraphEdge[];
+  unresolvedLinks: Array<{ source: MemoryTarget; ref: string }>;
+  focus: string | null;
+  depth: number;
+}

package/src/shared/relations.ts

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+
+export const relationKindSchema = z.string().trim().min(1).max(80);
+export const relationReasonSchema = z.string().trim().max(4000);
+export const relationDefinitionSchema = z.strictObject({
+  kind: relationKindSchema,
+  ink: z.enum(['supports', 'contradicts', 'cites', 'derived', 'informs', 'related']),
+  directed: z.boolean(),
+});
+export const relationVocabularySchema = z
+  .array(relationDefinitionSchema)
+  .max(64)
+  .refine(
+    (values) => new Set(values.map((value) => value.kind)).size === values.length,
+    'Relation kinds must be unique.',
+  );
+export type RelationDefinition = z.infer<typeof relationDefinitionSchema>;
+export const relationPresetSchema = z.strictObject({
+  id: z.string().trim().min(1),
+  name: z.string().trim().min(1).max(80),
+  vocabulary: relationVocabularySchema,
+});
+export type RelationPreset = z.infer<typeof relationPresetSchema>;
+
+export const RELATION_KINDS: RelationDefinition[] = [
+  { kind: 'supports', ink: 'supports', directed: true },
+  { kind: 'contradicts', ink: 'contradicts', directed: true },
+  { kind: 'cites', ink: 'cites', directed: true },
+  { kind: 'derived-from', ink: 'derived', directed: true },
+  { kind: 'answers', ink: 'informs', directed: true },
+  { kind: 'depends-on', ink: 'informs', directed: true },
+  { kind: 'supersedes', ink: 'informs', directed: true },
+  { kind: 'flow', ink: 'derived', directed: true },
+  { kind: 'related', ink: 'related', directed: false },
+];
+
+export const RELATION_PRESETS: Record<string, RelationDefinition[]> = {
+  Research: RELATION_KINDS.filter((item) =>
+    ['supports', 'contradicts', 'cites', 'derived-from', 'related'].includes(item.kind),
+  ),
+  Dependencies: RELATION_KINDS.filter((item) => ['depends-on', 'related'].includes(item.kind)),
+  Decision: [
+    { kind: 'option', ink: 'derived', directed: true },
+    { kind: 'if', ink: 'cites', directed: true },
+    { kind: 'rejected', ink: 'related', directed: true },
+    { kind: 'supersedes', ink: 'informs', directed: true },
+  ],
+  Flow: [
+    { kind: 'next', ink: 'derived', directed: true },
+    { kind: 'if-fails', ink: 'contradicts', directed: true },
+    { kind: 'loop', ink: 'related', directed: true },
+  ],
+};
+
+export function relationPreset(vocabulary: RelationDefinition[] = []): string | null {
+  return (
+    Object.entries(RELATION_PRESETS).find(
+      ([, preset]) =>
+        preset.length === vocabulary.length &&
+        preset.every((item) =>
+          vocabulary.some(
+            (entry) => entry.kind === item.kind && entry.ink === item.ink && entry.directed === item.directed,
+          ),
+        ),
+    )?.[0] ?? null
+  );
+}
+
+export function relationKind(edge: { kind?: string; type?: string }): string {
+  return (
+    edge.kind ??
+    (edge.type === 'relation' ? 'related' : edge.type === 'references' ? 'cites' : (edge.type ?? 'related'))
+  );
+}
+
+/** Direction is semantic, not inferred from ink or arrow decoration. */
+export function relationSourceEnd(edge: { kind?: string; type?: string }): 'from' | 'to' | null {
+  const kind = relationKind(edge);
+  if (kind === 'depends-on') return 'to';
+  if (['derived-from', 'contradicts', 'supersedes'].includes(kind)) return 'from';
+  return null;
+}
+
+export function relationDefinition(
+  edge: { kind?: string; type?: string },
+  vocabulary: RelationDefinition[] = [],
+): RelationDefinition {
+  const kind = relationKind(edge);
+  return (
+    vocabulary.find((item) => item.kind === kind) ??
+    RELATION_KINDS.find((item) => item.kind === kind) ?? { kind, ink: 'related', directed: true }
+  );
+}
+
+/** Keep the authored label and the explanation, rather than treating a label as a kind. */
+export function relationText(edge: { kind?: string; type?: string; label?: string | null; reason?: string }): string {
+  return `${edge.kind ?? edge.type ?? 'related'}${edge.label ? ` "${edge.label}"` : ''}${edge.reason ? ` (why: ${edge.reason})` : ''}`;
+}

package/src/shared/semantic-attention.ts

@@ -22,6 +22,7 @@ export interface SemanticWatchEdgeSummary {
   edgeType: CanvasEdge['type'];
   fromId: string;
   toId: string;
+  toBoardId?: string;
   fromTitle: string | null;
   toTitle: string | null;
 }
@@ -135,8 +136,9 @@ function summarizeEdge(edge: CanvasEdge, nodeMap: Map<string, CanvasNodeState>):
     edgeType: edge.type,
     fromId: edge.from,
     toId: edge.to,
+    ...(edge.toBoardId !== undefined ? { toBoardId: edge.toBoardId } : {}),
     fromTitle: getNodeTitle(nodeMap.get(edge.from)),
-    toTitle: getNodeTitle(nodeMap.get(edge.to)),
+    toTitle: edge.toBoardId === undefined ? getNodeTitle(nodeMap.get(edge.to)) : null,
   };
 }
 
@@ -326,6 +328,7 @@ export function formatCompactWatchEvent(event: SemanticWatchEvent): string {
 }
 
 export class SemanticWatchReducer {
+  private currentBoardId: string | null | undefined;
   private currentLayout: CanvasLayout | null = null;
   private currentPins = new Set<string>();
   private previousSpatial: SpatialContext | null = null;
@@ -339,6 +342,17 @@ export class SemanticWatchReducer {
   }
 
   handleMessage(message: SseMessage): SemanticWatchEvent[] {
+    if (message.event === 'context-pins-changed' || message.event === 'canvas-layout-update') {
+      const record = message.data && typeof message.data === 'object' ? (message.data as Record<string, unknown>) : {};
+      if (typeof record.boardId === 'string' || record.boardId === null) {
+        if (this.currentBoardId !== undefined && record.boardId !== this.currentBoardId) {
+          this.currentLayout = null;
+          this.currentPins.clear();
+          this.previousSpatial = null;
+        }
+        this.currentBoardId = record.boardId;
+      }
+    }
     if (message.event === 'context-pins-changed') {
       return this.handleContextPinsChanged(message.data);
     }

package/src/shared/tour.ts

@@ -1,8 +1,20 @@
 import { z } from 'zod';
 
 export const cameraSchema = z.object({ x: z.number(), y: z.number(), scale: z.number().positive() });
+/** A world-space box: `{ x, y }` is its top-left corner. */
+export const rectSchema = z.object({
+  x: z.number(),
+  y: z.number(),
+  width: z.number().positive(),
+  height: z.number().positive(),
+});
+export const tourTargetSchema = z.union([
+  z.strictObject({ nodeId: z.string().min(1) }),
+  z.strictObject({ rect: rectSchema }),
+  z.strictObject({ viewport: cameraSchema }),
+]);
 export const tourStopSchema = z.object({
-  target: z.union([z.strictObject({ nodeId: z.string().min(1) }), z.strictObject({ viewport: cameraSchema })]),
+  target: tourTargetSchema,
   duration: z.number().nonnegative().max(3600).optional(),
   easing: z.enum(['linear', 'ease-in-out', 'ease-out']).optional(),
   padding: z.number().nonnegative().optional(),
@@ -12,6 +24,7 @@ export const tourSchema = z.object({ stops: z.array(tourStopSchema).max(1000) })
 export type Tour = z.infer<typeof tourSchema>;
 export type TourStop = z.infer<typeof tourStopSchema>;
 export type Camera = z.infer<typeof cameraSchema>;
+export type Rect = z.infer<typeof rectSchema>;
 export interface TourNode {
   id: string;
   type: string;
@@ -30,15 +43,20 @@ export function derivedTour(nodes: TourNode[]): Tour {
 
 export function resolveStop(stop: TourStop, nodes: TourNode[], width: number, height: number): Camera {
   if ('viewport' in stop.target) return stop.target.viewport;
+  if ('rect' in stop.target) return fitRect(stop.target.rect, stop.padding, width, height);
   const id = stop.target.nodeId;
   const node = nodes.find((n) => n.id === id);
   if (!node) throw new Error(`Tour target not found: ${id}`);
-  const padding = stop.padding ?? 40;
+  return fitRect({ ...node.position, ...node.size }, stop.padding, width, height);
+}
+
+/** Centre a world-space rect in a width×height area with screen-space padding. */
+function fitRect(rect: Rect, padding = 40, width: number, height: number): Camera {
   if (padding * 2 >= Math.min(width, height)) throw new Error('Tour padding exceeds viewport');
-  const scale = Math.min((width - padding * 2) / node.size.width, (height - padding * 2) / node.size.height);
+  const scale = Math.min((width - padding * 2) / rect.width, (height - padding * 2) / rect.height);
   return {
-    x: width / 2 - (node.position.x + node.size.width / 2) * scale,
-    y: height / 2 - (node.position.y + node.size.height / 2) * scale,
+    x: width / 2 - (rect.x + rect.width / 2) * scale,
+    y: height / 2 - (rect.y + rect.height / 2) * scale,
     scale,
   };
 }

package/src/shared/workspace-settings.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+
+export const workspaceSettingsSchema = z.strictObject({
+  agentSessions: z.boolean(),
+  knowledgeLifecycle: z.boolean(),
+});
+
+export type WorkspaceSettings = z.infer<typeof workspaceSettingsSchema>;
+export const workspaceSettingsPatchSchema = workspaceSettingsSchema.partial();
+export const DEFAULT_WORKSPACE_SETTINGS: WorkspaceSettings = {
+  agentSessions: false,
+  knowledgeLifecycle: false,
+};

package/dist/types/client/canvas/ContextPinBar.d.ts

@@ -1 +0,0 @@
-export declare function ContextPinBar(): import("preact/src").JSX.Element | null;

package/dist/types/client/canvas/FocusFieldLayer.d.ts

@@ -1 +0,0 @@
-export declare function FocusFieldLayer(): import("preact/src").JSX.Element | null;

package/dist/types/client/canvas/kind-colors.d.ts

@@ -1,3 +0,0 @@
-import type { CanvasNodeState } from '../types';
-/** Kind color per node type, as CSS tokens so every theme keeps its palette. */
-export declare const KIND_COLOR: Record<CanvasNodeState['type'], string>;

package/dist/types/server/agent-context.d.ts

@@ -1,22 +0,0 @@
-import type { CanvasNodeState } from './canvas-state.js';
-export interface AgentContextNode {
-    id: string;
-    type: CanvasNodeState['type'];
-    kind: string;
-    title: string | null;
-    content: string | null;
-    metadata?: Record<string, unknown>;
-    position?: {
-        x: number;
-        y: number;
-    };
-}
-interface AgentContextOptions {
-    defaultTextLength?: number;
-    webpageTextLength?: number;
-    includePosition?: boolean;
-}
-export declare function summarizeNodeForAgentContext(node: CanvasNodeState, options?: AgentContextOptions): string;
-export declare function serializeNodeForAgentContext(node: CanvasNodeState, options?: AgentContextOptions): AgentContextNode;
-export declare function buildAgentContextPreamble(nodes: CanvasNodeState[], options?: AgentContextOptions): string;
-export {};

package/src/client/canvas/ContextPinBar.tsx

@@ -1,25 +0,0 @@
-import { clearContextPins, contextPinnedNodeIds } from '../state/canvas-store';
-import { attentionHistoryOpen } from '../state/attention-store';
-import { IconClose } from '../icons';
-
-export function ContextPinBar() {
-  const count = contextPinnedNodeIds.value.size;
-  if (count === 0 || attentionHistoryOpen.value) return null;
-
-  return (
-    <div class="context-pin-bar">
-      <span class="context-pin-bar-count">
-        {'\u2726'} {count} node{count !== 1 ? 's' : ''} in context
-      </span>
-      <button
-        type="button"
-        class="context-pin-bar-btn context-pin-bar-clear"
-        onClick={clearContextPins}
-        title="Clear all context pins"
-        aria-label="Clear all context pins"
-      >
-        <IconClose size={14} />
-      </button>
-    </div>
-  );
-}