pygeomatic 0.1.0__tar.gz → 0.2__tar.gz

pygeomatic-0.2/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: pygeomatic
+Version: 0.2
+Summary: Python mirror of the geomatic DSL function library; records calls for deterministic DSL emission
+Project-URL: Homepage, https://github.com/TinyVolt/pygeomatic
+Project-URL: Repository, https://github.com/TinyVolt/pygeomatic
+Project-URL: Issues, https://github.com/TinyVolt/pygeomatic/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# pygeomatic
+
+Python mirror of the [geomatic](https://www.tinyvolt.com/geomatic) DSL. Intended to be used in [Nova editor](https://www.tinyvolt.com/nova). 
+
+Every public function maps 1:1 to a geomatic command; calling it computes numeric values (numpy) where
+possible **and** records the call onto a tape, from which `emit()` produces
+geomatic DSL lines deterministically.
+
+## Naming
+
+Every node has an id. You control it in three ways.
+
+**Programmatically** — pass `out=` with an f-string (or any computed string),
+so ids can be generated in a loop:
+
+```python
+>>> for i in range(5):
+...   gm.point(i-3, 0, out=f'point{i}')
+...
+Point(id='point0', x=-3.0, y=0.0)
+Point(id='point1', x=-2.0, y=0.0)
+Point(id='point2', x=-1.0, y=0.0)
+Point(id='point3', x=0.0, y=0.0)
+Point(id='point4', x=1.0, y=0.0)
+```
+
+**By assignment** — the assignment target names the output (underscores become
+dashes). Without a target, the id is auto-assigned a dashed form (`p-0`,
+`num-1`):
+
+```python
+>>> my_p
+Point(id='my-p', x=2.0, y=3.0)
+>>> gm.point(3,2)
+Point(id='p-0', x=3.0, y=2.0)
+```
+
+Assignment naming works at any arity — `a, b, c = gm.scalar(1), gm.scalar(2), gm.scalar(3)` names all three. 
+An explicit `out="my-id"` always overrides the
+inferred name.
+
+Anything ambiguous or unsafe (no assignment target, attribute targets, reusing
+a name in a loop, a name shaped like an engine auto-name, an already-taken id)
+silently falls back to a dashed auto-id. Explicit ids must match the DSL
+grammar: start with a letter, then letters/digits/dashes, **no underscores** —
+and must not look like an engine auto-name (`num0`, `p3`, `text1`). The engine
+generates those for its own internal nodes, and a collision creates a reactive
+cycle that hangs the tab; pygeomatic's dashed ids can never collide. Name
+inference reads the caller's bytecode, not its source, so it behaves
+identically everywhere: files, the REPL, `python -c`, notebooks, `exec`'d
+strings.
+
+Whichever way a node was named, `gm.emit()` renders the tape as DSL, one line
+per call, using each node's resolved id. The examples above emit as:
+
+```
+>>> print(gm.emit())
+point0 = \point -3 0
+point1 = \point -2 0
+point2 = \point -1 0
+point3 = \point 0 0
+point4 = \point 1 0
+my-p = \point 2 3
+p-0 = \point 3 2
+```
+
+
+## Built-in variables
+
+Every canvas — and every `Store` — starts with the engine's default nodes
+already registered, so a scene may reference them by id without defining them
+first. They record no commands (they exist implicitly on every canvas) and
+resolve against the active store at access time. Access them as module
+attributes with dashes turned into underscores (`gm.p0`, `gm.learning_rate`),
+or by id with `gm.node("learning-rate")`.
+
+You may reassign any of them (`gm.scalar(0.5, out="learning-rate")`), matching
+the engine's last-write-wins `saveNode`.
+
+| Variable | Value | What it is / when to use it |
+| --- | --- | --- |
+| `p0` | `(0, 0)` | The world origin. It is the default `center`/`point2` for many commands (`\circle`, `\ellipse`, `\square`, `\rectangle`, `\reflect-point`, …), so reference it for a fixed origin instead of re-declaring `\point 0 0`. |
+| `learning-rate` | `0.01` | Gradient-descent step size, read by `\gradient-descent-step` and `\minimize`. Reassign before a descent step to tune training speed. |
+| `animation-speed` | `0.001` | Per-frame step size for `\animate`. Reassign larger to make animations run faster, smaller to slow them. |
+| `grid-points` | Point array | Every integer-lattice Point currently on the canvas (built from the live canvas bounds, so numerically unknown here). Reference it to act on the whole background grid at once, e.g. apply a linear map / `\translate-array` to every grid point. |
+| `unit` | `50` | Zoom: pixels per world unit (`unitX == unitY == unit`). Reassign to zoom (larger = more zoomed in). |
+| `grid-opacity` | `1` | Opacity of the grid lines and axes. Set to `0` to hide the grid. |
+| `grid-bg-color` | `""` | Solid fill painted behind the grid (empty = transparent). Reassign to a color (`grid-bg-color = COLOR-BLACK`) to give the canvas a background. |
+| `grid-origin` | `(0, 0)` | Where the world origin sits on the canvas, in world units (`(0, 0)` = centered). Reassign to pan the view. |
+| `T` | `true` | The boolean literal `true`, referenceable wherever a Bool argument is expected. |
+| `F` | `false` | The boolean literal `false`, referenceable wherever a Bool argument is expected. |
+
+```python
+gm.line(gm.p0, gm.point(1, 1))          # p0 by attribute
+gm.scalar(0.5, out="learning-rate")     # reassign a default (last-write-wins)
+gm.node("unit")                          # the string-keyed equivalent
+```
+
+## Authoring articles with Nova
+
+Write geomatic articles as markdown with pygeomatic Python instead of raw DSL;
+`compile_article` turns them into the `{label}(command)` span format. The Python
+runs once at compile time — readers only ever receive deterministic DSL text.
+
+````markdown
+```pygeomatic
+origin = gm.p0                    # top-level code → hidden {}(...) setup spans
+a = gm.point(3, 0)
+walk = gm.line(origin, a)
+gm.hide(walk)
+
+with group("walk-x"):             # a named run of commands for prose to reveal
+    gm.highlight(walk)
+    gm.show(walk)                 # last command gets the visible label
+```
+
+Reach the point by {moving a distance}(ref:walk-x) of $3$ units.
+Or reset it inline: {set scale to 1}(scale = gm.scalar(1)).
+````
+
+- **One store per article**: all fences and inline spans run in document order
+  sharing state, so ids and auto-names stay consistent.
+- **Ref expansion**: every command of a group but the last becomes a hidden
+  `{}()` span before the visible one — a click always lands on a fully set-up
+  scene.
+- **Inline spans** (`{label}(python statement)`) are the escape hatch for
+  one-offs; article mode is last-write-wins, so `s1 = gm.scalar(1)` reassigns
+  like the DSL line it becomes.
+- **Round-trip gate**: the compiled document is replayed with `parse_dsl` in
+  document order; broken ordering or invalid DSL fails the compile, not the
+  reader.
+- Regular code fences and `$...$` math are never scanned for spans.
+
+```sh
+uv run python scripts/compile_article.py article.md -o compiled.md   # one file
+uv run python scripts/compile_articles.py articles/ dist/            # a tree
+```
+
+(equivalently `gm.compile_article(md)` in-process or `gm.run_article(md)` in a
+subprocess; both take `extensions=` / `macros=` / `allow_coercions=`.)
+
+### Publishing from a content repo (GitHub Action)
+
+A content repo publishes compiled articles with one workflow file; a compile
+error in any article fails the push and nothing is published:
+
+```yaml
+name: Publish articles
+on:
+  push: {branches: [main]}
+jobs:
+  publish:
+    permissions: {contents: write}
+    uses: TinyVolt/pygeomatic/.github/workflows/publish-articles.yml@main
+```
+
+This compiles `articles/` and force-pushes the result (plus any non-markdown
+assets) to a `dist` branch, which raw.githubusercontent.com serves with CORS.
+Inputs: `source`, `publish-branch`, `extensions`, `macros`, `allow-coercions`,
+and `pygeomatic-ref` — pin the latter to a tag or SHA for reproducible output.
+For custom pipelines, the composite action `TinyVolt/pygeomatic@<ref>` runs just
+the compile step (the `<ref>` you pin is also the exact pygeomatic version
+used).
+
+### Reading published articles
+
+Once the `dist` branch exists, the article is live — readers open it at
+
+```
+https://www.tinyvolt.com/nova/<username>/<repo>/<article>
+```
+
+where `<article>` is the markdown file's path within `dist` (the `.md` suffix
+is optional). E.g. `articles/intro.md` compiled from the repo `alice/vectors`
+is read at `/nova/alice/vectors/intro`.
+
+If the article uses extension commands or macros, bake their URLs into the link
+you share so readers never load anything manually:
+
+- `?ext=<manifest-url>` — extension manifest, loaded (sandboxed, from
+  whitelisted domains only) before the article renders.
+- `?esm=<url>` — macro definitions, fetched and registered on page load.

pygeomatic-0.2/README.md

@@ -0,0 +1,182 @@
+# pygeomatic
+
+Python mirror of the [geomatic](https://www.tinyvolt.com/geomatic) DSL. Intended to be used in [Nova editor](https://www.tinyvolt.com/nova). 
+
+Every public function maps 1:1 to a geomatic command; calling it computes numeric values (numpy) where
+possible **and** records the call onto a tape, from which `emit()` produces
+geomatic DSL lines deterministically.
+
+## Naming
+
+Every node has an id. You control it in three ways.
+
+**Programmatically** — pass `out=` with an f-string (or any computed string),
+so ids can be generated in a loop:
+
+```python
+>>> for i in range(5):
+...   gm.point(i-3, 0, out=f'point{i}')
+...
+Point(id='point0', x=-3.0, y=0.0)
+Point(id='point1', x=-2.0, y=0.0)
+Point(id='point2', x=-1.0, y=0.0)
+Point(id='point3', x=0.0, y=0.0)
+Point(id='point4', x=1.0, y=0.0)
+```
+
+**By assignment** — the assignment target names the output (underscores become
+dashes). Without a target, the id is auto-assigned a dashed form (`p-0`,
+`num-1`):
+
+```python
+>>> my_p
+Point(id='my-p', x=2.0, y=3.0)
+>>> gm.point(3,2)
+Point(id='p-0', x=3.0, y=2.0)
+```
+
+Assignment naming works at any arity — `a, b, c = gm.scalar(1), gm.scalar(2), gm.scalar(3)` names all three. 
+An explicit `out="my-id"` always overrides the
+inferred name.
+
+Anything ambiguous or unsafe (no assignment target, attribute targets, reusing
+a name in a loop, a name shaped like an engine auto-name, an already-taken id)
+silently falls back to a dashed auto-id. Explicit ids must match the DSL
+grammar: start with a letter, then letters/digits/dashes, **no underscores** —
+and must not look like an engine auto-name (`num0`, `p3`, `text1`). The engine
+generates those for its own internal nodes, and a collision creates a reactive
+cycle that hangs the tab; pygeomatic's dashed ids can never collide. Name
+inference reads the caller's bytecode, not its source, so it behaves
+identically everywhere: files, the REPL, `python -c`, notebooks, `exec`'d
+strings.
+
+Whichever way a node was named, `gm.emit()` renders the tape as DSL, one line
+per call, using each node's resolved id. The examples above emit as:
+
+```
+>>> print(gm.emit())
+point0 = \point -3 0
+point1 = \point -2 0
+point2 = \point -1 0
+point3 = \point 0 0
+point4 = \point 1 0
+my-p = \point 2 3
+p-0 = \point 3 2
+```
+
+
+## Built-in variables
+
+Every canvas — and every `Store` — starts with the engine's default nodes
+already registered, so a scene may reference them by id without defining them
+first. They record no commands (they exist implicitly on every canvas) and
+resolve against the active store at access time. Access them as module
+attributes with dashes turned into underscores (`gm.p0`, `gm.learning_rate`),
+or by id with `gm.node("learning-rate")`.
+
+You may reassign any of them (`gm.scalar(0.5, out="learning-rate")`), matching
+the engine's last-write-wins `saveNode`.
+
+| Variable | Value | What it is / when to use it |
+| --- | --- | --- |
+| `p0` | `(0, 0)` | The world origin. It is the default `center`/`point2` for many commands (`\circle`, `\ellipse`, `\square`, `\rectangle`, `\reflect-point`, …), so reference it for a fixed origin instead of re-declaring `\point 0 0`. |
+| `learning-rate` | `0.01` | Gradient-descent step size, read by `\gradient-descent-step` and `\minimize`. Reassign before a descent step to tune training speed. |
+| `animation-speed` | `0.001` | Per-frame step size for `\animate`. Reassign larger to make animations run faster, smaller to slow them. |
+| `grid-points` | Point array | Every integer-lattice Point currently on the canvas (built from the live canvas bounds, so numerically unknown here). Reference it to act on the whole background grid at once, e.g. apply a linear map / `\translate-array` to every grid point. |
+| `unit` | `50` | Zoom: pixels per world unit (`unitX == unitY == unit`). Reassign to zoom (larger = more zoomed in). |
+| `grid-opacity` | `1` | Opacity of the grid lines and axes. Set to `0` to hide the grid. |
+| `grid-bg-color` | `""` | Solid fill painted behind the grid (empty = transparent). Reassign to a color (`grid-bg-color = COLOR-BLACK`) to give the canvas a background. |
+| `grid-origin` | `(0, 0)` | Where the world origin sits on the canvas, in world units (`(0, 0)` = centered). Reassign to pan the view. |
+| `T` | `true` | The boolean literal `true`, referenceable wherever a Bool argument is expected. |
+| `F` | `false` | The boolean literal `false`, referenceable wherever a Bool argument is expected. |
+
+```python
+gm.line(gm.p0, gm.point(1, 1))          # p0 by attribute
+gm.scalar(0.5, out="learning-rate")     # reassign a default (last-write-wins)
+gm.node("unit")                          # the string-keyed equivalent
+```
+
+## Authoring articles with Nova
+
+Write geomatic articles as markdown with pygeomatic Python instead of raw DSL;
+`compile_article` turns them into the `{label}(command)` span format. The Python
+runs once at compile time — readers only ever receive deterministic DSL text.
+
+````markdown
+```pygeomatic
+origin = gm.p0                    # top-level code → hidden {}(...) setup spans
+a = gm.point(3, 0)
+walk = gm.line(origin, a)
+gm.hide(walk)
+
+with group("walk-x"):             # a named run of commands for prose to reveal
+    gm.highlight(walk)
+    gm.show(walk)                 # last command gets the visible label
+```
+
+Reach the point by {moving a distance}(ref:walk-x) of $3$ units.
+Or reset it inline: {set scale to 1}(scale = gm.scalar(1)).
+````
+
+- **One store per article**: all fences and inline spans run in document order
+  sharing state, so ids and auto-names stay consistent.
+- **Ref expansion**: every command of a group but the last becomes a hidden
+  `{}()` span before the visible one — a click always lands on a fully set-up
+  scene.
+- **Inline spans** (`{label}(python statement)`) are the escape hatch for
+  one-offs; article mode is last-write-wins, so `s1 = gm.scalar(1)` reassigns
+  like the DSL line it becomes.
+- **Round-trip gate**: the compiled document is replayed with `parse_dsl` in
+  document order; broken ordering or invalid DSL fails the compile, not the
+  reader.
+- Regular code fences and `$...$` math are never scanned for spans.
+
+```sh
+uv run python scripts/compile_article.py article.md -o compiled.md   # one file
+uv run python scripts/compile_articles.py articles/ dist/            # a tree
+```
+
+(equivalently `gm.compile_article(md)` in-process or `gm.run_article(md)` in a
+subprocess; both take `extensions=` / `macros=` / `allow_coercions=`.)
+
+### Publishing from a content repo (GitHub Action)
+
+A content repo publishes compiled articles with one workflow file; a compile
+error in any article fails the push and nothing is published:
+
+```yaml
+name: Publish articles
+on:
+  push: {branches: [main]}
+jobs:
+  publish:
+    permissions: {contents: write}
+    uses: TinyVolt/pygeomatic/.github/workflows/publish-articles.yml@main
+```
+
+This compiles `articles/` and force-pushes the result (plus any non-markdown
+assets) to a `dist` branch, which raw.githubusercontent.com serves with CORS.
+Inputs: `source`, `publish-branch`, `extensions`, `macros`, `allow-coercions`,
+and `pygeomatic-ref` — pin the latter to a tag or SHA for reproducible output.
+For custom pipelines, the composite action `TinyVolt/pygeomatic@<ref>` runs just
+the compile step (the `<ref>` you pin is also the exact pygeomatic version
+used).
+
+### Reading published articles
+
+Once the `dist` branch exists, the article is live — readers open it at
+
+```
+https://www.tinyvolt.com/nova/<username>/<repo>/<article>
+```
+
+where `<article>` is the markdown file's path within `dist` (the `.md` suffix
+is optional). E.g. `articles/intro.md` compiled from the repo `alice/vectors`
+is read at `/nova/alice/vectors/intro`.
+
+If the article uses extension commands or macros, bake their URLs into the link
+you share so readers never load anything manually:
+
+- `?ext=<manifest-url>` — extension manifest, loaded (sandboxed, from
+  whitelisted domains only) before the article renders.
+- `?esm=<url>` — macro definitions, fetched and registered on page load.

{pygeomatic-0.1.0 → pygeomatic-0.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pygeomatic"
-version = "0.1.0"
+version = "0.2"
 description = "Python mirror of the geomatic DSL function library; records calls for deterministic DSL emission"
 readme = "README.md"
 license = "MIT"

{pygeomatic-0.1.0 → pygeomatic-0.2}/src/pygeomatic/__init__.py

@@ -105,6 +105,16 @@ from .system_nodes import (  # noqa: F401
     SystemNode,
     register_system_nodes,
 )
+from .tex import (  # noqa: F401
+    SCHEMA,
+    AxisExpr,
+    Selector,
+    Tex,
+    TexError,
+    harvest_tex_bindings,
+    register_tex_schema,
+    tex,
+)
 
 
 def __getattr__(name: str) -> GNode:

{pygeomatic-0.1.0 → pygeomatic-0.2}/src/pygeomatic/article.py

@@ -38,10 +38,27 @@ from contextvars import ContextVar
 from dataclasses import dataclass, field
 from typing import Optional, Sequence, Union
 
+import json
+
 from .coercions import allow_coercions
 from .emit import emit, render_command
 from .parse import DslParseError, parse_dsl
-from .store import Store, _article_replay, current_store
+from .store import Store, _article_replay, _auto_create_enabled, current_store
+from .tex import harvest_tex_bindings
+
+# texatlas bindings (gm.tex) are declarative page config, not DSL: the compiler
+# harvests them from the session and snapshots them into the compiled article as
+# an HTML comment (invisible to any markdown renderer, easily extracted by the
+# reader). Not a span, not a fence — the round-trip gate never sees it.
+_TEX_MANIFEST_OPEN = "<!-- texatlas:v1"
+_TEX_MANIFEST_CLOSE = "-->"
+
+
+def _append_tex_manifest(compiled: str, manifest: dict) -> str:
+    body = json.dumps(manifest, separators=(",", ":"), sort_keys=False)
+    block = f"{_TEX_MANIFEST_OPEN}\n{body}\n{_TEX_MANIFEST_CLOSE}\n"
+    sep = "" if compiled.endswith("\n") or not compiled else "\n"
+    return f"{compiled}{sep}\n{block}"
 
 
 class ArticleError(ValueError):
@@ -528,6 +545,11 @@ def compile_article(markdown: str, *, allow_coercions: bool = False) -> str:
         for s in _scan_spans(part.text)
     ]
     with Store() as check, article_mode():
+        # Strict replay: auto-creating a missing Point/Scalar/Text here would
+        # mask a define-before-use violation (the reader's engine would bind
+        # the consumer to a random-valued auto-created node, not the article's
+        # later definition), so unknown ids must fail the gate.
+        auto_create_token = _auto_create_enabled.set(False)
         try:
             parse_dsl(commands)
         except DslParseError as exc:
@@ -536,6 +558,8 @@ def compile_article(markdown: str, *, allow_coercions: bool = False) -> str:
                 f"compiled article failed the parse round-trip (command "
                 f"{exc.lineno} in document order): {exc}",
             ) from exc
+        finally:
+            _auto_create_enabled.reset(auto_create_token)
         replayed = emit(check).splitlines()
     if replayed != commands:
         for i, (got, want) in enumerate(zip(replayed, commands)):
@@ -550,6 +574,14 @@ def compile_article(markdown: str, *, allow_coercions: bool = False) -> str:
             f"round-trip drift: {len(commands)} command(s) in the document, "
             f"{len(replayed)} after replay",
         )
+
+    # -- texatlas snapshot ---------------------------------------------------
+    # Harvest the session's gm.tex bindings (recorded off-tape) and embed them,
+    # after the round-trip gate so the DSL replay is never disturbed. Articles
+    # with no bindings are byte-for-byte unchanged.
+    manifest = harvest_tex_bindings(store)
+    if manifest:
+        compiled = _append_tex_manifest(compiled, manifest)
     return compiled
 
 

{pygeomatic-0.1.0 → pygeomatic-0.2}/src/pygeomatic/macros.py

@@ -35,14 +35,16 @@ from typing import Any, Optional, Union
 from .coercions import _coercions_enabled
 from .emit import _render_number
 from .inference import infer_out_name
-from .nodes import GNode
+from .nodes import GNode, IdRef
 from .prompting import python_name
 from .registry import FunctionDef, P, REGISTRY
 from .store import (
     IDENTIFIER_RE,
+    UnresolvedId,
     _allow_engine_ids,
     _macro_replay,
     current_store,
+    validate_identifier,
 )
 
 MACRO_CATEGORY = "Macros"
@@ -178,6 +180,25 @@ def _make_wrapper(macro: MacroDef, source: str):
         subs: dict[str, str] = {}
         tokens = []
         for name, arg in zip(macro.params, args):
+            if isinstance(arg, (str, UnresolvedId)):
+                # A string names a node. An existing one binds like a GNode; a
+                # missing one substitutes as a bare id and the body replay
+                # auto-creates it on first typed use (engine parity: the engine
+                # runs macro bodies through the executor line-by-line).
+                ref = arg.name if isinstance(arg, UnresolvedId) else arg
+                found = store.nodes.get(ref)
+                if found is not None:
+                    arg = found
+                else:
+                    validate_identifier(ref)
+                    if ref in macro.assigned_ids:
+                        raise ValueError(
+                            f"\\{macro.keyword}: input id {ref!r} conflicts with "
+                            "an internal macro variable"
+                        )
+                    tokens.append(IdRef(ref))
+                    subs[name] = ref
+                    continue
             if isinstance(arg, GNode):
                 if arg.id is None:
                     raise TypeError(

{pygeomatic-0.1.0 → pygeomatic-0.2}/src/pygeomatic/parse.py

@@ -11,8 +11,11 @@ Supported grammar (exactly what emit produces / the engine accepts):
 
 where an arg is a number (positional notation), a node id, a property chain
 (`v.p1.x`, whitelist-checked per node type), or — for `\\text` only — a quoted
-string. Blank lines are skipped. Define-before-use is enforced (an id must
-name an earlier output).
+string. Blank lines are skipped. An id normally names an earlier output, but —
+engine parity (CommandExecutor.createAndSaveNode) — an unknown bare id filling
+a Point/Scalar/Text parameter is auto-created (random Point/Scalar payload,
+the id itself as a Text's value) instead of erroring, so `\\line a b` works on
+a fresh store. Auto-created nodes record no command, exactly like the engine.
 
 Engine-generated ids (`p0`, `num1`, ...) are accepted here — pasted scenes
 legitimately contain them — even though pygeomatic rejects them for ids YOU
@@ -36,7 +39,7 @@ from .coercions import _coercions_enabled
 from .nodes import GNode, NODE_PROPERTIES
 from .prompting import python_name
 from .registry import REGISTRY
-from .store import _allow_engine_ids, current_store
+from .store import UnresolvedId, _allow_engine_ids, current_store
 
 _LINE_RE = re.compile(
     r"^(?:(?P<out>[A-Za-z][A-Za-z0-9-]*)\s*=\s*)?"
@@ -70,9 +73,18 @@ def _resolve_ref(tok: str, store, lineno: int, line: str):
     base = m.group("base")
     node = store.nodes.get(base)
     if node is None:
-        raise DslParseError(
-            lineno, line, f"unknown node id {base!r} — geomatic requires define-before-use"
-        )
+        if m.group("path"):
+            # Engine parity (resolvePropertyAccess): a `.prop` chain carries no
+            # type hint to auto-create its base from.
+            raise DslParseError(
+                lineno,
+                line,
+                f"unknown node id {base!r} — cannot access "
+                f"'{m.group('path').lstrip('.')}' on it",
+            )
+        # A bare unknown identifier is auto-created by the binder from the
+        # parameter type it fills (engine parity: createAndSaveNode).
+        return UnresolvedId(base)
     for field in m.group("path").lstrip(".").split(".") if m.group("path") else []:
         allowed = NODE_PROPERTIES.get(node.type, {})
         if field not in allowed: