spyret 0.1.0 → 0.2.0

package/dist/spyret-browser.d.mts

@@ -0,0 +1,272 @@
+import { Graph } from 'graphlib';
+
+interface IAtom {
+    id: string;
+    type: string;
+    label: string;
+    /**
+     * Optional key-value labels associated with this atom.
+     * Used for language-specific metadata that should be displayed prominently on nodes
+     * (e.g., Skolems in Alloy, annotations in other languages).
+     * These labels are styled differently from regular attributes - typically in the node's color.
+     */
+    labels?: Record<string, string[]>;
+}
+/**
+ * One tuple in a relation.
+ *
+ * A tuple owns its own arity: `atoms.length` is the truth, and `types` is
+ * this tuple's signature, one entry per atom. A relation may hold tuples of
+ * different arity (see {@link IRelation}), so nothing may read one tuple's
+ * arity as the arity of the relation around it.
+ */
+interface ITuple {
+    atoms: string[];
+    types: string[];
+}
+interface IType {
+    id: string;
+    types: string[];
+    atoms: IAtom[];
+    isBuiltin: boolean;
+}
+/**
+ * A named set of tuples.
+ *
+ * Relations are RAGGED-TOLERANT: the tuples need not all have the same arity.
+ * Host languages hand us this routinely — two unrelated Python classes can both
+ * have a `foo` field, one holding pairs and one holding triples, and both are
+ * the relation `foo`. Alloy reaches the same place from the other side: two
+ * sigs may each declare a field `foo`, and their ids differ (`A<:foo`,
+ * `B<:foo`) while the name does not.
+ *
+ * Records with distinct IDs stay distinct in storage. The name is what
+ * selectors see: a name denotes the set union of all matching records.
+ * IDs are preserved for host reconstruction and exact-ID mutation. Rendering, the
+ * evaluators and the constraint layer all work tuple by tuple, so a ragged
+ * relation draws and queries correctly.
+ */
+interface IRelation {
+    id: string;
+    name: string;
+    /**
+     * A SUMMARY of the tuples' column types, one entry per column, positional.
+     *
+     * It is only meaningful when every tuple has the same arity. When the tuples
+     * disagree — a ragged relation — no positional list can describe them, and
+     * this is `[]`.
+     *
+     * So `types.length` is NOT the relation's arity, and must never be read as
+     * one: on a ragged relation it is 0 no matter how wide the tuples are. Arity
+     * lives on the tuple (`ITuple.atoms.length`).
+     */
+    types: string[];
+    tuples: ITuple[];
+}
+interface IDataInstance {
+    getAtomType(id: string): IType;
+    getTypes(): readonly IType[];
+    getAtoms(): readonly IAtom[];
+    getRelations(): readonly IRelation[];
+    generateGraph(hideDisconnected: boolean, hideDisconnectedBuiltIns: boolean): Graph;
+}
+
+/** Spyret's data view of a validated capture, implementing Core's public contract. */
+declare class CapturedDataInstance implements IDataInstance {
+    private datum;
+    private atoms;
+    private types;
+    constructor(datum: {
+        atoms: IAtom[];
+        relations: IRelation[];
+        types: IType[];
+    });
+    getAtoms(): readonly IAtom[];
+    getRelations(): readonly IRelation[];
+    getTypes(): readonly IType[];
+    getAtomType(id: string): IType;
+    generateGraph(hideDisconnected?: boolean, hideDisconnectedBuiltIns?: boolean): Graph;
+}
+
+/** Internal lossless numbers. IDataInstance stores their literal in the atom label. */
+type PyretNumberPayload = {
+    version: 1;
+} & ({
+    kind: 'integer';
+    value: string;
+} | {
+    kind: 'rational';
+    numerator: string;
+    denominator: string;
+} | {
+    kind: 'roughnum';
+    value: string;
+});
+
+interface ConstructorInfo {
+    name: string;
+    arity: number;
+    fields: string[];
+    mutableFields?: number[];
+}
+
+/** The adapter returns observations, never serialized values or display output. */
+type PyretObservation = {
+    kind: 'primitive';
+    value: string | boolean | {
+        $pyretNumber: PyretNumberPayload;
+    };
+} | {
+    kind: 'nothing';
+} | {
+    kind: 'constructor';
+    identity: object;
+    info: ConstructorInfo;
+    values: unknown[];
+} | {
+    kind: 'object';
+    fields: Array<[string, unknown]>;
+} | {
+    kind: 'raw-array' | 'tuple';
+    values: unknown[];
+} | {
+    kind: 'reference';
+    value: unknown;
+} | {
+    kind: 'string-dict';
+    mutable: boolean;
+    sealed: boolean;
+    entries: Array<[string, unknown]>;
+} | {
+    kind: 'table';
+    headers: string[];
+    rows: unknown[][];
+};
+interface PyretRuntimeAdapter {
+    /** Throw for unsupported state; capture adds the selected root and path. */
+    observe(value: unknown): PyretObservation;
+}
+/** Predicates must come from the runtime that owns the value, not another realm. */
+interface PyretCaptureRuntime {
+    Any: unknown;
+    isNumber(value: unknown): boolean;
+    isNothing(value: unknown): boolean;
+    isDataValue(value: unknown): boolean;
+    isTuple(value: unknown): boolean;
+    isRef(value: unknown): boolean;
+    isFunction(value: unknown): boolean;
+    isMethod(value: unknown): boolean;
+    isOpaque(value: unknown): boolean;
+    isObject(value: unknown): boolean;
+}
+/**
+ * Adapter for upstream Pyret's JS runtime. All runtime representation reads are
+ * isolated here (including library backing stores). No printers, annotations,
+ * user functions, field dereferencing, or evaluator operations are invoked.
+ */
+declare function createPyretRuntimeAdapter(runtime: PyretCaptureRuntime): PyretRuntimeAdapter;
+
+type PyretCaptureJson = null | boolean | number | string | PyretCaptureJson[] | {
+    [key: string]: PyretCaptureJson;
+};
+interface PyretCaptureSnapshot {
+    format: 'spytial-pyret-capture';
+    version: 1;
+    datum: {
+        atoms: IAtom[];
+        relations: IRelation[];
+        types: IType[];
+    };
+    roots: Array<{
+        name: string;
+        atomId: string;
+        observation?: PyretCaptureJson;
+    }>;
+    provenance?: PyretCaptureJson;
+}
+
+/** The Pyret-specific part of diagramming. Rendering is supplied by the host. */
+declare function prepareDiagram(value: unknown, runtime: Parameters<typeof createPyretRuntimeAdapter>[0]): {
+    snapshot: PyretCaptureSnapshot;
+    instance: CapturedDataInstance;
+    sourcePreview: string;
+};
+
+/** The owning runtime, with its standard field, list and execution APIs. */
+interface SpytialRuntime extends PyretCaptureRuntime {
+    hasField(value: unknown, name: string): boolean;
+    getColonField(value: unknown, name: string): unknown;
+    getField(value: unknown, name: string): unknown;
+    num_to_fixnum(value: unknown): number;
+    ffi: {
+        isLink(value: unknown): boolean;
+        isEmpty(value: unknown): boolean;
+        isSome(value: unknown): boolean;
+        isNone(value: unknown): boolean;
+    };
+    safeCall(thunk: () => unknown, after: (value: unknown) => unknown, frame: string): unknown;
+    runThunk(thunk: () => unknown, done: (result: {
+        result?: unknown;
+        exn?: unknown;
+    }) => void): void;
+    isSuccessResult(result: unknown): boolean;
+}
+
+type Layout = {
+    nodes: {
+        mostSpecificType: string;
+    }[];
+};
+/** Only the Core operations used by the Pyret integration. Core is supplied separately. */
+interface BrowserCore {
+    parseLayoutSpec(yaml: string): any;
+    Evaluators: {
+        SGraphQueryEvaluator: new () => {
+            initialize(input: {
+                sourceData: IDataInstance;
+            }): unknown;
+        };
+    };
+    LayoutInstance: new (spec: any, evaluator: any, instance: number, align: boolean) => {
+        generateLayout(data: IDataInstance): {
+            layout: Layout;
+        };
+    };
+}
+interface DiagramRuntime extends SpytialRuntime {
+    ffi: SpytialRuntime['ffi'] & {
+        makeMessageException(message: string): unknown;
+        throwMessageException(message: string): never;
+    };
+    makeOpaque(value: unknown): unknown;
+    makeFunction(fn: (...args: any[]) => unknown, name?: string): unknown;
+    makeModuleReturn(values: Record<string, unknown>, types: Record<string, unknown>): unknown;
+    checkString(value: unknown): void;
+    pauseStack(callback: (restarter: {
+        resume(value: unknown): void;
+        error(error: unknown): void;
+        /** Standard Pyret PausePackage thread handlers; used to observe Stop. */
+        handlers?: {
+            break(): void;
+        };
+    }) => void): unknown;
+}
+interface BrowserHost {
+    core: () => BrowserCore | Promise<BrowserCore>;
+    document: Document;
+    registerOutput(runtime: DiagramRuntime, handle: object, render: () => HTMLElement): void;
+}
+/** Append sections in discovery order. Interpretation and conflicts belong to Core. */
+declare function combineSpytialSpecs(specs: readonly string[]): string;
+/** Construct a fresh view for every display of an opaque diagram value. */
+declare function createDiagramView(prepared: ReturnType<typeof prepareDiagram>, layout: Layout, document: Document): HTMLElement;
+/** All Pyret-facing behavior lives here; hosts supply Core and output registration. */
+declare function createPyretModule(runtime: DiagramRuntime, host: BrowserHost): unknown;
+/** Compatibility adapter for stock CPO. Private APIs are isolated to this function. */
+declare function registerCpoOutput(runtime: DiagramRuntime, handle: object, render: () => HTMLElement, jquery: (node: HTMLElement) => unknown): void;
+/** Load only when used. The IDE may already supply a compatible Core bundle. */
+declare function loadBrowserCore(document: Document, url: string): Promise<BrowserCore>;
+/** Used by the packaged native Pyret module (js-file or gdrive-js). */
+declare function createCpoModule(runtime: DiagramRuntime, document: Document, coreUrl: string): unknown;
+
+export { type BrowserCore, type BrowserHost, type DiagramRuntime, combineSpytialSpecs, createCpoModule, createDiagramView, createPyretModule, loadBrowserCore, registerCpoOutput };

package/dist/spyret-browser.d.ts

@@ -0,0 +1,272 @@
+import { Graph } from 'graphlib';
+
+interface IAtom {
+    id: string;
+    type: string;
+    label: string;
+    /**
+     * Optional key-value labels associated with this atom.
+     * Used for language-specific metadata that should be displayed prominently on nodes
+     * (e.g., Skolems in Alloy, annotations in other languages).
+     * These labels are styled differently from regular attributes - typically in the node's color.
+     */
+    labels?: Record<string, string[]>;
+}
+/**
+ * One tuple in a relation.
+ *
+ * A tuple owns its own arity: `atoms.length` is the truth, and `types` is
+ * this tuple's signature, one entry per atom. A relation may hold tuples of
+ * different arity (see {@link IRelation}), so nothing may read one tuple's
+ * arity as the arity of the relation around it.
+ */
+interface ITuple {
+    atoms: string[];
+    types: string[];
+}
+interface IType {
+    id: string;
+    types: string[];
+    atoms: IAtom[];
+    isBuiltin: boolean;
+}
+/**
+ * A named set of tuples.
+ *
+ * Relations are RAGGED-TOLERANT: the tuples need not all have the same arity.
+ * Host languages hand us this routinely — two unrelated Python classes can both
+ * have a `foo` field, one holding pairs and one holding triples, and both are
+ * the relation `foo`. Alloy reaches the same place from the other side: two
+ * sigs may each declare a field `foo`, and their ids differ (`A<:foo`,
+ * `B<:foo`) while the name does not.
+ *
+ * Records with distinct IDs stay distinct in storage. The name is what
+ * selectors see: a name denotes the set union of all matching records.
+ * IDs are preserved for host reconstruction and exact-ID mutation. Rendering, the
+ * evaluators and the constraint layer all work tuple by tuple, so a ragged
+ * relation draws and queries correctly.
+ */
+interface IRelation {
+    id: string;
+    name: string;
+    /**
+     * A SUMMARY of the tuples' column types, one entry per column, positional.
+     *
+     * It is only meaningful when every tuple has the same arity. When the tuples
+     * disagree — a ragged relation — no positional list can describe them, and
+     * this is `[]`.
+     *
+     * So `types.length` is NOT the relation's arity, and must never be read as
+     * one: on a ragged relation it is 0 no matter how wide the tuples are. Arity
+     * lives on the tuple (`ITuple.atoms.length`).
+     */
+    types: string[];
+    tuples: ITuple[];
+}
+interface IDataInstance {
+    getAtomType(id: string): IType;
+    getTypes(): readonly IType[];
+    getAtoms(): readonly IAtom[];
+    getRelations(): readonly IRelation[];
+    generateGraph(hideDisconnected: boolean, hideDisconnectedBuiltIns: boolean): Graph;
+}
+
+/** Spyret's data view of a validated capture, implementing Core's public contract. */
+declare class CapturedDataInstance implements IDataInstance {
+    private datum;
+    private atoms;
+    private types;
+    constructor(datum: {
+        atoms: IAtom[];
+        relations: IRelation[];
+        types: IType[];
+    });
+    getAtoms(): readonly IAtom[];
+    getRelations(): readonly IRelation[];
+    getTypes(): readonly IType[];
+    getAtomType(id: string): IType;
+    generateGraph(hideDisconnected?: boolean, hideDisconnectedBuiltIns?: boolean): Graph;
+}
+
+/** Internal lossless numbers. IDataInstance stores their literal in the atom label. */
+type PyretNumberPayload = {
+    version: 1;
+} & ({
+    kind: 'integer';
+    value: string;
+} | {
+    kind: 'rational';
+    numerator: string;
+    denominator: string;
+} | {
+    kind: 'roughnum';
+    value: string;
+});
+
+interface ConstructorInfo {
+    name: string;
+    arity: number;
+    fields: string[];
+    mutableFields?: number[];
+}
+
+/** The adapter returns observations, never serialized values or display output. */
+type PyretObservation = {
+    kind: 'primitive';
+    value: string | boolean | {
+        $pyretNumber: PyretNumberPayload;
+    };
+} | {
+    kind: 'nothing';
+} | {
+    kind: 'constructor';
+    identity: object;
+    info: ConstructorInfo;
+    values: unknown[];
+} | {
+    kind: 'object';
+    fields: Array<[string, unknown]>;
+} | {
+    kind: 'raw-array' | 'tuple';
+    values: unknown[];
+} | {
+    kind: 'reference';
+    value: unknown;
+} | {
+    kind: 'string-dict';
+    mutable: boolean;
+    sealed: boolean;
+    entries: Array<[string, unknown]>;
+} | {
+    kind: 'table';
+    headers: string[];
+    rows: unknown[][];
+};
+interface PyretRuntimeAdapter {
+    /** Throw for unsupported state; capture adds the selected root and path. */
+    observe(value: unknown): PyretObservation;
+}
+/** Predicates must come from the runtime that owns the value, not another realm. */
+interface PyretCaptureRuntime {
+    Any: unknown;
+    isNumber(value: unknown): boolean;
+    isNothing(value: unknown): boolean;
+    isDataValue(value: unknown): boolean;
+    isTuple(value: unknown): boolean;
+    isRef(value: unknown): boolean;
+    isFunction(value: unknown): boolean;
+    isMethod(value: unknown): boolean;
+    isOpaque(value: unknown): boolean;
+    isObject(value: unknown): boolean;
+}
+/**
+ * Adapter for upstream Pyret's JS runtime. All runtime representation reads are
+ * isolated here (including library backing stores). No printers, annotations,
+ * user functions, field dereferencing, or evaluator operations are invoked.
+ */
+declare function createPyretRuntimeAdapter(runtime: PyretCaptureRuntime): PyretRuntimeAdapter;
+
+type PyretCaptureJson = null | boolean | number | string | PyretCaptureJson[] | {
+    [key: string]: PyretCaptureJson;
+};
+interface PyretCaptureSnapshot {
+    format: 'spytial-pyret-capture';
+    version: 1;
+    datum: {
+        atoms: IAtom[];
+        relations: IRelation[];
+        types: IType[];
+    };
+    roots: Array<{
+        name: string;
+        atomId: string;
+        observation?: PyretCaptureJson;
+    }>;
+    provenance?: PyretCaptureJson;
+}
+
+/** The Pyret-specific part of diagramming. Rendering is supplied by the host. */
+declare function prepareDiagram(value: unknown, runtime: Parameters<typeof createPyretRuntimeAdapter>[0]): {
+    snapshot: PyretCaptureSnapshot;
+    instance: CapturedDataInstance;
+    sourcePreview: string;
+};
+
+/** The owning runtime, with its standard field, list and execution APIs. */
+interface SpytialRuntime extends PyretCaptureRuntime {
+    hasField(value: unknown, name: string): boolean;
+    getColonField(value: unknown, name: string): unknown;
+    getField(value: unknown, name: string): unknown;
+    num_to_fixnum(value: unknown): number;
+    ffi: {
+        isLink(value: unknown): boolean;
+        isEmpty(value: unknown): boolean;
+        isSome(value: unknown): boolean;
+        isNone(value: unknown): boolean;
+    };
+    safeCall(thunk: () => unknown, after: (value: unknown) => unknown, frame: string): unknown;
+    runThunk(thunk: () => unknown, done: (result: {
+        result?: unknown;
+        exn?: unknown;
+    }) => void): void;
+    isSuccessResult(result: unknown): boolean;
+}
+
+type Layout = {
+    nodes: {
+        mostSpecificType: string;
+    }[];
+};
+/** Only the Core operations used by the Pyret integration. Core is supplied separately. */
+interface BrowserCore {
+    parseLayoutSpec(yaml: string): any;
+    Evaluators: {
+        SGraphQueryEvaluator: new () => {
+            initialize(input: {
+                sourceData: IDataInstance;
+            }): unknown;
+        };
+    };
+    LayoutInstance: new (spec: any, evaluator: any, instance: number, align: boolean) => {
+        generateLayout(data: IDataInstance): {
+            layout: Layout;
+        };
+    };
+}
+interface DiagramRuntime extends SpytialRuntime {
+    ffi: SpytialRuntime['ffi'] & {
+        makeMessageException(message: string): unknown;
+        throwMessageException(message: string): never;
+    };
+    makeOpaque(value: unknown): unknown;
+    makeFunction(fn: (...args: any[]) => unknown, name?: string): unknown;
+    makeModuleReturn(values: Record<string, unknown>, types: Record<string, unknown>): unknown;
+    checkString(value: unknown): void;
+    pauseStack(callback: (restarter: {
+        resume(value: unknown): void;
+        error(error: unknown): void;
+        /** Standard Pyret PausePackage thread handlers; used to observe Stop. */
+        handlers?: {
+            break(): void;
+        };
+    }) => void): unknown;
+}
+interface BrowserHost {
+    core: () => BrowserCore | Promise<BrowserCore>;
+    document: Document;
+    registerOutput(runtime: DiagramRuntime, handle: object, render: () => HTMLElement): void;
+}
+/** Append sections in discovery order. Interpretation and conflicts belong to Core. */
+declare function combineSpytialSpecs(specs: readonly string[]): string;
+/** Construct a fresh view for every display of an opaque diagram value. */
+declare function createDiagramView(prepared: ReturnType<typeof prepareDiagram>, layout: Layout, document: Document): HTMLElement;
+/** All Pyret-facing behavior lives here; hosts supply Core and output registration. */
+declare function createPyretModule(runtime: DiagramRuntime, host: BrowserHost): unknown;
+/** Compatibility adapter for stock CPO. Private APIs are isolated to this function. */
+declare function registerCpoOutput(runtime: DiagramRuntime, handle: object, render: () => HTMLElement, jquery: (node: HTMLElement) => unknown): void;
+/** Load only when used. The IDE may already supply a compatible Core bundle. */
+declare function loadBrowserCore(document: Document, url: string): Promise<BrowserCore>;
+/** Used by the packaged native Pyret module (js-file or gdrive-js). */
+declare function createCpoModule(runtime: DiagramRuntime, document: Document, coreUrl: string): unknown;
+
+export { type BrowserCore, type BrowserHost, type DiagramRuntime, combineSpytialSpecs, createCpoModule, createDiagramView, createPyretModule, loadBrowserCore, registerCpoOutput };