@nbt-dev/components 0.0.5

package/src/editor/nbt-language.ts

@@ -0,0 +1,151 @@
+// NBT syntax highlighting for CodeMirror 6 — a StreamLanguage tokenizer ported
+// from the console tokenizer (modules/lang_common/scan.jai) and the VSCode
+// grammar (editors/vscode/nbt/syntaxes/nbt.tmLanguage.json). Highlighting is
+// local; everything semantic (diagnostics/completion/hover) comes via the LSP.
+
+import {
+  StreamLanguage,
+  LanguageSupport,
+  indentUnit,
+  type StreamParser,
+} from "@codemirror/language";
+
+const KEYWORDS = new Set([
+  "entity", "enum", "struct", "const", "export", "extends",
+  "fn", "on", "action", "activity", "task", "variant", "workflow", "command",
+  "middleware", "schedule", "every", "jai",
+  "migration", "test", "mock", "assert",
+  "cartridge", "service", "component", "app", "route", "layout",
+  "import", "from",
+  "if", "elif", "else", "while", "for", "in", "return", "break", "continue",
+  "delete", "defer", "print", "sleep", "fail",
+]);
+
+const TYPES = new Set([
+  "string", "bool", "ulid", "document", "dict", "blob", "DateTime",
+  "u8", "u16", "u32", "u64", "s8", "s16", "s32", "s64",
+  "int", "integer", "float", "float64", "f32", "f64", "double",
+  "time", "bytes", "any", "name", "ref",
+]);
+
+type NbtState = {
+  tripleString: boolean;
+};
+
+// NBT strings carry NO escapes (scan.jai consumes to the bare closing quote),
+// so a backslash before a quote does not extend the string.
+function eatSingleLineString(stream: StringStream, quote: string): string {
+  while (!stream.eol()) {
+    if (stream.next() === quote) break;
+  }
+  return "string";
+}
+
+type StringStream = Parameters<StreamParser<NbtState>["token"]>[0];
+
+const nbtParser: StreamParser<NbtState> = {
+  name: "nbt",
+  startState: () => ({ tripleString: false }),
+  token(stream, state) {
+    if (state.tripleString) {
+      while (!stream.eol()) {
+        if (stream.match('"""')) {
+          state.tripleString = false;
+          return "string";
+        }
+        stream.next();
+      }
+      return "string";
+    }
+
+    if (stream.eatSpace()) return null;
+
+    const ch = stream.peek();
+    if (ch == null) return null;
+
+    if (ch === "#") {
+      stream.skipToEnd();
+      return "comment";
+    }
+
+    if (stream.match('"""')) {
+      state.tripleString = true;
+      // Rest of line is string body unless it closes on the same line.
+      while (!stream.eol()) {
+        if (stream.match('"""')) {
+          state.tripleString = false;
+          return "string";
+        }
+        stream.next();
+      }
+      return "string";
+    }
+
+    if (ch === '"') {
+      stream.next();
+      return eatSingleLineString(stream, '"');
+    }
+    if (ch === "'") {
+      // Like the scanner: only a string opener when not glued to an identifier
+      // (lets contractions inside docs pass).
+      const before = stream.string.charAt(stream.pos - 1);
+      if (!/[A-Za-z0-9_]/.test(before)) {
+        stream.next();
+        return eatSingleLineString(stream, "'");
+      }
+      stream.next();
+      return null;
+    }
+
+    // f-strings: f"..." — body highlighted as a string (interpolation holes
+    // are cosmetic only).
+    if (ch === "f" && stream.string.charAt(stream.pos + 1) === '"') {
+      stream.next();
+      stream.next();
+      return eatSingleLineString(stream, '"');
+    }
+
+    // @attr / @@attr
+    if (ch === "@") {
+      stream.next();
+      stream.eat("@");
+      stream.eatWhile(/[A-Za-z0-9_]/);
+      return "meta";
+    }
+
+    // Numbers. The optional fraction backtracks on `0..9` ranges (matches "0",
+    // not "0.").
+    if (/\d/.test(ch)) {
+      stream.match(/^\d+(\.\d+)?/);
+      return "number";
+    }
+
+    if (/[A-Za-z_]/.test(ch)) {
+      stream.eatWhile(/[A-Za-z0-9_]/);
+      const word = stream.current();
+      if (word === "true" || word === "false") return "atom";
+      if (KEYWORDS.has(word)) return "keyword";
+      if (TYPES.has(word)) return "typeName";
+      if (/^[A-Z]/.test(word)) return "typeName"; // entity/enum references
+      return "variableName";
+    }
+
+    if (/[+\-*/=<>!&|?.,:;]/.test(ch)) {
+      stream.next();
+      stream.eatWhile(/[+\-*/=<>!&|.]/);
+      return "operator";
+    }
+
+    stream.next();
+    return null;
+  },
+  languageData: {
+    commentTokens: { line: "#" },
+  },
+};
+
+export const nbtLanguage = StreamLanguage.define(nbtParser);
+
+export function nbtLanguageSupport(): LanguageSupport {
+  return new LanguageSupport(nbtLanguage, [indentUnit.of("  ")]);
+}

package/src/generated/bulk-protocol.ts

@@ -0,0 +1,63 @@
+// Wire constants mirrored from modules/cart/ws.jai (CART_WS_* + cart_ws_type_byte).
+
+// Frame types (first byte of each WS binary message).
+export const FRAME_SCHEMA = 0x01;
+export const FRAME_DATA = 0x02;
+export const FRAME_DATA_END = 0x03;
+export const FRAME_DELTA_INS = 0x04;
+export const FRAME_DELTA_UPD = 0x05;
+export const FRAME_DELTA_DEL = 0x06;
+export const FRAME_ERROR = 0xff;
+
+// Column type bytes (schema frame, per column).
+export const TYPE_U8 = 0x01;
+export const TYPE_U16 = 0x02;
+export const TYPE_U32 = 0x03;
+export const TYPE_U64 = 0x04;
+export const TYPE_S8 = 0x05;
+export const TYPE_S16 = 0x06;
+export const TYPE_S32 = 0x07;
+export const TYPE_S64 = 0x08;
+export const TYPE_BOOL = 0x09;
+export const TYPE_FLOAT32 = 0x0a;
+export const TYPE_FLOAT64 = 0x0b;
+export const TYPE_STRING = 0x0c;
+export const TYPE_DATETIME = 0x0d;
+export const TYPE_DOCUMENT = 0x0e;
+
+export type ColumnDef = {
+  name: string;
+  type: number;
+  fixedSize: number; // 0 for variable-width (string, document)
+};
+
+export type SchemaFrame = {
+  totalRows: number;
+  columns: ColumnDef[];
+};
+
+export type DeltaFrame = {
+  op: number;
+  rowData?: string[];
+  id?: string; // DELETE carries the row id as a len-prefixed string
+};
+
+export function fixedSizeForType(type: number): number {
+  switch (type) {
+    case TYPE_U8: return 1;
+    case TYPE_U16: return 2;
+    case TYPE_U32: return 4;
+    case TYPE_U64: return 8;
+    case TYPE_S8: return 1;
+    case TYPE_S16: return 2;
+    case TYPE_S32: return 4;
+    case TYPE_S64: return 8;
+    case TYPE_BOOL: return 1;
+    case TYPE_FLOAT32: return 4;
+    case TYPE_FLOAT64: return 8;
+    case TYPE_STRING: return 0;
+    case TYPE_DATETIME: return 8;
+    case TYPE_DOCUMENT: return 0;
+    default: return 0;
+  }
+}

package/src/graph/diagram.tsx

@@ -0,0 +1,296 @@
+import React from "react";
+import {
+  Background,
+  BackgroundVariant,
+  Controls,
+  MarkerType,
+  ReactFlow,
+  ReactFlowProvider,
+  useNodesInitialized,
+  useReactFlow,
+  type Edge,
+  type Node,
+} from "@xyflow/react";
+// ReactFlow's stylesheet ships inlined in @nbt-dev/devtools/styles.css.
+import { useDevToolsConfig } from "../core/config";
+import { authHeaders } from "../core/auth";
+import { useBulkRowCounts } from "../core/use-bulk-stream";
+import type { BulkRegistry } from "../core/use-cartridge-info";
+import { EntityNode } from "./entity-node";
+import {
+  buildEntityGraphModel,
+  cartsFromContracts,
+  entityGraphId,
+  filterEntityGraphModel,
+  type Contract,
+  type EntityGraphModel,
+  type EntityGraphNodeData,
+} from "./entity-graph-utils";
+
+const nodeTypes = { entity: EntityNode };
+
+// Custom nodes are measured asynchronously after mount, so the `fitView` prop
+// fits to zero-size bounds on first paint (boxes end up off-screen). Refit once
+// nodes report measured dimensions, and again whenever the visible set changes.
+const FitOnReady: React.FC<{ fitKey: string }> = ({ fitKey }) => {
+  const initialized = useNodesInitialized();
+  const { fitView } = useReactFlow();
+  React.useEffect(() => {
+    if (initialized) fitView({ padding: 0.25, duration: 200 });
+  }, [initialized, fitKey, fitView]);
+  return null;
+};
+
+type EntityFlowEdge = Edge<Record<string, unknown>, "smoothstep"> & {
+  pathOptions: { borderRadius: number; offset: number };
+};
+
+function useContracts() {
+  const { apiBaseUrl } = useDevToolsConfig();
+  const [contracts, setContracts] = React.useState<Contract[]>([]);
+  const [loading, setLoading] = React.useState(true);
+  const [error, setError] = React.useState<string | null>(null);
+
+  React.useEffect(() => {
+    const ac = new AbortController();
+    let cancelled = false;
+    (async () => {
+      try {
+        const r = await fetch(`${apiBaseUrl}/_console/contracts`, {
+          signal: ac.signal,
+          credentials: "include",
+          headers: authHeaders(),
+        });
+        if (!r.ok) throw new Error(`HTTP ${r.status}`);
+        const data = (await r.json()) as Contract[];
+        if (!Array.isArray(data)) throw new Error("malformed contracts response");
+        if (!cancelled) setContracts(data);
+      } catch (e) {
+        if (cancelled || (e as { name?: string }).name === "AbortError") return;
+        setError(e instanceof Error ? e.message : String(e));
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+      ac.abort();
+    };
+  }, [apiBaseUrl]);
+
+  return { contracts, loading, error };
+}
+
+// Derive the bulk WS registry off the same contracts so live row counts work
+// through the shared socket (the provider preloads each entity's SCHEMA, which
+// carries totalRows). Mirrors buildRegistry in use-cartridge-info.
+function registryFromContracts(contracts: Contract[]): BulkRegistry {
+  const reg: BulkRegistry = {};
+  for (const c of contracts) {
+    if (!c.cartridge || !c.owns) continue;
+    const entities = Object.keys(c.owns).map((name) => ({
+      name,
+      route: `/_ws/bulk/${c.cartridge}/${name.toLowerCase()}`,
+      searchFields: [] as string[],
+    }));
+    if (entities.length > 0) reg[c.cartridge] = entities;
+  }
+  return reg;
+}
+
+// Renders the entity graph. Must be mounted inside a <BulkStreamProvider> — it
+// reads live row counts off that shared socket's SCHEMA preload rather than
+// opening its own connection (the Data tab already provides one).
+export const DiagramView: React.FC<{
+  visibleIds: Set<string>;
+  onSelectNode?: (cart: string, entity: string) => void;
+}> = ({ visibleIds, onSelectNode }) => {
+  const { contracts, loading, error } = useContracts();
+
+  const graph = React.useMemo(
+    () => buildEntityGraphModel(cartsFromContracts(contracts)),
+    [contracts],
+  );
+  const registry = React.useMemo(() => registryFromContracts(contracts), [contracts]);
+
+  if (graph.nodes.length === 0) {
+    let msg = "No installed cartridges with entities.";
+    if (loading) msg = "Loading entity graph…";
+    else if (error) msg = `Failed to load contracts: ${error}`;
+    return <div className="p-3 text-[12px] text-muted-foreground">{msg}</div>;
+  }
+
+  return (
+    <DiagramInner
+      graph={graph}
+      registry={registry}
+      visibleIds={visibleIds}
+      onSelectNode={onSelectNode}
+    />
+  );
+};
+
+const DiagramInner: React.FC<{
+  graph: EntityGraphModel;
+  registry: BulkRegistry;
+  visibleIds: Set<string>;
+  onSelectNode?: (cart: string, entity: string) => void;
+}> = ({ graph, registry, visibleIds, onSelectNode }) => {
+  const rowCounts = useBulkRowCounts(registry);
+  const [focusedNodeId, setFocusedNodeId] = React.useState<string | null>(null);
+
+  const visibleGraph = React.useMemo(
+    () => filterEntityGraphModel(graph, visibleIds),
+    [graph, visibleIds],
+  );
+
+  React.useEffect(() => {
+    if (focusedNodeId && !visibleIds.has(focusedNodeId)) setFocusedNodeId(null);
+  }, [focusedNodeId, visibleIds]);
+
+  const focusedConnections = React.useMemo(() => {
+    if (!focusedNodeId) {
+      return {
+        connectedIds: new Set<string>(),
+        edgeIds: new Set<string>(),
+        fieldsByNode: new Map<string, Set<string>>(),
+      };
+    }
+    const connectedIds = new Set<string>([focusedNodeId]);
+    const edgeIds = new Set<string>();
+    const fieldsByNode = new Map<string, Set<string>>();
+    const addField = (nodeId: string, fieldName: string) => {
+      const fields = fieldsByNode.get(nodeId) ?? new Set<string>();
+      fields.add(fieldName);
+      fieldsByNode.set(nodeId, fields);
+    };
+    for (const edge of visibleGraph.edges) {
+      if (edge.source !== focusedNodeId && edge.target !== focusedNodeId) continue;
+      edgeIds.add(edge.id);
+      connectedIds.add(edge.source);
+      connectedIds.add(edge.target);
+      addField(edge.source, edge.sourceField);
+      addField(edge.target, edge.targetField);
+    }
+    return { connectedIds, edgeIds, fieldsByNode };
+  }, [focusedNodeId, visibleGraph.edges]);
+
+  const nodes: Node[] = React.useMemo(
+    () =>
+      visibleGraph.nodes.map((node) => ({
+        id: node.id,
+        type: "entity",
+        position: node.position,
+        data: {
+          ...node,
+          rowCount: rowCounts[node.id] ?? node.rowCount,
+          highlight: focusedNodeId
+            ? {
+                focused: node.id === focusedNodeId,
+                connected: focusedConnections.connectedIds.has(node.id) && node.id !== focusedNodeId,
+                dimmed: !focusedConnections.connectedIds.has(node.id),
+                fields: [...(focusedConnections.fieldsByNode.get(node.id) ?? [])],
+              }
+            : undefined,
+        },
+      })),
+    [focusedConnections, focusedNodeId, visibleGraph.nodes, rowCounts],
+  );
+
+  const edges: EntityFlowEdge[] = React.useMemo(() => {
+    const nodeById = new Map(visibleGraph.nodes.map((node) => [node.id, node]));
+    const laneCounts = new Map<string, number>();
+    return visibleGraph.edges.map((edge) => {
+      const source = nodeById.get(edge.source);
+      const target = nodeById.get(edge.target);
+      const sourceSide = source && target && source.position.x > target.position.x ? "left" : "right";
+      const targetSide = sourceSide === "left" ? "right" : "left";
+      const laneKey = `${edge.target}:${edge.targetField}:${targetSide}`;
+      const lane = laneCounts.get(laneKey) ?? 0;
+      laneCounts.set(laneKey, lane + 1);
+      const highlighted = !focusedNodeId || focusedConnections.edgeIds.has(edge.id);
+      return {
+        id: edge.id,
+        source: edge.source,
+        target: edge.target,
+        sourceHandle: `source-${edge.sourceField}-${sourceSide}`,
+        targetHandle: `target-${edge.targetField}-${targetSide}`,
+        type: "smoothstep",
+        pathOptions: { borderRadius: 8, offset: 22 + (lane % 5) * 12 },
+        markerEnd: {
+          type: MarkerType.ArrowClosed,
+          color: highlighted ? "#2563eb" : "#64748b",
+        },
+        style: {
+          strokeWidth: focusedNodeId && highlighted ? 2.5 : 1.5,
+          stroke: highlighted ? "#2563eb" : "#64748b",
+          opacity: highlighted ? 1 : 0.16,
+        },
+      };
+    });
+  }, [focusedConnections.edgeIds, focusedNodeId, visibleGraph.edges, visibleGraph.nodes]);
+
+  const onNodeClick = React.useCallback(
+    (_: unknown, node: Node) => {
+      const data = node.data as EntityGraphNodeData;
+      const nodeId = entityGraphId(data.cartridge, data.entity);
+      setFocusedNodeId((prev) => (prev === nodeId ? null : nodeId));
+      onSelectNode?.(data.cartridge, data.entity);
+    },
+    [onSelectNode],
+  );
+
+  // Right-click surfaces the same data panel (and suppresses the browser menu)
+  // rather than toggling focus off; selecting also focuses the node.
+  const onNodeContextMenu = React.useCallback(
+    (e: React.MouseEvent, node: Node) => {
+      e.preventDefault();
+      const data = node.data as EntityGraphNodeData;
+      setFocusedNodeId(entityGraphId(data.cartridge, data.entity));
+      onSelectNode?.(data.cartridge, data.entity);
+    },
+    [onSelectNode],
+  );
+
+  const clearFocusedNode = React.useCallback(() => setFocusedNodeId(null), []);
+
+  return (
+    <div className="flex h-full min-h-0 w-full flex-col">
+      <div className="relative min-h-0 flex-1 bg-zinc-950">
+        {nodes.length === 0 ? (
+          <div className="flex h-full items-center justify-center text-[12px] text-zinc-500">
+            No entities are visible.
+          </div>
+        ) : (
+          <ReactFlowProvider>
+            <ReactFlow
+              colorMode="dark"
+              nodes={nodes}
+              edges={edges}
+              nodeTypes={nodeTypes}
+              fitView
+              fitViewOptions={{ padding: 0.2 }}
+              minZoom={0.1}
+              maxZoom={1.6}
+              nodesDraggable={false}
+              nodesConnectable={false}
+              elementsSelectable
+              panOnDrag
+              zoomOnScroll
+              zoomOnPinch
+              selectionOnDrag={false}
+              onNodeClick={onNodeClick}
+              onNodeContextMenu={onNodeContextMenu}
+              onPaneClick={clearFocusedNode}
+              proOptions={{ hideAttribution: true }}
+            >
+              <FitOnReady fitKey={[...visibleIds].sort().join("|")} />
+              <Background variant={BackgroundVariant.Dots} gap={16} size={1} color="#3f3f46" />
+              <Controls showInteractive={false} />
+            </ReactFlow>
+          </ReactFlowProvider>
+        )}
+      </div>
+    </div>
+  );
+};