spyret 0.1.0 → 0.2.0

package/docs/IDE_MIGRATION.md

@@ -0,0 +1,38 @@
+# Spyret library and IDE ownership
+
+Spyret now supplies the reusable browser integration. A Drive-imported native
+module can install its own CPO display adapter; the IDE does **not** need a
+Spytial-specific output branch. See [library setup](BROWSER_LIBRARY.md).
+
+| Functionality | Owner |
+| --- | --- |
+| Value capture, relationalization, reconstruction, `_spytial` collection | Spyret |
+| Generated Pyret rule types, YAML section composition | Spyret |
+| Pyret-facing diagram functions and runtime suspension/Stop handling | Spyret |
+| Evaluator/layout setup, opaque handles, source preview and views | Spyret browser entry |
+| CPO renderer compatibility code | Spyret, isolated in `registerCpoOutput` |
+| Layout semantics, parsing, solving, graph controls and diagnostics | Core |
+| Source selection, YAML source writeback, undo and keyboard shortcuts | IDE |
+| Builtin aliases and package/asset delivery for existing programs | IDE build configuration |
+
+In the separate companion IDE change, the `spytial` builtin becomes a small
+forwarding wrapper around
+`spyret/browser`. `spytial-rules` is a build-time copy of the generated Pyret
+module. Its old `spytial-view` module and Spytial branch in `output-ui` are removed.
+Existing `SP.diagram(value, yaml)` and `_output` methods continue to work; new
+programs can use `SP.diagram(value)` and typed rules.
+
+Stock CPO can instead load `spyret/pyret-module` through its existing `gdrive-js`
+locator, optionally hidden behind one URL-imported `.arr` wrapper. No new native
+URL locator or IDE plugin is required for that route. Drive hosting/access is a
+separate deployment step.
+
+The companion IDE change consumes a lockfile-verified vendored Spyret 0.2.0 package
+archive, so this coordinated change builds without an unpublished registry
+version or a sibling source checkout. Once 0.2.0 is published, replace that
+archive dependency with the exact npm version and regenerate the copied assets;
+no runtime code needs to change.
+
+Future work should focus on an upstream public display-registration and
+cancellation API, deployment/Drive-access testing, and optional source-editor
+integration. The existing private CPO adapter remains a compatibility dependency.

package/docs/PYRET_CAPTURE.md

@@ -62,8 +62,10 @@ inspect its nominal token/display spelling.
 
 No printer or arbitrary annotation runs during capture. Declared datatype methods
 are behavior supplied by declarations and are outside the declared-slot state
-contract; this includes `_output`. Non-method extension fields on data values
-are rejected instead of dropped. Functions/methods in state-bearing slots,
+contract; this includes `_output`. Callable `_spytial` metadata is also omitted
+on ordinary objects and outside a datatype's declared slots; collecting layout
+rules is a separate, explicit operation. Other non-method extension fields on
+data values are rejected instead of dropped. Functions/methods in state-bearing slots,
 opaque values, unrecognized branded library objects, standalone table Row
 values, sparse arrays, unset/frozen references, and arbitrary reference
 annotations produce explicit diagnostics. This API does not serialize closures

package/docs/RELEASING.md

@@ -1,69 +1,26 @@
-# Releasing Spyret
+# Releasing Spyret to Google Drive
 
-Spyret is published as the public npm package `spyret`. The CJS, ESM, browser and
-TypeScript entry points contain Spyret's adapters and bundled data contract
-declarations, with no Core runtime dependency. The host passes the returned
-`IDataInstance` to Core for layout/rendering; compatibility tests use Core 6.3.1.
-
-## One-time npm setup
-
-The first package publication requires an npm maintainer login. From a checked,
-merged release commit, run:
-
-```sh
-npm login
-npm install --global npm@11.20.0
-npm ci
-npm run typecheck
-npm test
-npm run test:package -- --out release
-npm publish ./release/spyret-0.1.0.tgz --access public
-```
-
-Also require green upstream PBT CI for this commit before publishing. The package
-check installs the actual tarball into an empty project and exercises
-CJS, ESM, browser and TypeScript consumers.
-
-After the package exists, configure its npm **Trusted Publisher** settings:
-
-| Setting | Value |
-| --- | --- |
-| Provider | GitHub Actions |
-| Organization/user | `sidprasad` |
-| Repository | `spyret` |
-| Workflow filename | `release.yml` |
-| Environment | Leave empty |
-| Allowed action | Enable direct `npm publish` |
-
-With npm 11.15 or later, the equivalent command is:
+With Node 22+, [GitHub CLI](https://cli.github.com/), and `tar` installed, run
+from this checkout (no `npm install` or build needed):
 
 ```sh
-npm trust github spyret --repo sidprasad/spyret --file release.yml --allow-publish
+npm run release:drive
 ```
 
-See [npm's trusted publishing documentation](https://docs.npmjs.com/trusted-publishers/).
-No npm token needs to be stored in GitHub. Publishing uses OIDC and provenance.
-
-## Later releases
-
-1. On a release branch, run `npm version patch --no-git-tag-version` (or choose a
-   minor/major bump), commit both manifests, and merge after CI passes.
-2. On the updated `main`, tag that exact commit and push the tag:
-
-   ```sh
-   git tag v0.1.1
-   git push origin v0.1.1
-   ```
+The script downloads the latest GitHub release and walks you through:
 
-3. `release.yml` verifies the tag matches `package.json` and belongs to `main`,
-   runs the unit/package suite and both standard-Pyret PBT seeds, tests the packed
-   artifact, publishes it to npm, and attaches it to a GitHub release.
+1. Upload the prepared `.js` file to your Google Drive. Set **Anyone with the
+   link / Viewer**, then paste its Drive link into the script.
+2. Upload the generated `.arr` file with the same sharing setting and paste
+   its Drive link into the script.
+3. Copy the printed import into CPO and run the provided diagram example.
+   Share that import line with users: it includes typed constructors and diagrams.
 
-Prerelease versions publish under `next`; stable versions use `latest`. A failed
-workflow can be rerun or manually dispatched against the same **tag**. An existing
-npm version is accepted only when its integrity matches the tested tarball;
-different contents require a version bump.
+Keep both filenames unchanged and upload them as files without conversion.
+The two upload files are in `release/vVERSION/upload/`; the CPO example is
+saved separately as `release/vVERSION/import.arr`. Keep published Drive files
+unchanged so existing imports continue to work.
 
-For the manually bootstrapped 0.1.0 release, push `v0.1.0` after configuring
-trusted publishing. The workflow verifies that identical package and creates
-the corresponding GitHub release.
+To select a specific release, use `npm run release:drive -- --tag v0.2.0`.
+The release must contain the browser module and Pyret rules; `v0.1.1` is headless
+and cannot be used. No Google Cloud project, service account, or API setup is needed.

package/docs/SPYTIAL_HOOKS.md

@@ -0,0 +1,73 @@
+# Layout hooks and typed rules
+
+The package includes `pyret/spytial.arr`, a typed rule library generated from
+Core's language manifest. Copy or serve that file where your Pyret program can
+import it (Node hosts can locate it with `require.resolve('spyret/spytial.arr')`).
+
+```pyret
+import file("spytial.arr") as S
+
+data Tree:
+  | leaf(value)
+  | branch(children)
+sharing:
+  method _spytial(self) -> List<S.SpytialRule>:
+    [list:
+      S.orientation("children", [list: S.direction-below]),
+      S.align("siblings", S.alignment-horizontal)
+    ]
+  end
+end
+```
+
+Public constructors wrap their results as `constraint(Constraint)` or
+`directive(Directive)` automatically. Compose rules with ordinary Pyret lists;
+the serializer puts each rule in its proper YAML section. Optional fields and
+style blocks have typed, immutable setters:
+
+```pyret
+S.atom-style-with(S.default-atom-style-options
+  .with-selector("leaf")
+  .with-fill-style(S.default-fill-style.with-color("red")))
+```
+
+From the JavaScript host, after evaluating the program:
+
+```js
+import { toDataInstance, getSpytialSpec } from 'spyret';
+
+const instance = toDataInstance(pyretValue, runtime);
+const specs = await getSpytialSpec(pyretValue, runtime); // string[]
+```
+
+The collector walks reachable values in breadth-first order, including lists,
+objects, tuples, arrays, references, dictionaries and table cells. It handles
+cycles and invokes each distinct `_spytial` function or method once per call,
+with methods bound to their first encountered owner. Repeated hooks never stop
+the traversal of an instance's children. Hooks should describe types, independent
+of the particular instance; unobserved datatype variants cannot be discovered.
+
+Each hook returns `List<SpytialRule>`, serialized as one YAML document. A raw YAML
+string is also accepted as an escape hatch, unchanged and unvalidated. No hooks
+yields `[]`; a hook returning an empty list yields one empty spec. Identical
+documents from different hooks remain separate. Hook failures, malformed rules
+and unsupported values reject the promise with a `SpytialSpecError` and path.
+
+Hooks execute user code. Call the async collector while its owning runtime is
+idle or paused; a native Pyret module can use `runtime.pauseStack` around the
+promise. `spytialRulesToYaml(rules, runtime)` also serializes an already evaluated
+rule list directly. Capture and `toDataInstance` never invoke hooks, and omit
+callable `_spytial` metadata on ordinary objects or outside a datatype's declared
+slots. Other capture restrictions still apply.
+
+See the [generated rule reference](SPYTIAL_RULES_REFERENCE.md) for every
+constructor, enum and option. Pyret annotations check field types; serialization
+checks numeric bounds, string patterns and incompatible directions. Selector
+meaning and result arity remain Core's responsibility.
+
+To update the API, pin the desired Core release in `package.json` and the lockfile,
+then run `npm run generate:spytial`. Commit the generated Pyret source, serializer
+schema and reference together. `npm run check:spytial` and the tests detect drift;
+unknown field types or enum vocabularies fail generation for explicit handling.
+No Core runtime dependency is added to the published package.
+

package/docs/SPYTIAL_RULES_REFERENCE.md

@@ -0,0 +1,51 @@
+# Generated Pyret rule reference
+
+Core 6.3.2; language 2026-09-18.
+
+Import `pyret/spytial.arr` as `S`. Constructors return `S.SpytialRule` automatically.
+Optional fields use typed options. Start with `S.default-<rule>-options`,
+chain `.with-<field>(value)`, then pass it to `<rule>-with` after the required arguments.
+Style blocks similarly offer `default-<block>` and `.with-<field>(value)`.
+
+Numeric bounds, patterns and incompatible direction combinations are checked during serialization.
+
+| Constructor | Optional fields |
+| --- | --- |
+| `orientation(selector :: String, directions :: List<Direction>)` | `hold: Hold`, `source: RuleSource` |
+| `cyclic(selector :: String)` | `direction: Rotation`, `hold: Hold`, `source: RuleSource` |
+| `align(selector :: String, direction :: Alignment)` | `hold: Hold`, `source: RuleSource` |
+| `group(selector :: String, name :: String)` | `add-edge: GroupAddEdge`, `show-label: Boolean`, `text-style: TextStyle`, `hold: Hold`, `source: RuleSource` |
+| `size(width :: Number, height :: Number)` | `selector: String`, `source: RuleSource` |
+| `hide-atom(selector :: String)` | `source: RuleSource` |
+| `flag(name :: LayoutFlag)` |  |
+| `atom-style()` | `selector: String`, `fill-style: FillStyle`, `border-style: BorderStyle`, `icon-style: IconStyle`, `text-style: TextStyle`, `show-label: Boolean`, `source: RuleSource` |
+| `edge-style(field :: String)` | `selector: String`, `filter: String`, `line-style: LineStyle`, `text-style: TextStyle`, `show-label: Boolean`, `hidden: Boolean`, `source: RuleSource` |
+| `attribute(field :: String)` | `selector: String`, `filter: String`, `text-style: TextStyle`, `source: RuleSource` |
+| `tag(to-tag :: String, name :: String, value :: String)` | `text-style: TextStyle`, `source: RuleSource` |
+| `hide-field(field :: String)` | `selector: String`, `filter: String`, `source: RuleSource` |
+| `inferred-edge(name :: String, selector :: String)` | `draw: String`, `line-style: LineStyle`, `text-style: TextStyle`, `color: String`, `style: LinePattern`, `weight: Number`, `highlight: String`, `source: RuleSource` |
+| `icon(selector :: String, path :: String)` (deprecated; use atom-style) | `show-labels: Boolean`, `source: RuleSource` |
+| `atom-color(value :: String, selector :: String)` (deprecated; use atom-style) | `source: RuleSource` |
+| `edge-color(field :: String, value :: String)` (deprecated; use edge-style) | `selector: String`, `filter: String`, `style: LinePattern`, `weight: Number`, `highlight: String`, `show-label: Boolean`, `hidden: Boolean`, `source: RuleSource` |
+
+## Enum values
+
+- `TextSize`: `text-size-small`, `text-size-normal`, `text-size-large`
+- `LinePattern`: `line-pattern-solid`, `line-pattern-dashed`, `line-pattern-dotted`
+- `IconPlacement`: `icon-placement-full`, `icon-placement-badge`
+- `Direction`: `direction-above`, `direction-below`, `direction-left`, `direction-right`, `direction-directly-above`, `direction-directly-below`, `direction-directly-left`, `direction-directly-right`
+- `Hold`: `hold-always`, `hold-never`
+- `Rotation`: `rotation-clockwise`, `rotation-counterclockwise`
+- `Alignment`: `alignment-horizontal`, `alignment-vertical`
+- `GroupEdgeDirection`: `group-edge-direction-none`, `group-edge-direction-togroup`, `group-edge-direction-fromgroup`
+- `LayoutFlag`: `layout-flag-hide-disconnected`, `layout-flag-hide-disconnected-built-ins`
+
+## Blocks
+
+- `text-style(size: Option<TextSize>, color: Option<String>)`
+- `line-style(color: Option<String>, pattern: Option<LinePattern>, weight: Option<Number>, highlight: Option<String>)`
+- `fill-style(color: Option<String>)`
+- `border-style(color: Option<String>, width: Option<Number>)`
+- `icon-style(path: Option<String>, placement: Option<IconPlacement>, opacity: Option<Number>)`
+- `rule-source(text: String, location: Option<String>)`
+- `group-add-edge(points: Option<GroupEdgeDirection>, line-style: Option<LineStyle>, text-style: Option<TextStyle>)`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spyret",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Headless interfaces between standard Pyret and Spytial",
   "license": "MIT",
   "author": "Siddhartha Prasad",
@@ -14,7 +14,8 @@
   "files": [
     "dist",
     "docs",
-    "THIRD_PARTY_NOTICES.txt"
+    "THIRD_PARTY_NOTICES.txt",
+    "pyret"
   ],
   "exports": {
     ".": {
@@ -27,31 +28,51 @@
         "default": "./dist/spyret.js"
       }
     },
-    "./global": "./dist/spyret.global.js"
+    "./global": "./dist/spyret.global.js",
+    "./spytial.arr": "./pyret/spytial.arr",
+    "./browser": {
+      "import": {
+        "types": "./dist/spyret-browser.d.mts",
+        "default": "./dist/spyret-browser.mjs"
+      },
+      "require": {
+        "types": "./dist/spyret-browser.d.ts",
+        "default": "./dist/spyret-browser.js"
+      }
+    },
+    "./browser/amd": "./dist/spyret-browser.amd.js",
+    "./pyret-module": "./dist/spyret.pyret.js"
   },
   "scripts": {
-    "build": "tsup && node scripts/write-notices.mjs",
+    "build": "npm run check:spytial && tsup && node scripts/write-pyret-module.mjs && node scripts/write-notices.mjs",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:upstream": "node scripts/check-pyret-capture.mjs",
     "test:program": "node scripts/check-pyret-capture-program.mjs",
     "test:pbt": "node scripts/check-pyret-pbt.mjs",
     "prepack": "npm run typecheck && npm run build",
-    "test:package": "npm run build && node scripts/check-package.mjs"
+    "test:package": "npm run build && node scripts/check-package.mjs",
+    "generate:spytial": "node scripts/generate-spytial.mjs",
+    "check:spytial": "node scripts/generate-spytial.mjs --check",
+    "test:spytial": "node scripts/check-spytial-program.mjs",
+    "make:drive-wrapper": "node scripts/make-drive-wrapper.mjs",
+    "release:drive": "node scripts/prepare-drive-release.mjs"
   },
   "engines": {
     "node": ">=22"
   },
   "devDependencies": {
+    "@types/js-yaml": "4.0.9",
     "@types/node": "^24.0.3",
     "fast-check": "^4.6.0",
+    "graphlib": "^2.1.8",
+    "js-yaml": "4.1.0",
     "jsdom": "^26.1.0",
+    "spytial-core": "6.3.2",
     "tsup": "^8.5.0",
     "tsx": "^4.21.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4",
-    "spytial-core": "6.3.1",
-    "graphlib": "^2.1.8"
+    "vitest": "^3.2.4"
   },
   "publishConfig": {
     "access": "public",