Skip to main content

Scripting And Code Layout

Morph authoring is not only about manifests.

A package feature usually has real implementation files behind it, and those files should follow the package boundary instead of pushing logic into core.

What "Scripting" Means Here​

In Morph authoring, the implementation side of a feature usually lives as package-owned source files that back:

  • syntax hooks
  • semantic hooks
  • lowering hooks
  • runtime handlers
  • backend route emitters
  • tooling commands

The code can be C++, generated glue, or package runtime code, but it should still stay inside the package layout.

Keep Files Near Ownership​

A feature should keep its implementation close to its manifest.

Typical pattern:

morphs/<Package>/features/<feature>/
  feature.toml
  Feature.cpp
  Behavior.cpp
  Emit.cpp

Grammar-heavy surfaces often split block.toml into a sibling blocks/ tree (syntax/sema/lowering per form):

morphs/<Package>/blocks/<block>/
  block.toml
  Syntax.cpp
  Sema.cpp
  Lowering.cpp

You should be able to answer "who owns this file?" by looking at its package path. If the folder has a manifest, ensure the root morph.toml [include] glob covers it (features/*/feature.toml, blocks/*/block.toml).

Common Layout Pattern​

Good package-local implementation layout usually groups:

  • declaration manifest
  • semantic behavior
  • lowering behavior
  • route emitters
  • helper code that only exists for that feature

If helper code belongs only to one feature, keep it with that feature.

What To Avoid​

Avoid these patterns:

  • package behavior hidden in generic src/ helpers
  • feature code split across unrelated folders because core already had a convenient file
  • package-local command logic placed in generic CLI host files

That is how feature ownership erodes.

Scripts vs Runtime Code​

Do not confuse package implementation code with package runtime code.

  • feature implementation files usually wire syntax, sema, lowering, or tooling
  • runtime/ files own package runtime behavior

Both are package-owned, but they solve different problems.

Next Steps​