Skip to content

example_dossier_standard.md

Latest commit

 

History

History
251 lines (214 loc) · 9.1 KB

example_dossier_standard.md

File metadata and controls

251 lines (214 loc) · 9.1 KB

FROG logo

FROG Example Dossier Standard

Common organization for public FROG examples
FROG - Free Open Graphical Language

Purpose

A FROG example is a focused, inspectable dossier. It is not the owner of language semantics. It demonstrates how a specific language feature, widget surface, operator, library call, structure, compiler corridor, or runtime-facing contract is represented through the public FROG artifact chain.

Each example should make one primary idea easy to inspect. If an example combines several already validated ideas, it should name the new composition being tested and should reuse the accepted baselines instead of redefining them.

Minimum Dossier Shape

A numbered example directory should contain the smallest set of files needed to make its public claim inspectable:

File or directory Role When expected
Readme.md Human explanation of the example, its focus, artifact path, validation posture, and limitations. Always.
main.frog Canonical FROG source for the example. Always, unless the example is explicitly a documentation-only mirror.
main.fir.json Derived FIR / execution-facing representation of the source. Required for accepted executable examples.
main.lowering.json Lowered execution/backend handoff for the example. Required for accepted executable examples.
Implementations/Reference/LLVM/examples/<example>/kernel.ll LLVM IR proof for the current executable example validation corridor. Required for accepted executable examples in the current LLVM/native line.
Implementations/Reference/LLVM/examples/<example>/native_kernel_manifest.json Native/provider manifest declaring ABI, entry symbols, inputs, outputs, artifacts, and provider dependencies where relevant. Required for accepted executable examples in the current LLVM/native line.
ui/*.wfrog Front-panel realization package references, Default asset references, and host capability declarations. When the example has a front panel or widget surface.
assets/ Example-owned input fixtures such as sample images or data files. Only for true example data fixtures, not duplicated Default widget skins.

Compiler, conformance, or library examples may add specialized artifacts when they are the subject of the example. Those artifacts should be linked from the example README and should not obscure the primary source-to-artifact story.

For the current executable example line, the acceptance corridor is complete only when it reaches LLVM IR, a native artifact or native artifact build material, a manifest, and runtime-host consumption. Documentation-only, negative conformance, or explicitly exploratory examples may stop earlier, but their README must state that limitation instead of implying executable closure. This does not make LLVM the identity of FROG; LLVM remains one backend producer of native artifacts.

README Expectations

An example README should identify:

  • the example title and numbered directory;
  • the single primary behavior or concept under test;
  • the source artifact path, normally starting at main.frog;
  • the public artifact chain for executable examples: .frog -> FIR -> lowering -> LLVM IR -> native artifact + manifest -> runtime host;
  • front-panel packages and Default realization assets when widgets are involved;
  • the stated validation level, without claiming broader runtime or compiler completeness than the example proves;
  • known limits, especially when the example is post-boundary public material whose runtime implementation continues privately.

The README should be useful to a reader who has not seen the chat that created the example. It should explain what changed, what is reused, and what evidence the directory provides.

Ownership Boundaries

Examples must preserve the public FROG ownership model:

  • .frog owns diagram logic, source identity, front-panel instances, widget layout, bindings, initial values, labels, and instance-level visual overrides.
  • .wfrog owns realization package references, Default asset references, supported classes, and host capability declarations.
  • Default realization assets own reusable widget visual grammar, SVG templates, public parts, anchors, bindings, internal geometry, and default visual behavior.
  • Runtime or host material consumes the published artifacts; it does not become the semantic definition of the example.

For non-widget examples, the same principle applies: the example should show the source truth, the public derived artifacts, and the handoff boundary instead of hiding meaning inside an implementation-specific shortcut.

For widget examples, visible borders are part of the inspectable realization contract. Any border, frame, outline, selection rectangle, cell boundary, scrollbar track, or equivalent stroke-like surface should keep one uniform thickness on every side after resize unless the widget class deliberately publishes side-specific border properties. The width, color, visibility, and style of such surfaces should be source-owned or realization-published, not hardcoded by the runtime host.

Browser-Hosted Examples

When an example is launched through a browser host for validation, the page should make the example inspectable without treating the browser as the FROG runtime identity.

The browser-hosted surface should expose:

  • the example title and validation badges;
  • the visible front panel or equivalent review surface;
  • an explicit Execute action when the example requires running the diagram or manifest-backed contract;
  • Read only when the example specifically validates program-read semantics;
  • a collapsed-by-default source and execution artifact inspector with formatted readable content and raw routes for state.json, the owning .frog, directly consumed .wfrog packages, and FIR/lowering artifacts when present.

Widget edits are front-panel state changes. They should not silently execute the diagram unless the example explicitly defines that interaction as the execution event.

Example Families

The same dossier pattern applies beyond widget work:

Example family What it should emphasize
Widget examples Source-owned instances, .wfrog realization references, Default SVG assets, public parts, bindings, and visible behavior.
Operator examples Source operator identity, type/value behavior, FIR preservation, lowering behavior, and backend/runtime evidence where in scope.
Structure examples Explicit structure boundaries, regions, terminals, state participation, and preservation across FIR/lowering.
Library examples Explicit frog.xxx function identity, provider or dependency boundary, manifest declaration, and dataflow-visible inputs/outputs.
Compiler/conformance examples Positive and negative cases, expected diagnostics, accepted/rejected source patterns, and artifact preservation claims.

Acceptance Posture

An example is complete at the level it honestly proves. It may be a public specification-facing example, a bounded public reference runtime example, a compiler corridor example, a widget progression example, or a future conformance case. The README and artifacts should state that posture precisely.

For the current repository boundary, Examples 01 through 15 define the public reference runtime closure. Examples after that boundary may remain public as source, specification, widget, library, conformance, or design-progression material while Graiphic runtime implementation continues privately unless a later public reference surface is explicitly promoted.