Definition of image-backed IDE snippet artifacts for FROG authoring workflows
FROG — Free Open Graphical Language
- 1. Overview
- 2. Scope for v0.1
- 3. Architectural Position and Dependencies
- 4. Design Principles
- 5. What a Snippet Is
- 6. Snippet vs Full FROG
- 7. Snippet Kinds
- 8. Selection Scope Model
- 9. Diagram Snippet Content
- 10. Front Panel Snippet Content
- 11. Composite Snippets
- 12. Image-Backed Snippet Model
- 13. Embedded Payload Model
- 14. Boundary Endpoints and Open Connections
- 15. Reference Closure and Dependencies
- 16. Preview and Presentation
- 17. Export Semantics
- 18. Import, Paste, and Drag-and-Drop Semantics
- 19. Validation and Safety Rules
- 20. Illustrative Examples
- 21. Out of Scope for v0.1
- 22. Summary
- 23. License
This document defines the snippet model of a FROG IDE. A snippet is a portable, image-backed IDE artifact that captures a reusable fragment of authoring content so that it may be:
- copied,
- shared,
- previewed as an ordinary image,
- dragged into a FROG IDE,
- or inserted into another editing context.
A snippet is not a full FROG program. It is a source-aligned fragment of IDE-managed content derived from the FROG Program Model and packaged inside an image carrier that remains visually meaningful outside the IDE.
The core intent of a FROG snippet is therefore dual:
- human-visible artifact — the snippet is viewable as an image in generic tools, file browsers, documentation, chat systems, and websites,
- IDE-readable artifact — the same image contains structured embedded snippet payload data that a conforming FROG IDE can decode and insert through import, paste, or drag-and-drop.
This gives FROG a snippet workflow intentionally aligned with image-backed graphical-language reuse: a user can see the snippet as an image everywhere, while a conforming FROG IDE can recover the actual structured reusable content from it.
Snippet model
authoring fragment
-> structured snippet payload
-> image-backed carrier
-> human preview outside IDE
-> structured recovery inside IDE
Never:
snippet image
-> pixel interpretation only
-> guessed semantics
For FROG v0.1, this document standardizes:
- what a snippet is,
- which kinds of authoring fragments may be captured,
- how snippet boundaries are represented,
- how references and required supporting objects are carried,
- that a standalone snippet artifact MUST be image-backed,
- that the image carrier MUST contain structured embedded snippet payload data readable by a conforming FROG IDE,
- how import, paste, and drag-and-drop SHOULD behave at the source-model level,
- how optional non-authoritative recoverability metadata MAY accompany carried content.
FROG v0.1 does not standardize:
- a mandatory clipboard MIME type,
- a mandatory operating-system drag-and-drop protocol,
- a mandatory online marketplace or package manager for snippet libraries,
- execution directly from a snippet,
- automatic semantic repair of invalid pasted fragments beyond defined validation rules,
- one universal binary embedding mechanism that every image technology must share.
Base v0.1 standardizes the image-backed requirement and the logical embedded payload model. Stricter transport conventions MAY later freeze exact carrier encodings, chunk conventions, metadata slots, integrity metadata, or file-extension rules.
This document belongs in IDE/ because it defines snippet capture, transport, preview, paste,
drag-and-drop, and reinsertion behavior as IDE authoring workflows.
It does not belong to Expression/ because it does not define the canonical persisted form of a full FROG source unit.
This document complements the following specifications:
IDE/Readme.md— defines the role of the Program Model and the distinction between IDE artifacts and canonical source,IDE/Palette.md— defines the active canonical insertable space into which carried snippet content is reinserted,IDE/Express.md— defines Express authoring, canonical target identity, and IDE-side recoverability expectations for guided authoring,Expression/Readme.md— defines the canonical source model and the optional source-levelidesection,Expression/IDE preferences.md— defines IDE-facing preferences and recoverability metadata carried in the optional source-levelidesection,Expression/Diagram.md— defines executable graph objects, layout metadata, annotations, and diagram-scope dependency references,Expression/Control structures.md— defines structure nodes, owned regions, and the whole-structure representation that snippet capture must preserve when structures are selected,Expression/Front panel.md— defines front-panel composition and widget-tree structure,Expression/Widget.md— defines widget identity and widget object structure,Expression/Widget interaction.md— defines the source-facing representation ofwidget_value,widget_reference, and object-style widget interaction,Libraries/UI.md— defines the standardizedfrog.ui.*primitive identities and primitive-local behavior used by widget-related diagram content,Profiles/Readme.md— defines the architectural role of optional standardized capability families that may surface in transported snippet content.
This document does not redefine the canonical .frog source format.
It defines how the IDE may serialize, embed, transport, preview, and reinsert fragments of source-aligned authoring content through an image-backed snippet artifact.
Accordingly:
Expression/remains authoritative for the carried source-level object model,Libraries/remains authoritative for intrinsic primitive identity and primitive-local behavior,Profiles/remains authoritative for optional profile-defined capability families,IDE/Palette.mdremains authoritative for the canonical insertable space of the target editor,IDE/Snippet.mdremains authoritative only for snippet transport, preview, embedding, and reinsertion behavior.
Ownership reminder
Expression/ -> carried source-level object model
Libraries/ -> intrinsic primitive identity
Profiles/ -> optional capability families
IDE/Palette -> target insertable space
IDE/Snippet -> snippet transport and reinsertion behavior
A snippet belongs to the IDE and authoring-workflow layer. It is not the canonical persisted form of a full FROG program.
Although snippets are IDE artifacts, their embedded contents MUST remain expressible in terms of source-level objects already defined elsewhere, such as:
- diagram nodes and edges,
- diagram annotations,
- structure-owned regions when a structure is carried,
- front-panel widgets,
- layout metadata,
- documentation metadata.
A standalone snippet artifact MUST be an image that:
- can be rendered by generic image-capable tools, and
- contains embedded structured snippet payload data readable by a conforming FROG IDE.
The visible image is essential for human workflow and browsing, but the IDE-authoritative meaning of a snippet is defined by its embedded structured payload, not by pixel interpretation alone.
A snippet MUST carry enough information for a target IDE to either:
- insert it deterministically,
- or reject it deterministically with an explicit reason.
A snippet MUST NOT introduce ad hoc execution semantics that do not already exist in the FROG language or Program Model. It transports content; it does not redefine the language.
A snippet MUST reinsert canonical content into the target Program Model. It is a transport path into the same canonical insertable space, not a competing insertion language.
A snippet MAY carry non-authoritative recoverability metadata related to Express-authored instances or other guided authoring flows. However:
- such metadata MUST remain optional,
- such metadata MUST remain non-authoritative for execution semantics,
- loss of such metadata MUST NOT invalidate the carried canonical snippet content.
A snippet MAY carry intrinsic, profile-defined, or other implementation-supported content. Transporting that content does not imply that every target IDE supports it. Import validation remains responsible for checking whether required capabilities are actually available.
FROG v0.1 defines a minimal snippet core. Future transport conventions MAY define richer carrier encodings, previews, galleries, library conventions, signing models, or cross-tool interchange standards.
A snippet is a serialized authoring fragment captured from one editing context so that it may be inserted into another editing context through an image-backed transport artifact.
Conceptually, a snippet contains:
- a snippet kind,
- a payload containing source-aligned fragment content,
- boundary information for open connections or incomplete surroundings,
- presentation metadata used to render the snippet as an image,
- optional non-authoritative recoverability metadata,
- an image carrier that embeds the structured snippet payload.
A snippet is usually derived from a user selection, but the exact UI gesture used to create that selection is outside the scope of this document.
A full FROG program is a complete source-level unit described by the canonical FROG Expression. A snippet is only a fragment.
Therefore, a snippet:
- MAY be incomplete relative to a full program,
- MAY have open boundaries,
- MAY omit unrelated program sections,
- MAY carry non-authoritative recoverability metadata,
- MUST NOT be treated as a complete executable FROG unless a future convention explicitly wraps it into a complete FROG.
A snippet is not a substitute for:
- a reusable library FROG,
- a dependency package,
- a canonical source file,
- an execution artifact.
The canonical snippet kinds for FROG v0.1 are:
diagram_snippet— a fragment of one diagram scope,front_panel_snippet— a fragment of a front-panel widget tree,composite_snippet— a snippet carrying both diagram and front-panel content when they are semantically linked.
A diagram_snippet is the primary snippet kind for v0.1.
A v0.1 snippet payload MUST be rooted in exactly one source scope for each carried content family. For example:
- a diagram snippet is rooted in one diagram scope,
- a front-panel snippet is rooted in one widget-tree scope.
A single diagram_snippet payload MUST NOT directly mix executable objects taken from multiple diagram scopes.
For example, it MUST NOT combine objects from both:
- a parent diagram scope, and
- a nested structure-region scope
inside one flat diagram payload.
If a selection includes a structure node as a selected object, the snippet MUST carry that structure node together with its owned regions and their source-aligned content.
A future stricter convention MAY allow creating a snippet from content inside one structure-owned region without selecting the containing structure itself. In that case, the snippet root is that region-local diagram scope rather than the parent scope.
A diagram_snippet MAY contain:
- selected nodes,
- selected internal edges between those nodes,
- selected annotations,
- node-local documentation fields,
- node tags,
- layout metadata relevant to pasted placement,
- snippet-local dependency references needed by selected
subfrognodes, - optional non-authoritative recoverability metadata relevant to guided authoring reconstruction.
A diagram snippet MUST preserve source-level node kinds and kind-specific fields. It MUST NOT rewrite a selected node into a different node kind merely for snippet transport.
An edge is internal to the snippet if both its source endpoint and destination endpoint are carried by the snippet payload. Internal edges SHOULD be carried directly as ordinary snippet-owned edges.
An edge that crosses the snippet selection boundary is not fully internal. Such a crossing MUST be represented through snippet boundary endpoints as defined later in this document.
A front_panel_snippet MAY contain:
- one or more widget instances,
- widget subtrees,
- layout and composition metadata,
- styling metadata,
- widget-local configuration,
- optional non-authoritative recoverability metadata relevant to guided authoring reconstruction.
For v0.1, a front-panel snippet SHOULD preserve widget-tree structure rather than flattening it into unrelated widgets. If a selected widget has selected descendants, their parent-child relationship MUST remain preserved.
A snippet MUST NOT silently break a widget subtree in a way that makes the resulting payload structurally ambiguous. An IDE MAY therefore require subtree closure for certain widget selections.
A front-panel snippet MUST preserve widget instances using the canonical widget-instance field model defined by the front-panel and widget specifications rather than inventing a snippet-specific widget object shape.
A composite_snippet carries both:
- a diagram fragment, and
- a related front-panel fragment.
This is especially useful when the diagram fragment contains:
widget_valuenodes,widget_referencenodes,frog.ui.*widget-interaction primitives whose meaning depends on referenced widgets.
If a snippet carries widget-related diagram nodes and is intended to be portable across documents, it SHOULD include the required referenced widget definitions in a front-panel fragment rather than assuming they already exist in the target FROG.
When a composite snippet carries both diagram and front-panel content, all internal widget references between those carried content families MUST remain resolvable inside the snippet payload.
If a composite snippet also carries recoverability metadata, that metadata MUST remain subordinate to the carried canonical diagram and front-panel content.
A standalone FROG snippet artifact MUST be image-backed. The image carrier is not optional in the base standalone workflow.
The snippet image carrier MUST satisfy both of the following:
- generic visibility — it MUST be displayable as an image outside the FROG IDE,
- structured recoverability — it MUST contain embedded snippet payload data that a conforming FROG IDE can recover without relying on manual visual interpretation.
The embedded structured payload is authoritative for import, drag-and-drop insertion, validation, and reconstruction. The rendered image is authoritative for visual presentation only.
The image carrier exists so that a snippet can be:
- dropped into chats, emails, wikis, presentations, and documents as an image,
- browsed visually in folders and asset collections,
- dragged from a generic image-aware environment into a FROG IDE,
- decoded by the IDE into structured reusable authoring content.
Base v0.1 requires an image-backed carrier but does not require one unique binary embedding technique across all environments. A stricter transport convention MAY freeze:
- the exact raster format,
- the exact file extension convention,
- the exact metadata or chunk location for embedded payloads,
- signature or integrity metadata.
The embedded payload of a snippet image is conceptually:
{
"kind": "frog_snippet",
"version": "0.1",
"snippet_kind": "diagram_snippet | front_panel_snippet | composite_snippet",
"diagram_fragment": { },
"front_panel_fragment": { },
"boundaries": { },
"dependencies": { },
"preview": { },
"metadata": { },
"recoverability": { },
"provenance": { }
}kindMUST be"frog_snippet",versionMUST identify the snippet-format version,snippet_kindMUST identify the snippet category,diagram_fragmentMUST be present fordiagram_snippetandcomposite_snippet,front_panel_fragmentMUST be present forfront_panel_snippetandcomposite_snippet.
Auxiliary sections such as preview, metadata, and recoverability MAY be present provided that they remain non-authoritative with respect to source-aligned snippet meaning.
A snippet payload MAY also carry provenance evidence when the relationship between the original source objects and the transported fragment remains clear. During insertion, the IDE SHOULD either preserve valid provenance with explicit imported context, mark the inserted objects as snippet_inserted or imported, or require a fresh human-review attestation after the fragment is placed in the target program.
A conforming standalone snippet image MUST embed a recoverable payload equivalent in information content to the logical model above. An image that merely resembles a snippet visually but lacks recoverable structured payload is not a valid standalone FROG snippet artifact.
The rendered image MAY be regenerated from the payload. The payload MUST NOT be reconstructed by lossy visual analysis of the rendered image.
If an embedded snippet payload carries recoverability metadata:
- that metadata MUST remain optional,
- that metadata MUST remain non-authoritative for canonical meaning,
- its absence or loss MUST NOT invalidate the carried canonical snippet content,
- it SHOULD help a conforming IDE reopen or preserve guided authoring presentation only when that is safely possible.
A snippet is often created from a larger graph fragment that was connected to surrounding content. Those external relationships must be represented without pretending that the snippet is a full closed diagram.
FROG v0.1 defines conceptual snippet boundary endpoints:
snippet_input— a value or sequencing dependency expected from outside the snippet,snippet_output— a value or sequencing dependency produced by the snippet for use outside the snippet.
These are snippet-level transport concepts, not canonical node kinds of the FROG source language. They exist only inside the snippet payload model.
A snippet boundary endpoint represents an open connection between the carried fragment and content that was not included in the snippet. When the snippet is imported or dropped, the IDE MAY:
- leave the corresponding boundary as an unwired open endpoint,
- offer reconnection assistance,
- or map it to a suitable target connection if the insertion operation explicitly defines one.
When type information is resolvable from the source fragment, a snippet boundary endpoint SHOULD carry that type information so that insertion validation can remain deterministic.
A snippet SHOULD carry the minimum supporting information needed to remain meaningful after transport.
Primitive nodes are carried by their canonical type identifiers such as frog.core.add or frog.ui.property_read.
A snippet does not inline primitive-library definitions.
If a snippet contains subfrog nodes, it SHOULD carry the relevant dependency references needed to keep those subfrog.ref identifiers meaningful at insertion time.
A snippet does not inline the full referenced dependent FROGs.
If a snippet contains profile-defined entries, it SHOULD carry enough capability-identification information to allow the target IDE to validate whether the required profile support is available. A snippet does not convert optional profile-defined content into unconditional core content.
If a snippet contains widget_value or widget_reference nodes and is intended to remain portable across documents,
it SHOULD carry the required widget definitions through a front-panel fragment or equivalent widget payload.
If a composite snippet carries both diagram-side widget references and front-panel widget definitions, those internal references MUST remain consistent after identifier regeneration and insertion.
A snippet SHOULD NOT capture unrelated surrounding program content merely to avoid open boundaries. Closure should be minimal and semantically relevant.
A snippet MAY carry recoverability metadata that helps preserve or restore the relationship between a carried fragment and an Express-authored presentation. Such metadata MUST NOT replace the requirement to carry the actual canonical content needed for insertion.
Because the snippet itself is image-backed, preview is not an optional afterthought. The visible image is a first-class workflow surface of the snippet artifact.
The rendered snippet image SHOULD make the snippet identifiable to a human viewer. Depending on snippet kind, this MAY include:
- a diagram thumbnail or cropped fragment view,
- a front-panel thumbnail,
- a composite preview of diagram and front panel,
- a compact title or label,
- lightweight visual hints for open boundaries.
The rendered image SHOULD be visually useful and SHOULD correspond to the embedded payload. However, if any conflict exists between the visible rendering and the embedded payload, the embedded payload remains authoritative.
A conforming IDE MUST NOT require OCR, image understanding, or manual tracing to recover snippet meaning from a valid snippet image. The structured embedded payload is mandatory precisely to avoid that ambiguity.
When an IDE exports a snippet, it MUST:
- capture the selected source-aligned fragment,
- normalize it into one of the canonical snippet kinds,
- compute boundary endpoints for cut external connections,
- attach minimal required dependencies,
- generate a human-visible rendered image,
- embed the structured snippet payload into that image-backed carrier.
If the exported selection also contains optional recoverability state, the IDE MAY embed corresponding non-authoritative recoverability metadata in the snippet payload.
The visible rendering SHOULD remain stable enough that repeated exports of the same snippet produce recognizably similar images, subject to convention-defined rendering policies.
An IDE MUST NOT export an image as a valid snippet artifact if:
- the structured payload is missing,
- the payload is incomplete for the chosen snippet kind,
- required dependencies are intentionally omitted in a way that makes deterministic import impossible.
A conforming FROG IDE SHOULD treat a dropped or imported image as a candidate snippet artifact when the environment supplies an image object or file.
On snippet import, paste, or drag-and-drop, the IDE MUST first attempt to decode embedded structured snippet payload from the image-backed carrier.
If decoding succeeds and validation succeeds, the IDE SHOULD proceed with snippet insertion semantics. If decoding fails, the IDE MUST NOT pretend that the image is a valid snippet. It MAY instead:
- reject the operation,
- treat the dropped object as an ordinary image asset if the editor context supports that,
- report that the image is viewable but not a valid FROG snippet.
When inserting a valid snippet payload, the IDE SHOULD:
- reinsert canonical carried content into the target Program Model,
- regenerate local identifiers as required to avoid collisions,
- preserve internal connectivity and internal ownership relationships,
- preserve internal cross-references between carried content families,
- preserve carried layout relationships as far as practical,
- leave external boundaries open unless the insertion operation provides an explicit reconnection rule,
- preserve semantic distinction between diagram content, front-panel content, dependencies, and non-authoritative recoverability metadata.
If optional recoverability metadata is present, the IDE MAY use it to restore or preserve guided authoring presentation. If such metadata is absent, ignored, or cannot safely be applied, the IDE MUST still insert the canonical carried content deterministically when the canonical content itself is valid.
Snippet insertion MUST still validate against the target scope and active insertable space. A snippet may carry valid source-aligned content and still be rejected if the target editing context does not support the required canonical target family or required optional profile support.
Snippet insertion MUST NOT silently turn copied or imported provenance into a fresh human_direct claim. A direct human drag-and-drop action is evidence about the insertion action; it is not automatically evidence that the carried canonical objects were originally authored manually.
A drag-and-drop workflow using a snippet image SHOULD be semantically equivalent to explicit snippet import from the same carrier. The gesture differs; the recovered payload meaning does not.
If a clipboard operation carries an image-backed snippet artifact or equivalent embedded-payload image data, the IDE SHOULD decode and treat it using the same rules as file import or drag-and-drop.
A snippet payload MUST be rejected if any of the following is true:
- the image carrier does not contain recoverable embedded payload data,
- the payload kind is missing or invalid,
- required fragment sections are missing for the declared snippet kind,
- internal references are inconsistent,
- the payload violates source-level invariants of the carried content family,
- the payload depends on unsupported required profile-defined capabilities in the target IDE.
Optional non-authoritative recoverability metadata MUST NOT by itself determine whether the canonical carried content is valid. It MAY be ignored, warned about, or dropped without invalidating an otherwise valid snippet payload.
A target IDE SHOULD additionally warn when:
- the snippet is valid but requires external dependencies that are unavailable,
- the snippet is valid but references profile-defined capabilities that are not supported in the current environment,
- the snippet is structurally valid but contains unresolved boundary endpoints,
- the visible image appears stale relative to regenerated preview expectations,
- optional recoverability metadata is present but cannot be safely applied,
- the snippet was produced by a newer incompatible snippet-transport revision.
A snippet image MUST NOT be trusted merely because it looks correct visually. Validation MUST be performed on the embedded structured payload.
{
"kind": "frog_snippet",
"version": "0.1",
"snippet_kind": "diagram_snippet",
"diagram_fragment": {
"nodes": [
{ "id": "add_1", "kind": "primitive", "type": "frog.core.add" }
],
"edges": []
},
"boundaries": {
"inputs": [
{ "id": "b_in_1", "kind": "snippet_input", "type": "f64" }
],
"outputs": [
{ "id": "b_out_1", "kind": "snippet_output", "type": "f64" }
]
},
"metadata": {
"title": "Adder fragment"
}
}{
"kind": "frog_snippet",
"version": "0.1",
"snippet_kind": "composite_snippet",
"diagram_fragment": {
"nodes": [
{ "id": "widget_temp", "kind": "widget_value", "widget": "temperature_numeric" }
],
"edges": []
},
"front_panel_fragment": {
"widgets": [
{
"id": "temperature_numeric",
"role": "indicator",
"widget": "frog.ui.standard.numeric_indicator",
"value_type": "f64",
"props": {
"label": "Temperature"
},
"children": []
}
]
},
"boundaries": {
"inputs": [],
"outputs": []
},
"metadata": {
"title": "Temperature indicator snippet"
}
}{
"kind": "frog_snippet",
"version": "0.1",
"snippet_kind": "diagram_snippet",
"diagram_fragment": {
"nodes": [
{ "id": "read_text_1", "kind": "subfrog", "ref": "frog.io.read_text_file.basic" }
],
"edges": []
},
"dependencies": {
"diagram_dependencies": [
{
"name": "frog.io.read_text_file.basic",
"path": "lib/io/read_text_file/basic.frog"
}
]
},
"recoverability": {
"express_bindings": [
{
"instance_id": "expr_001",
"express_id": "frog.ide.express.read_text_file",
"canonical_target_kind": "subfrog",
"canonical_target_ref": "frog.io.read_text_file.basic",
"visible_optional_terminals": ["error_in", "error_out"],
"config": {
"encoding": "utf8"
}
}
]
}
}
In this example, the carried canonical content remains the authoritative snippet meaning.
The recoverability section is optional and non-authoritative.
+---------------------------------------------+
| visible snippet image |
| - diagram or panel preview |
| - optional title or label |
| - optional boundary hints |
+---------------------------------------------+
| embedded structured payload |
| kind = frog_snippet |
| version = 0.1 |
| snippet_kind = diagram/front_panel/... |
| source-aligned fragment content |
| optional non-authoritative recoverability |
+---------------------------------------------+user drags snippet image into FROG IDE
|
v
IDE detects image-backed candidate artifact
|
v
IDE decodes embedded structured snippet payload
|
+-----+-----+
| |
v v
success failure
| |
v v
validate reject as snippet
|
v
insert fragment deterministically- automatic semantic adaptation across incompatible language or profile environments,
- execution directly from snippet images,
- a mandatory cross-platform clipboard MIME registry,
- a mandatory OS-level drag-and-drop binary protocol,
- online snippet marketplaces,
- cryptographic signing requirements for snippet images,
- pixel-only recovery of snippet semantics without embedded structured payload,
- making optional recoverability metadata required for valid snippet insertion.
A FROG snippet is an IDE-layer reusable fragment artifact, but unlike an ordinary detached fragment file, it is intentionally defined as an image-backed snippet carrier.
- it is viewable as an ordinary image outside the IDE,
- it contains embedded structured snippet payload data,
- a conforming FROG IDE can recover that payload during import, paste, or drag-and-drop,
- the embedded payload is authoritative for snippet meaning,
- the visible image is authoritative for presentation only,
- optional recoverability metadata MAY be transported but MUST remain non-authoritative,
- reinsertion targets canonical carried content rather than a separate snippet-specific language,
- the snippet remains a fragment, not a full canonical
.frogprogram.
This gives FROG a modern, portable, and visually shareable snippet model that preserves the usability advantage of image-based graphical-language reuse while remaining structurally rigorous.
This specification is part of the FROG repository and is governed by the repository license and contribution rules.