spyret 0.2.0 → 0.3.0

package/docs/BROWSER_LIBRARY.md

@@ -8,7 +8,10 @@ integration is a separate `spyret/browser` entry.
 ## Import a published version in CPO
 
 A maintainer runs `npm run release:drive` and follows the
-[manual upload instructions](RELEASING.md). Use the import line they supply:
+[CPO-save and Drive publishing instructions](RELEASING.md). The native JavaScript
+requires CPO per-file authorization; public sharing alone is insufficient.
+Verify the import with a second account using normal login before distributing it.
+Use the import line the maintainer supplies:
 
 ```pyret
 import shared-gdrive("spyret-vVERSION.arr", "WRAPPER_DRIVE_FILE_ID") as S
@@ -22,9 +25,11 @@ only one import for typed constructors and diagram functions.
 
 ## An ordinary native import in CPO
 
-CPO already supports native Pyret modules through `gdrive-js`. Upload the built
-`dist/spyret.pyret.js` to Google Drive **as `spyret.js`**, and grant intended users
-read access. Do not convert it to a Google document. With that file's ID:
+CPO supports native Pyret modules through `gdrive-js`. Save the complete contents
+of `dist/spyret.pyret.js` through a new CPO editor document **as `spyret.js`**,
+without running it, following [the release workflow](RELEASING.md). Grant intended
+users read access in Drive; their CPO per-file authorization must also be checked.
+Do not convert the file to a Google document. With the saved file's ID:
 
 ```pyret
 import gdrive-js("spyret.js", "YOUR_DRIVE_FILE_ID") as Spyret

package/docs/RELEASING.md

@@ -9,18 +9,57 @@ npm run release:drive
 
 The script downloads the latest GitHub release and walks you through:
 
-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.
+1. Open a new [CPO editor](https://code.pyret.org/editor) with normal Google login.
+   Replace **all** editor text (including the initial `use context` line) with the
+   contents of the prepared `.js` file. Name it `spyret-vVERSION.js`, **Save**, and
+   wait for saving to finish. **Do not Run** this document: it contains JavaScript.
+   In Google Drive, set the saved file to **Anyone with the link / Viewer** and
+   keep it under **My Drive**. Paste its CPO editor URL (`#program=...`), Drive
+   link, or file ID into the script. Use the saved file, not a CPO Share copy.
+2. Upload the generated `.arr` wrapper to My Drive 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.
+4. Test that same import with a **second account using normal CPO login** before
+   distributing it. The script prepares artifacts; it does not verify Google
+   permissions or perform either browser test.
 
-Keep both filenames unchanged and upload them as files without conversion.
+### Why save the JavaScript through CPO?
+
+CPO's normal login requests `drive.file`. Its `gdrive-js` loader uses an
+authenticated request, so uploading a public JavaScript file directly to Drive
+does not by itself authorize CPO to read it. Saving through CPO creates the file
+with CPO's authorization. CPO saves the editor text without compiling it.
+The outer `.arr` wrapper uses `shared-gdrive`, which has a public-file retrieval
+path, so that file can still be uploaded directly.
+
+For an existing JavaScript upload, **Open with → Code Pyret** in Google Drive,
+if offered, is another way to grant per-file access without changing its ID.
+Google documents this mechanism in its
+[Drive authorization guidance](https://developers.google.com/workspace/drive/api/guides/handle-errors#appNotAuthorizedToFile).
+Opening an arbitrary `editor#program=ID` link alone is not the same authorization
+action. Pasting a link into this script only selects an ID; it grants no access.
+
+This workflow still needs end-to-end verification with real CPO accounts.
+Success as the publisher does not establish access for other users. If another
+user gets a 403, they may need to authorize the JavaScript through Drive's
+**Open with → Code Pyret** too. Do not advertise a setup-free import until the
+second-account test passes. The old full-access login flow is not a prerequisite
+or a recommended workaround: Google may block it.
+
+Keep both filenames unchanged and preserve the file contents without conversion.
+Use **My Drive**, not a Google **Shared drive**: CPO’s Drive loader omits the
+shared-drive API flag, so files in Shared drives return 404 even when public.
+A shortcut under My Drive does not change where a file lives.
 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.
 
+If you previously uploaded directly to Drive (or used a Shared drive), rerun with
+`npm run release:drive -- --tag v0.2.0 --out release/cpo-authorized` and follow
+the CPO-save workflow above. Paste the new links when prompted so the wrapper
+uses the new JavaScript file ID. The fresh output directory preserves the old
+release artifacts; existing wrappers are never overwritten with a different ID.
+
 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

@@ -13,8 +13,8 @@ data Tree:
 sharing:
   method _spytial(self) -> List<S.SpytialRule>:
     [list:
-      S.orientation("children", [list: S.direction-below]),
-      S.align("siblings", S.alignment-horizontal)
+      S.orientation("children", [list: S.below]),
+      S.align("siblings", S.horizontal)
     ]
   end
 end
@@ -22,13 +22,11 @@ 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:
+the serializer puts each rule in its proper YAML section. Use named fields in
+records for optional properties and typed constructors for nested style blocks:
 
 ```pyret
-S.atom-style-with(S.default-atom-style-options
-  .with-selector("leaf")
-  .with-fill-style(S.default-fill-style.with-color("red")))
+S.atom-style("leaf", {fill-style: S.fill-style({color: "red"})})
 ```
 
 From the JavaScript host, after evaluating the program:
@@ -60,8 +58,9 @@ 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
+See the [layout rule guide](SPYTIAL_LANGUAGE.md) for examples and 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.
 
@@ -70,4 +69,3 @@ then run `npm run generate:spytial`. Commit the generated Pyret source, serializ
 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_LANGUAGE.md

@@ -0,0 +1,194 @@
+# Spyret's layout rule language
+
+Spyret lets a Pyret program describe how its data should be drawn. The
+`pyret/spytial.arr` library, imported as `S` below, provides typed constructors
+for Spytial constraints and directives. Each constructor returns an
+`S.SpytialRule`; put rules in an ordinary Pyret list. `S.diagram(value)` finds
+`_spytial` hooks on reachable values, collects their rules, and displays the
+diagram. See [layout hooks](SPYTIAL_HOOKS.md) for the hook contract and
+[the README](../README.md#pyret-import-describe-display) for the CPO import.
+This page describes the 0.3.0 source API. The published v0.2.0 wrapper uses
+prefixed enum names and `atom-style-with`; update those calls when moving to
+0.3.0. Style properties now use named records and typed blocks instead of
+`.with-*` chains.
+
+## A first diagram
+
+```pyret
+# Use the versioned wrapper import 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.SpytialRule>:
+    [list:
+      S.orientation("left + right", [list: S.below]),
+      S.orientation("left", [list: S.left]),
+      S.orientation("right", [list: S.right]),
+      S.atom-style("leaf", {fill-style: S.fill-style({color: "#e0f2ff"})})
+    ]
+  end
+end
+
+S.diagram(branch(leaf(1), leaf(2)))
+```
+
+The `left + right` selector finds parent-to-child pairs. For each pair,
+`below` places the child below the parent. The next two rules put
+left children to the left and right children to the right. The style rule fills
+leaf nodes. Rule order does not turn later rules into overrides; Spytial applies
+them together and reports conflicting constraints.
+
+The same constructors work in a local `import file("spytial.arr") as S` if the
+library is available as a file. That import supplies rule constructors; the
+versioned wrapper also supplies `diagram` and `diagram-with-rules`.
+
+## Selectors and direction
+
+A selector is a **string containing a Spytial relational expression**, not a
+Pyret function. A unary selector such as `"leaf"` selects nodes. A binary
+selector such as `"left"` or `"left + right"` selects `(source, target)` pairs.
+The expected arity depends on the rule. For orientation, the direction names
+describe where the **target** goes relative to the source. Thus, if `left`
+contains `(parent, child)`, `S.below` puts the child below its parent.
+
+Common expressions are a type name (`"leaf"`), a field name (`"left"`), a
+union (`"left + right"`), or a transitive closure (`"^(left + right)"`). Keep
+operators inside the quoted Pyret string. See [Spytial Core's selector
+documentation](https://github.com/sidprasad/spytial-core/blob/main/site/selectors.md)
+for the full expression language and arity rules.
+
+| Pyret direction | Meaning for the target |
+| --- | --- |
+| `S.above`, `S.below` | Strictly above or below; sideways offset is allowed. |
+| `S.left`, `S.right` | Strictly left or right; vertical offset is allowed. |
+| `S.directly-above`, `S.directly-below` | Above or below and horizontally centered. |
+| `S.directly-left`, `S.directly-right` | Left or right and vertically centered. |
+
+You can combine compatible directions, for example
+`[list: S.below, S.left]`. Opposites such as `above` and
+`below` cannot be combined. A `directly-*` direction can only be combined with
+its matching plain direction. Spyret checks these combinations when it
+serializes the rule list.
+
+## Constraints: layout and visibility
+
+| Constructor | What it does |
+| --- | --- |
+| `S.orientation(selector, directions)` | Places targets of a binary selector relative to sources. |
+| `S.cyclic(selector)` | Arranges nodes in the order of a binary selector around a circle. |
+| `S.align(selector, direction)` | Gives selected nodes or node pairs a common row (`S.horizontal`) or column (`S.vertical`). |
+| `S.group(selector, name)` | Draws a box around selected nodes; a binary selector makes a group per first-column key. |
+| `S.size(width, height)` | Sets node dimensions in pixels; select the affected nodes with `S.size-with(width, height, {selector: "..."})`. Both numbers must be positive. |
+| `S.hide-atom(selector)` | Removes selected nodes and their edges from the diagram. |
+
+For example:
+
+```pyret
+[list:
+  S.cyclic-with("next", {direction: S.counterclockwise}),
+  S.align("siblings", S.horizontal),
+  S.group("children", "Family"),
+  S.size-with(150, 80, {selector: "branch"}),
+  S.hide-atom("InternalNode")
+]
+```
+
+Constraints can also use `{hold: S.never}` to require that a relation
+**does not** hold. For instance, negating `S.above` means the target is
+not strictly above the source; it does not require the target to be below.
+`S.always` expresses the normal positive constraint.
+
+## Directives: appearance and labels
+
+| Constructor | What it does |
+| --- | --- |
+| `S.flag(name)` | Applies a global display flag such as `S.hide-disconnected` or `S.hide-disconnected-built-ins`. |
+| `S.atom-style(selector, style)` | Styles the selected nodes' fill, border, icon, label, and label visibility. |
+| `S.edge-style(field, style)` | Styles a relation's edge line and label, or hides the edge. |
+| `S.attribute(field)` | Shows a field as text inside its source node instead of as an edge. |
+| `S.tag(to-tag, name, value)` | Adds computed text to matching nodes while retaining the original edges. |
+| `S.hide-field(field)` | Hides a field's drawn edges. |
+| `S.inferred-edge(name, selector)` | Draws additional edges computed from a selector. |
+
+`field` names a relation; optional `selector` and `filter` fields narrow where
+field-based directives apply. `tag` takes a unary `to-tag` selector and a
+`value` selector whose first column identifies the node receiving the tag.
+
+```pyret
+[list:
+  S.flag(S.hide-disconnected-built-ins),
+  S.atom-style("leaf", {border-style: S.border-style({
+    color: "#2563eb", width: 2
+  })}),
+  S.edge-style("left", {line-style: S.line-style({
+    color: "#64748b", pattern: S.dashed
+  })}),
+  S.attribute("value"),
+  S.hide-field("internal"),
+  S.inferred-edge("descendant", "^(left + right)")
+]
+```
+
+Use `atom-style`, `edge-style`, and `inferred-edge` for new styles. The exported
+`icon`, `atom-color`, and `edge-color` constructors are older forms retained for
+compatibility.
+
+## Optional fields and reusable style blocks
+
+Rules with optional fields have a short constructor for their required
+arguments and a `-with` constructor that takes a Pyret record of named fields.
+`atom-style` takes a selector and a style record; `edge-style` takes a field
+and a style record. Within those records, nested styles use the named types
+`S.TextStyle`, `S.LineStyle`, `S.FillStyle`, `S.BorderStyle`, and `S.IconStyle`.
+For example, `S.text-style({color: "navy"})` makes a `TextStyle`. Leave any
+field out to let Spytial Core supply its display default.
+
+```pyret
+S.orientation-with("children", [list: S.below], {hold: S.always})
+
+S.group-with("children", "Family", {
+  add-edge: S.group-add-edge({
+    points: S.togroup,
+    line-style: S.line-style({weight: 2})
+  }),
+  text-style: S.text-style({color: "#7c3aed"})
+})
+```
+
+The group example draws a connector from each group key to its box. Its
+`line-style` styles that connector; the group's own `text-style` styles its
+caption. Most rule records also accept a `source: S.rule-source({...})` field;
+this records the originating rule text and optional location
+for error reports without changing layout.
+
+The [generated rule reference](SPYTIAL_RULES_REFERENCE.md) lists every
+constructor, option, enum, and style block for the currently pinned Core
+language version. Spyret checks Pyret types through annotations, then checks
+numeric bounds, string patterns, and direction compatibility while serializing.
+
+## How rules become a diagram
+
+`_spytial` returns `List<S.SpytialRule>`. Spyret turns each list into one YAML
+document with `constraints` and `directives` sections; constructors choose the
+correct section automatically. `S.diagram(value)` collects the hooks reachable
+from `value`. To bypass hooks, call `S.diagram-with-rules(value, rules)`; an
+existing YAML document can be passed as `S.diagram(value, yaml)`.
+
+For example, `S.orientation("left", [list: S.below])` represents the
+following constraint (the serializer quotes YAML keys and strings):
+
+```yaml
+constraints:
+  - orientation:
+      selector: left
+      directions: [below]
+directives: []
+```
+
+For host code, `getSpytialSpec(value, runtime)` returns the collected YAML
+documents as `string[]`, and `spytialRulesToYaml(rules, runtime)` serializes an
+already evaluated list. See [layout hooks](SPYTIAL_HOOKS.md) for collection
+order, error behavior, and runtime requirements.

package/docs/SPYTIAL_RULES_REFERENCE.md

@@ -3,9 +3,11 @@
 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)`.
+Enum values are qualified through `S`, for example `S.below` and `S.horizontal`.
+Optional fields use Pyret records with named keys. Pass the record to `<rule>-with`;
+`atom-style(selector, style)` and `edge-style(field, style)` take one directly.
+Nested style blocks are typed constructors such as `S.fill-style({color: "red"})`.
+Unset fields are omitted from YAML; Spytial Core supplies their defaults.
 
 Numeric bounds, patterns and incompatible direction combinations are checked during serialization.
 
@@ -18,8 +20,8 @@ Numeric bounds, patterns and incompatible direction combinations are checked dur
 | `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` |
+| `atom-style(selector :: String, style :: Any)` | A record with optional `fill-style`, `border-style`, `icon-style`, `text-style`, `show-label`, and `source` keys. |
+| `edge-style(field :: String, style :: Any)` | A record with optional `selector`, `filter`, `line-style`, `text-style`, `show-label`, `hidden`, and `source` keys. |
 | `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` |
@@ -30,22 +32,22 @@ Numeric bounds, patterns and incompatible direction combinations are checked dur
 
 ## 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`
+- `TextSize`: `small`, `normal`, `large`
+- `LinePattern`: `solid`, `dashed`, `dotted`
+- `IconPlacement`: `full`, `badge`
+- `Direction`: `above`, `below`, `left`, `right`, `directly-above`, `directly-below`, `directly-left`, `directly-right`
+- `Hold`: `always`, `never`
+- `Rotation`: `clockwise`, `counterclockwise`
+- `Alignment`: `horizontal`, `vertical`
+- `GroupEdgeDirection`: `no-group-edge`, `togroup`, `fromgroup`
+- `LayoutFlag`: `hide-disconnected`, `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>)`
+- `text-style({size: TextSize?, color: String?})`
+- `line-style({color: String?, pattern: LinePattern?, weight: Number?, highlight: String?})`
+- `fill-style({color: String?})`
+- `border-style({color: String?, width: Number?})`
+- `icon-style({path: String?, placement: IconPlacement?, opacity: Number?})`
+- `rule-source({text: String, location: String?})`
+- `group-add-edge({points: GroupEdgeDirection?, line-style: LineStyle?, text-style: TextStyle?})`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spyret",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Headless interfaces between standard Pyret and Spytial",
   "license": "MIT",
   "author": "Siddhartha Prasad",