spyret 0.1.1 → 0.2.0

package/README.md

@@ -1,37 +1,89 @@
 # Spyret
 
-The interfaces between standard Pyret and Spytial. Spyret captures Pyret values
-as portable relational data, reconstructs their structure, and emits Pyret source
-where supported. It runs in Node or a browser without an IDE.
+[![Build and tests](https://github.com/sidprasad/spyret/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/sidprasad/spyret/actions/workflows/test.yml)
+[![npm version](https://img.shields.io/npm/v/spyret)](https://www.npmjs.com/package/spyret)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-`spyret-ide` is one consumer. `spytial-core` owns generic graph data, queries,
-layout and rendering. This package owns Pyret runtime adaptation, constructor
-identity, exact numbers, collections, capture validation, reconstruction and the
-tests of those contracts.
+Spyret connects [Pyret](https://pyret.org/) values to
+[Spytial](https://github.com/sidprasad/spytial-core) diagrams.
+`toDataInstance(value, runtime)` turns a Pyret value into relational data for
+Spytial; `await getSpytialSpec(value, runtime)` walks its reachable values and
+collects one YAML string per distinct `_spytial` hook. Hooks can return typed
+Pyret rules or raw YAML; values without hooks return `[]`. The JavaScript API
+runs without an IDE, and the browser library lets Pyret programs display diagrams
+in CPO through an import.
+
+## JavaScript
+
+```sh
+npm install spyret
+```
 
 ```js
-import { toDataInstance } from 'spyret';
+import { toDataInstance, getSpytialSpec } from 'spyret';
 
+// Use the Pyret runtime that owns the value, while it is idle or paused.
 const instance = toDataInstance(pyretValue, runtime);
-// Pass instance directly to Spytial-Core's evaluator/layout APIs.
+const specs = await getSpytialSpec(pyretValue, runtime); // string[]
+// Pass the data and layout specs to Spytial-Core.
 ```
 
-`toDataInstance` accepts a value and the standard Pyret runtime that owns it.
-Spyret handles capture, relationalization and validation and returns an
-`IDataInstance`. Core handles queries, layout and rendering. No
-`spytial-core/data` entry point or Core runtime is needed inside Spyret.
+`toDataInstance` returns an `IDataInstance` and never invokes hooks. The collector
+handles cycles and calls each distinct hook once. See the
+[hook contract and typed rules](docs/SPYTIAL_HOOKS.md) for composition, errors and
+runtime requirements. For portable snapshots and reconstruction, see the
+[capture API](docs/PYRET_CAPTURE.md).
+
+## Pyret: import, describe, display
+
+A maintainer runs `npm run release:drive` and follows the
+[manual upload instructions](docs/RELEASING.md). Users then import the versioned
+wrapper in CPO to get typed rule constructors and diagram functions together:
+
+```pyret
+# Use the import line supplied by the library maintainer.
+import shared-gdrive("spyret-vVERSION.arr", "WRAPPER_DRIVE_FILE_ID") as S
+
+data Tree:
+  | leaf(value)
+  | branch(left, right)
+sharing:
+  method _spytial(self):
+    [list: S.orientation("left + right", [list: S.direction-below])]
+  end
+end
+
+S.diagram(branch(leaf(1), leaf(2)))
+```
+
+`diagram` collects the reachable types' rules, relationalizes the value and displays
+a diagram. Compose rules with ordinary Pyret lists; constructors such as
+`orientation`, `align` and `group` handle their constraint/directive category.
+`S.diagram([list: 1, 2, 3])` also works without any hooks. To supply rules explicitly,
+use `S.diagram-with-rules(value, rules)`, or `S.diagram(value, yaml)` for YAML.
+See the [rule reference](docs/SPYTIAL_RULES_REFERENCE.md) for available constructors.
+
+The import form depends on the host and file:
+
+| Import | What it loads |
+| --- | --- |
+| `shared-gdrive("spyret-vVERSION.arr", "WRAPPER_DRIVE_FILE_ID")` | The versioned release wrapper in CPO: typed rules and diagram functions in one import. |
+| `url("https://raw.githubusercontent.com/…/spyret-vVERSION.arr")` | A GitHub-hosted Pyret wrapper: typed rules and diagram functions in one import. It imports the native module from Drive internally. |
+| `gdrive-js("spyret-vVERSION.js", "NATIVE_DRIVE_FILE_ID")` | The versioned native JavaScript module in CPO, providing diagram functions. |
+| `js-file("path/to/spyret")` | The same native module in a browser host with a filesystem bridge. |
 
-For transport between processes, use `capturePyret` with
-`createPyretRuntimeAdapter(runtime)`, then `importPyretCapture` at the receiver.
-The receiver needs neither Pyret nor an IDE. Collecting layout YAML alongside
-values can be added to Spyret later; YAML interpretation stays in Core.
+A plain `url(...)` import cannot load native JavaScript. The packaged renderer
+supports CPO; other browser hosts need an adapter. No changes to CPO itself are
+required, although the library uses private CPO display APIs. See the
+[hosting and import guide](docs/BROWSER_LIBRARY.md) for details about published imports.
 
-See [the capture contract](docs/PYRET_CAPTURE.md) for supported values and limits.
-Closures are not serialized. Source preview is separate from structural capture.
+Spyret owns Pyret adaptation and display integration; Core owns layout semantics
+and graph rendering. Spyret-IDE can consume this library through a small wrapper;
+its migration is a [separate companion change](docs/IDE_MIGRATION.md).
 
 ## Development
 
-Requires Node 22 or later. The development dependency on released Core 6.3.1
+Requires Node 22 or later. The development dependency on released Core 6.3.2
 provides its public interface types and tests layout/query compatibility.
 Published Spyret builds include those type declarations and have no Core runtime
 dependency.
@@ -49,6 +101,7 @@ directory with `npm ci --ignore-scripts && make phaseA`, then run:
 ```sh
 npm run test:upstream -- /path/to/pyret-lang/lang
 npm run test:program -- /path/to/pyret-lang/lang
+npm run test:spytial -- /path/to/pyret-lang/lang
 REIFY_SEED=1 npm run test:pbt -- /path/to/pyret-lang/lang
 REIFY_SEED=2 npm run test:pbt -- /path/to/pyret-lang/lang
 ```
@@ -66,10 +119,13 @@ CommonJS and ES modules import `spyret`. The browser bundle is
 ## npm releases
 
 Published builds contain Spyret's adapter and bundled interface declarations.
-Hosts can use Core 6.3.1 for layout and rendering; Core 6.3.2 is not required.
+The standalone browser module loads Core 6.3.2; headless consumers do not need
+a Core runtime.
 `npm run test:package` verifies the actual tarball in an isolated consumer.
 Version tags trigger the unit/package suite and both upstream PBT seeds before
-publishing. See [release setup and commands](docs/RELEASING.md).
+publishing to npm and GitHub. To prepare the latest release for Google Drive,
+run `npm run release:drive` and follow the upload prompts.
+See [manual release instructions](docs/RELEASING.md).
 
 ## Migration and provenance
 

package/THIRD_PARTY_NOTICES.txt

@@ -2,7 +2,7 @@ Spyret's adapter helpers and data contracts originate in Spytial-Core.
 Author: Siddhartha Prasad
 License: MIT (declared by the source package)
 Source: https://github.com/sidprasad/spytial-core
-Contracts verified against spytial-core 6.3.1.
+Contracts verified against spytial-core 6.3.2.
 No Core runtime or renderer is included.
 
 ---
@@ -82,3 +82,30 @@ maintained libraries used by this software which have their own
 licenses; we recommend you read them, as their terms may differ from the
 terms above.
 
+
+---
+
+js-yaml
+
+(The MIT License)
+
+Copyright (C) 2011-2015 by Vitaly Puzrin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+