lispgram 0.10.0

package/LAYOUT_LANGUAGE.md

@@ -0,0 +1,390 @@
+# Lispgram layout language
+
+This document describes the layout surface that Lispgram accepts today. It is intentionally small. The normal Lispgram graph language remains the primary authoring surface; `$layout` is an optional correction and template layer.
+
+The design rule is:
+
+```text
+write ordinary Lispgram first
+add $layout only when the inferred layout needs a visual nudge
+```
+
+## 1. Relationship to the Lispgram core
+
+The core Lispgram syntax is still enough for many diagrams:
+
+```lisp
+(lispgram
+  (P{Parent} A B C)
+  (-> f A B)
+  (-> g B C)
+  (-> meta f g))
+```
+
+From this small syntax the renderer infers:
+
+- visual containment from tree forms such as `(P A B C)`;
+- ordinary routes from arrows such as `(-> f A B)`;
+- self loops from ordinary self-arrows such as `(-> loop A A)`;
+- arrows between arrows from ordinary arrows such as `(-> meta f g)`;
+- curved lanes for repeated or anti-parallel endpoint pairs;
+- containment-scoped fallback rows/ranks;
+- locality for implicit targets that are introduced only by arrow references.
+
+`$layout` and legacy `$metalayout` forms are preserved as layout metadata. They do not enter semantic core facts.
+
+## 2. Basic shape
+
+A layout block is written inside a Lispgram document:
+
+```lisp
+(lispgram
+  (P A B C)
+  (-> f A B)
+
+  ($layout
+    (same-row [A B C])
+    (left-of A B)))
+```
+
+Legacy `$metalayout` is still accepted for the older arrow-shaped syntax:
+
+```lisp
+($metalayout
+  (-> $samerow [A B C])
+  (-> $leftof A B))
+```
+
+New code should prefer `$layout`.
+
+## 3. Strengths
+
+Most relative constraints accept an optional strength as their final positional argument:
+
+```lisp
+(same-row [A B C] strong)
+(left-of A B required)
+(same-x [X P] medium)
+```
+
+Implemented strength names are:
+
+```text
+required > strong > medium > weak
+```
+
+The solver also has a small numeric epsilon tolerance, so sub-pixel differences do not cause endless projection churn. Required constraints are still the strongest constraints; epsilon only controls when a nearly-satisfied numeric equation stops moving.
+
+## 4. Relative positioning forms
+
+### `same-row`
+
+Aligns the vertical centers of nodes/containers.
+
+```lisp
+(same-row [A B C])
+(same-row [A B C] strong)
+```
+
+Equivalent older spelling:
+
+```lisp
+(-> $samerow [A B C])
+```
+
+### `same-column` / `same-col`
+
+Aligns the horizontal centers of nodes/containers and performs initial vertical packing so the aligned objects do not collapse on top of each other.
+
+```lisp
+(same-column [A B C])
+(same-col [A B C])
+```
+
+Equivalent older spellings include `$samecol`, `$samecolumn`, `$same-col`, and `$same-column`.
+
+### `same-x`
+
+A softer x-alignment form. It aligns horizontal centers but defaults to `strong` instead of `required`.
+
+```lisp
+(same-x [X P])
+```
+
+### `left-of`
+
+Places the first object left of the second object.
+
+```lisp
+(left-of A B)
+(left-of A B required)
+```
+
+Equivalent older spellings include `leftof` and `$leftof`.
+
+### `above`
+
+Places one object above another object.
+
+```lisp
+(above X P)
+```
+
+The first argument may also be a vector in some template-lowered cases, but author-facing uses should usually keep it singular.
+
+### `below`
+
+Places one or more movers below an anchor.
+
+```lisp
+(below [A B C] P)
+(below A P)
+```
+
+### `center-over` / `center-x-over`
+
+Horizontally centers an object over the average center of target objects.
+
+```lisp
+(center-over P [A B])
+(center-x-over Product [A B C] strong)
+```
+
+This is useful for product/coproduct-like fan diagrams, but most authors should use a template view instead.
+
+## 5. Route endpoint references
+
+Most route directives accept endpoints. A bare id refers to a node/container by id.
+
+```lisp
+(route h :from A :to B)
+```
+
+The following endpoint constructors are also available:
+
+```lisp
+(node A)                 ;; force a node endpoint
+(container C)            ;; force a container endpoint
+(boundary C left)        ;; selected boundary side of a node/container/island
+(boundary C right 0.25)  ;; side plus optional normalized side position
+(route f)                ;; route midpoint of f
+(arrow f)                ;; alias of route endpoint
+(mid f)                  ;; route midpoint
+(start f)                ;; route start anchor
+(end f)                  ;; route end anchor
+(label f)                ;; label anchor
+```
+
+`(-> meta f g)` does not need `$layout`: arrow-to-arrow routes are inferred automatically and anchor to the final visible geometry of `f` and `g`.
+
+## 6. Route directives
+
+### `route`
+
+Overrides the visual endpoints or role of an existing arrow.
+
+```lisp
+(route h :from A :to B)
+(route h :from (mid f) :to (mid g) :role route-arrow)
+(route h :from A :to B :shape straight :label h)
+```
+
+When `route` is used, the automatic rank pressure from the arrow's original semantic endpoints is suppressed for that arrow. This prevents the old semantic direction from fighting the explicit visual route.
+
+### `parallel-pair`
+
+Draws a set of arrows as global parallel lanes between the same visual endpoints.
+
+```lisp
+(parallel-pair [f g h] :from A :to B)
+```
+
+Despite the historical name, this can handle more than two arrows. The engine also infers parallel and anti-parallel lanes from ordinary Lispgram arrows where possible, so use this only when the automatic lane grouping needs to be overridden.
+
+### `attach-at-boundary`
+
+Places an external source subtree outside a boundary side, then routes the arrow through that side-port.
+
+```lisp
+(attach-at-boundary h
+  :from ReviewThread
+  :to S
+  :boundary CoproductBox
+  :side left)
+```
+
+Supported sides are `left`, `right`, `top`, and `bottom`.
+
+This directive is both a placement hint and a route directive. It should be used for hierarchy-route-style diagrams where something external connects into a container/island boundary.
+
+### `parallel-to-boundary`
+
+Places a route alongside a selected boundary without making its endpoints members of that boundary owner.
+
+```lisp
+(parallel-to-boundary q
+  :from M
+  :to N
+  :boundary C
+  :side left)
+```
+
+## 7. Self loops
+
+Self loops are not a `$layout` directive. They are ordinary arrows:
+
+```lisp
+(lispgram
+  (A)
+  (-> loop A A))
+```
+
+`$layout (self-loop ...)` and `$layout (loop ...)` intentionally error. This keeps loops in the small core language.
+
+## 8. Template / view directives
+
+Templates are written as layout views:
+
+```lisp
+($layout
+  (view product
+    :product P
+    :factors [A B]
+    :test-object X
+    :mediator u
+    :projections [pi1 pi2]
+    :cone-legs [f g]
+    :container C))
+```
+
+`view` and `template` are aliases. Templates emit ordinary relative constraints, route directives, and an island/layout view. They do not directly assign final coordinates.
+
+Common keyword conventions:
+
+- `:id` names the layout island. If omitted, the engine generates a template-specific id.
+- `:container` links the view to a visual container shell when safe.
+- `:mode full` asks the template to include optional outer/cone-leg routes where supported.
+- Supplying `:cone-legs` for product/coproduct automatically selects full mode.
+
+### Product
+
+```lisp
+(view product
+  :product P
+  :factors [A B]
+  :test-object X
+  :mediator u
+  :projections [pi1 pi2]
+  :cone-legs [f g]
+  :container C)
+```
+
+Visual convention:
+
+```text
+X above P
+P centered over factors
+factors in a row below P
+projections fan downward
+mediator is centered
+```
+
+Aliases: `product`, `product-cone`.
+
+### Coproduct
+
+```lisp
+(view coproduct
+  :coproduct S
+  :summands [A B]
+  :test-object X
+  :mediator u
+  :injections [i1 i2]
+  :cone-legs [f g]
+  :container CΣ)
+```
+
+Aliases: `coproduct`, `sum`, `sum-type`.
+
+### Equalizer
+
+```lisp
+(view equalizer
+  :equalizer E
+  :source A
+  :target B
+  :inclusion e
+  :parallel [f g])
+```
+
+### Pullback / pushout
+
+```lisp
+(view pullback
+  :corners [TL TR BL BR]
+  :arrows [top left bottom right])
+
+(view pushout
+  :corners [TL TR BL BR]
+  :arrows [top left bottom right])
+```
+
+The corner order is top-left, top-right, bottom-left, bottom-right.
+
+### Exponential
+
+```lisp
+(view exponential
+  :exponential BA
+  :source A
+  :target B
+  :product AxBA
+  :evaluation eval)
+```
+
+### Hasse / ranked rows
+
+```lisp
+(view hasse
+  :rows [[Bottom] [A B] [Top]])
+```
+
+The current surface lowering preserves rows and claims the island. Cover arrows can still be ordinary Lispgram arrows or explicit `route` directives.
+
+## 9. NCF round trip
+
+`toNCF()` emits layout metadata as a top-level `(layout ...)` block, and public `toNCFDoc()` can read raw NCF back into `doc.layoutForms`. Layout metadata remains outside semantic core. The lower-level `parseNCF()` helper exists inside the implementation but is not part of the minimal public npm export surface.
+
+A simplified NCF shape looks like:
+
+```lisp
+(cy
+  (nodes ...)
+  (edges ...)
+  (layout
+    (same-row [A B C])
+    (view product :product P :factors [A B])))
+```
+
+## 10. Recommended authoring style
+
+Prefer this:
+
+```lisp
+(lispgram
+  (P{Parent} A B C)
+  (-> f A B)
+  (-> g B C)
+  (-> meta f g))
+```
+
+Add this only when needed:
+
+```lisp
+($layout
+  (same-row [A B C])
+  (attach-at-boundary h :from External :to P :boundary C :side left)
+  (view product :product P :factors [A B]))
+```
+
+Avoid using `$layout` to restate obvious graph facts. The engine should infer containers, self-loops, arrow-to-arrow routes, parallel lanes, and many ordinary ranks from the small core syntax.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.