Skip to content

Latest commit

 

History

History
714 lines (637 loc) · 45.5 KB

model.md

File metadata and controls

714 lines (637 loc) · 45.5 KB

Data and editor model

Earlier models and unverified rationale are preserved in historical notes. Open work is listed separately in deferred work.

Data and resolution

GID defines Value as cell references, blobs, lists, and records. A document has an optional root and a CellId -> Value table. An identity with no table entry is a bare cell. Record labels are cell identities; text, names, numbers, absence reasons, and domain data are library conventions.

A record's kind is one of those conventions: its isa field, whose cell the isa library owns, names what kind of thing it is, as {isa: call} does. Typing stays structural, a kind's other fields read by what they are; the kind says only what the record is, never what it requires, so a record stays its kind while it's unfinished and whatever its kind comes to require. A kind is a cell of its own, apart from any field that shares its name: the call kind will carry the type of calls, an absent's call field the type of what it holds. Grap's calls, lambdas, closures, foreign functions, value wrappers, unquotes, match cases, bindings, binders and absents say their kinds, as the Grap library's evaluations and notebooks do, and a record that doesn't is data. A value encoded under one tag field, a number, text or a boolean, is told by that field.

A cell may accidentally occur in several sources, for example when editing a document that also exists as a loaded library. Normal lookup selects the document definition first, otherwise the first loaded library definition. Names, structural display, and cell evaluation use that value. Definitions are neither merged nor implicitly composed. Duplicate indicators and inspection UI are deferred.

Each library has one value per cell, and the Rust code of the foreign functions it implements, each under its own cell. Reads and calls use the same lookup. A foreign function's value says what it is, {isa: foreign function, implementation: <its own cell>, name, params}, the library writing it from the function's name and the parameters its code declares. It's data, so a reference evaluates to it as to any definition. Only a call reaches code (grap::Host::implementation): calling a cell whose definition is a foreign function implemented under it runs the code there, and calling a foreign function value calls its implementation's cell. A document that defines that cell otherwise overrides the code too, since the call reads the definition first; one implemented nowhere isn't callable. An absent or non-callable result does not try another source. A library's own value lives in that same table under its identity, not in a separate metadata store: {isa: loaded library, name, cells}, the name it gives itself and the cells it defines, ordered by their names. Composing the loaded libraries writes it, so it lists what each library ends up defining; the editor library draws it as its name over a column of its cells, each by its name. Replacing a loaded library replaces all its contributions in place, including projections and completions, before those are composed. Paths, locations and evaluation all go through that lookup, so a path reaches whichever definition it selects; loaded library values remain read-only. See Sources, Library and Libraries, and Grap evaluation.

Documents are saved and loaded through the text bridge.

Occurrences, definitions, and views

A Path is a sequence of GID steps interpreted in a supplied document and library context:

  • Key(cell) enters a record field.
  • Element(position) enters a list element at its stable position.
  • Follow crosses a cell into its definition, the one lookup selects.

The empty path is the document root; it need not be a cell. Loading a library, reordering libraries, or adding a document definition can change which definition a Follow reaches, as other edits can leave a path stale; the editor tolerates both. List positions preserve an occurrence across edits that retain that position; they are not content identities or globally meaningful addresses.

A Location names stored data: it starts at the document's root or at a cell's definition, then follows a path from there. Following a cell starts a new location at its definition, however the cell was reached, so what can be edited depends on where the data is stored, not on the route to it. Writes land in that stored value: a location's last Follow enters the definition it is in, or else its own start names it. The root and the document's own definitions are writable, including a cell with no definition yet; a library's definitions are read-only. A route through a cell and a location starting at that cell are the same location.

Where something is drawn has two tiers. The first is the view it's in, a View the editor lays out: the document's, or one it opened beside it (panes). A view is the editor's, not GID data, and it's known by its address, an Rc<View>, so two views of one place are two views. The second tier is the occurrence path within the view, unchanged from what the view alone would draw. A selection, a landmark, hover and computations carry the view beside the path, so two views drawing the same stored data at the same path keep separate focus, scroll, folds and results. Where a view's root value is a row or column, each part is drawn in its own area of the view, an Area naming the view and the part's path below its root; which area a path is in follows from the path, the part whose path leads it.

SourceTrace serves source-linked widgets, drawing, and highlighting. It is a location in the form it is stored in: a path from the root, or a cell and a path relative to its definition. Normalizing to the nearest followed definition lets different occurrences highlight the same source. Both forms still need the caller's lookup context. Neither is an execution stack or global address.

Computed values use at at their own displayed occurrences. They and their children can be selected, copied, and folded, but have no document destination for edits. Selecting a result does not select its producing expression. A cell inside a result is still a cell, though, as in a missing-cell error or a quote's template: following it starts a location at its definition, which edits on the usual terms. So the missing-cell error a pane shows for a Grap starting point's unwritten program is a place to write it. Values copied out of cells stay read-only; reaching the code that made one is source-linked hover's job. Computed output uses the same read-only ground as external definitions. Nested read-only occurrences do not stack washes; an explicit jump to writable source restores the paper ground. This decoration does not change edit permissions: those still follow the occurrence's source. A reference to an external definition can itself still be replaced or removed from a writable document.

Selection and editing

Selection owns its workspace view, a path within it, a GID payload, and an optional Rust editor. Its stages distinguish an existing edge, a pending value, and a pending record label. Annotation records live in an Annotations tree owned by the view, a node per path step, so a projection carries the node for where it draws and reaches a child's by its one step; folding is one convention in those records. A projection folds what it draws by consulting that state through display::fold, and decides how it starts: Raw's cells, lists and records fold, as do Grap's calls and the control forms. Space folds and unfolds the selected occurrence where its projection folds. Clicking a fold's … selects the occurrence as it opens it, so Space closes it again.

Raw's lists and records start open. A cell starts closed where drawing it would draw its value again inside itself, a cycle, and where it sits inside another cell's value and holds cells itself, since opening it could open more in turn. The cells a view reaches directly open, so their projections get going, and so do cells holding no cells, which can't cascade. A cell whose whole value is another cell opens through to it.

An occurrence path says where its data is, so a selection, a site and a landmark are each a path in a view, with no location beside it. As projection builds them, paths are trails: each occurrence holds its own step and a link to the trail of the occurrence it's drawn inside, so descending adds one link, siblings share what's above them, and what wants the whole path walks the parents. A selection, made rarely, holds its path whole. Its steps are the document's own, Key, Element and Follow, plus two of the editor's: a jump restarts the path at a location, as a projection's jump does, and a computed step stops it, as at does for a supplied value. Which view the path is in sits beside it, not in it. Resolving a path starts from the document's root, or from its last jump's location, and follows the data steps after it; past a computed step there's no location until a jump. A cell followed inside a computed value has no stored route to it, so following it jumps to its definition, which starts a location again. Reads and writes resolve the same way; there is no independently configurable read/write pair or inverse mapping. Several occurrences may resolve to one source. Selection, navigation, and annotations stay occurrence-local, while source-linked hover uses the location. Line editing, gestures, completion insertion, structural paste/deletion, and history all act on the path, and undo restores the selected path, which carries its own interpretation. Occurrence steps are the editor's, not GID's: document paths never contain a jump, and no jump can be mistaken for a field. If a projection changes what a selected occurrence means, its caller is responsible for clearing the selection when necessary; the editor does not try to repair arbitrary changes of interpretation.

descend extends the current occurrence, jump gives a new occurrence an actual document source, and at projects a supplied value without a source, beneath a computed step. None means no document location, not a missing value: Some(location) can name an absent field and still offer editing. A library source is present but read-only. Ordinary descendants of at stay detached until they follow a cell, which starts a location at its definition; an explicit jump can also establish a source again. Outline list entries project their referenced fields through jumps: the heading is the real list element, and its body has an occurrence beneath that element. Repeating a field yields independent folds and selection locations while both bodies edit the same source field.

Copy and fold do not resolve an occurrence's location. The shared projection boundary installs handlers that copy the displayed Value, and a folding projection changes the occurrence's fold annotation using the default it determined. This also works for source-less at values. Inner widget handlers take precedence (for example, copying a text selection). Structural cut copies that same value, then attempts deletion where the selection's path says its data is; a source-less value can be copied but not deleted.

On macOS and Linux a structural copy also puts a PNG picture of the copied occurrence on the system clipboard, after the private format and before the plain text, so apps that take images paste what was drawn. Once the key is handled, the shell builds the window's frame again with nothing selected and no pointer over it, composites it offscreen on the window's GPU, and crops it to the occurrence's landmark, at the window's scale and only as far as it's in view; see picture.rs. A cut carries no picture, since its occurrence is gone by then.

Ordinary selection does not initialize editing state. Its role is derived from the current location: a writable missing value uses the pending picker, while an existing value is selected normally. An explicit pending or label payload can still request those modes intentionally, but no caller needs one as setup. The picker renders an empty query by default without writing selection state and materializes its editor only on input; query, caret, choice, and scroll state are optional. This applies to empty roots, bare-cell definitions, missing record fields, and inserted list positions, without a special selection callback for each. Read-only locations do not enter a picker.

Enter beside a selected value adds a peer: an element after it in a list, or a field on the record holding it. Cmd+Enter adds something within it: a field on a record, an element appended to a list, or a bare cell's first value. Both belong to the view of the container they land in, which offers them through structure::authoring; its children's handlers run first. The structural record, list and cell views offer it. Grap's calls don't, since their arguments are their parameters, shown as slots when missing; nor does a view that draws a value as one piece, such as a number, text, a color, an infix expression or a tutorial's slots, so Enter there adds nothing. While typing in a value, Enter only ends the typing, since the value is already written; the text re-spells from it, so a half-typed 6e goes back to 6. A key a line editor doesn't take never starts its typing.

Deleting a selected value keeps its place selected as a hole, so the next keystrokes write its replacement; Backspace or Delete on the hole's empty query removes it, Backspace landing on the sibling before it, else on its container, and Delete on the stop after it, even past its container's end. Typing over a selected value opens a picker in its place seeded with what was typed: an explicit pending payload over the existing value, which projection draws as missing until a choice commits, so the document is untouched until then. Where Grap is shown, one of a number type's single-character operators typed at the end of a selected number instead makes the number that operator's left operand and opens the right operand's picker; a sign or exponent the number is still becoming stays in its text. A picker opened from a key remembers where it was opened, and Escape, or an empty query's Backspace or Delete, steps back there. Views that draw a record as one value (numbers, text, colors) follow it with a record of its other fields, as a call follows its head with its arguments. No key adds a field to them there; a rawer view, where the value reads as the record it is, can.

The live LineEditState owns text, caret, IME, and text-drag state. A projection at the selected location receives a GID description derived from that state. A capability replacement decodes it once into the live editor; there is no second retained editor representation to synchronize. Paths reach Grap as ordinary GID data.

Generic Grap handlers receive GID events and caller-supplied capabilities. Site and selection access are scoped foreign calls. site path returns the site's occurrence path in its view; selection get reads the selection payload there. selection set takes an explicit path and value, interpreted in the supplied document and view, so it can move selection to another location. An absent value clears selection only at the specified path. Reads observe staged writes; an explicitly declined or halted handler commits no effects. Ordinary absent results keep preceding effects. Setters return {} on successful set or clear; absent remains an input convention for clearing, not its return value. Site and selection getters return their own missing-state reasons when empty. Only the complete editor operation is staged, with no per-call snapshots or rollback. Tests can replace these foreign functions with a recording interpreter.

The projection supplies a line's spelling, presentation, and conversion callback. The current line editor's handler owns the callback; selection retains neither a Rust callback nor a Grap callable. The line editor, display::line_edit, is the stock native widget function carried by Layout::widget; layout has no line-editor constructor or interpreter arm. The editor supplies current state and scoped editing capabilities, then incorporates the widget's render closures, handlers, hover claim, and navigation transition. Progred's line edit runs an editing operation, then converts only when the accepted operation changed the text. The callback receives the live value and spelling; None declines a write. An equal result does not rewrite the document. Invalid intermediate text can remain in the editor while the last valid value remains in the document. Loaded library values decline writes. Projections decide how unrelated fields survive an edit. Atomic libraries supply native conversion functions.

Query editing resets its completion choice and scroll at the editing operation, not after unrelated events.

Raw draws a blob as a monospace hex line with a fixed 0x prefix, edited in place; no library draws blobs. One of more than 16 bytes shows its first eight bytes and its length until it's selected, and one of more than 1024 stays that way, replaced by typing over it rather than edited. Edits accept complete bytes; empty hex denotes an empty blob. Query entry and editing share GID's hex reader, gid::read_hex.

A selected, writable line with no editing state uses its current projected spelling with the caret at the end. Rendering and input use the same default; projection does not store it just because the line is selected. On an editing interaction, the line editor materializes state from that default. Its current handler supplies conversion. Existing caret, in-progress spelling, and IME state take precedence. Read-only views, and Raw outside a blob, do not acquire an editor from a plain selection.

Ordinary selection therefore needs only a location, including after completion, paste, deletion, and undo. Navigation targets receive an optional arrival direction. The line editor places the caret at the beginning when moving Right into it and at the end when moving Left; ordinary and vertical arrivals keep the default. This policy belongs to the widget, not navigation dispatch. Pointer placement remains an explicit interaction. The shell does not inspect values or the render tree to infer editability. See Select and the line editor.

Arrow keys move the selection between stops that projections declare, in an order the chosen layout determines; layout navigation is the reference for how stops are declared, ordered, and dispatched. Destinations keep the existing occurrence path, which carries its own interpretation, and navigation never resolves document paths to choose one.

Line editing uses the host-supplied keyboard convention: Mac Command+Left/Right moves to the content's ends and Option+Left/Right moves by words. Control-based hosts use Control+Left/Right for words. Shift extends the selection in each case. These controls handle movement before structural navigation; affixes remain outside the editable span.

Related occurrences are references to the same cell, or occurrences of the same location, an empty one included, so a hole drawn in two places marks as one. An offer that inserts a cell relates to it: hovering the offer, or choosing it from the keyboard while picking, marks where that cell is declared and used. Ordinary hover, selection, and related-occurrence highlights share one padded outline. Each occurrence paints at most one mark: selection takes precedence, then related selection, direct hover, and related hover. Pending text frames keep their own tighter outline through focus and editing; this widget styling does not determine the geometry of ordinary value highlights.

The editor owns an explicit Palette input, used by text, selections, library grounds, menus, completion cards, and popovers. Theme::Light uses white paper, blue names, violet field labels, and orange literals. Theme::Dark supplies brighter corresponding colors on navy paper. The macOS shell follows the system appearance at startup and on changes. Its native View menu offers Follow System Appearance, Light Mode, and Dark Mode; this application-wide override lasts for the session, including newly opened windows, and also updates window chrome. Other hosts default to Light; the browser host can explicitly choose either theme. Read-only projection boundaries use a faint tint; returning to writable source restores the same opaque paper used by the window. Changing the palette rebuilds the ordinary complete frame without replacing the document, selection, or undo history. Authored drawing colors remain document data, not theme colors. These styles change presentation, not projection recognition or source/selection policy.

Cmd+A (Ctrl+A on non-Mac hosts) selects the root of the selection's area through its landmark's direct-selection callback. With no selection, it targets the document view's whole area. Focused text fields handle the shortcut first and select their own text.

Completion

The projection drawing a hole decides what it offers. A hole is a pending value or label; its projection draws a picker there, an ordinary toolkit widget, and gives it the hole's offers. A projection's own offers, ranked against the query, are then the hole's whole vocabulary: the picker shows those offers and nothing else. The generic structure projection's holes, and the hole the editor draws for a missing value no projection draws, take Raw's picker. Raw offers the editor's constructors and what's typed, read as a value: what the libraries read the query as, such as a number, then text, or for a field the name library's new label named as typed, and bytes typed in GID's own 0x spelling. It offers no existing cells. An existing cell is reused by pointing at it (Cmd+click) or pasting it; typing makes something new. Cmd+clicking a drawn value points at it, and with no slot open selects it, as a click does; a value's own drawing adds nothing to that. Cmd+clicking a field's label points at the label, not the field's value. The hole at a document's root starts the document: it leads with what the libraries switched on there start one as, such as a Grap program or a Fidget scene, then offers Raw's. The Raw view switches every library off, so its holes offer only GID's own kinds: the constructors and 0x bytes. A picker can also take keys that choose an offer at once from an empty query, as Raw's brackets do. No provider is hidden in traversal context. Only the active picker asks for offers.

Deferred work lists what completion may add.

Each request includes the query, field/value kind, the question asked of a library (what it offers anywhere, what it reads the query as, or what a document can start as), the hole's path, read-only path and cell lookups, lazy enumeration of defined cells, the document's names for cells, and the loaded libraries' provider. Cell lookup exposes the selected definition's value and source, without evaluating it. The path names a missing value or the record receiving a new label, from where the hole's location starts, and path lookups read from there too. A hole in a cell's definition reads that definition as its own context, however the cell was reached, so Grap offers only the bindings visible within it. A projection's provider that answers None offers nothing, as Some([]) does. Raw asks the libraries for their readings of the query, a document's root for their starting points, and a projection's provider for whatever it wants, as Grap's slots ask for their offers anywhere. They answer in library order; None means a library has nothing to add.

Completion display text and detail can be literal text or a named cell reference. Library, constructor, parameter, and numeric-type labels use references; the picker resolves their current names before filtering each frame. Renaming a definition therefore updates even retained offers without changing their activation handler. An explicit empty name stays empty; a missing name uses the usual short cell identity. Typed values remain literal text.

The completion library's combine concatenates applicable lazy providers in order, preserving an explicitly empty vocabulary. Grap's parameter reader takes an inline or stored lambda's declared parameters when asked, for a call's field order, its slots for missing arguments, and call_completion's initial pending parameter. It follows cell aliases and declines cycles and computed callables. A foreign function's value lists the arguments its implementation requires under params; the reader takes that list as is and never interprets a foreign function as a lambda. Filtering names and excluding existing record labels remain picker responsibilities.

Grap's expression slots offer calls to named stored lambdas, closures, and foreign functions, found through the defined cells; the Grap library itself answers only what a document can start as. These are ordinary call_completion offers, distinguished by a call detail, which also names a library function's library; choosing one inserts {isa: call, function: cell} and opens its first declared argument when known. A call's function slot offers each function as itself, with a function detail. Call suggestions put document-defined functions before library functions, sorting each group alphabetically by display name, ignoring case. Typed-query matching still takes precedence; this order breaks equally ranked matches. Discovery does not evaluate code or guess the result of computed callables. Label pickers do not receive these call offers.

Grap expression slots supply their own provider: statically visible lambda parameters, preceding let/where bindings and the current match case's pattern bindings, plus named function calls, every library's offers anywhere, the editor's cell, list, and record constructors, quote, and what's typed, read as a value. This is an explicit local projection, including the items of do, not a global change to data completion. Binding suggestions put the nearest enclosing lexical scope first, then outer scopes, sorting names alphabetically within each scope. Rebinding a cell gives it the nearer scope's rank; scrolling and layout have no effect on this order. Typed-query match quality still ranks ahead of proximity. The request carries the loaded libraries' provider for composition; Grap reuses those offers rather than duplicating numeric conventions. Scope discovery reads source structure only; quoted template declarations do not introduce bindings into unquotes. Computed binding lists and runtime callable types are not inferred. Cells that are neither bindings nor functions, such as a named constant, are not offered there.

A projection that descends into a name passes the name library's partial, which draws a name as its line editor, there or missing: typed into where it's missing, the first keystroke writes the name, and Enter with nothing typed writes the empty string. A missing-name marker, such as an anonymous lambda's, selects that name location and then draws the same editor. A name field drawn by the generic structure projection offers Raw's instead. A sphere is a Fidget program, not a Fidget form: the examples that use one define sphere as an ordinary named Grap lambda that quotes Fidget arithmetic with its radius unquoted.

The numeric libraries read the query as f32, f64, and u64 numbers when it parses, showing the representation and the actual stored number; a query that doesn't parse, an empty one included, reads as no number. Any query reads as text, after the readings particular to it, an empty one as the empty string, which is text where it isn't a number. A new label needs something typed. An empty query therefore offers Raw's constructors, after a document root's starting points, then the empty string. A picker with nothing to offer draws no card, only its query. Raw orders its offers: a reading that spells the query exactly, the constructors the query names, the other readings in library order, text (or a new label), then constructors the query matches only loosely. The editor does not distinguish particular numeric representations for ranking. Explicit quoted text and blob syntax lead instead. Numeric providers decline label requests.

Raw's holes, and a document's root, make the editor's constructors from their delimiters: typed into an empty query, ( makes a new cell, [ a new list, and { a new record; a field label permits only the cell. These are keys of Raw's holes, not of the offers. A projection's hole takes a delimiter as text, which finds its constructor where the projection offers one, as Grap's do. Nonempty queries and IME composition keep ordinary text input; quoted punctuation leads with literal text. A new cell, list or record opens as it's made, as Cmd+Enter would open it, so typing goes inside: the cell's value, an element of the list, or a field of the record. Escape steps back out to it.

A library completion consists of presentation metadata and an activation handler receiving the dispatch's Session. Clicking or pressing Enter runs it; highlighting or moving between suggestions does not. Handlers may edit, change selection, or start an interaction without inserting data. An optional advertised value supplies source/filter metadata only; it never determines activation behavior.

The completion library's insert and generated helpers build ordinary insertion handlers. They accept an optional on_commit continuation, run at the committed location against the staged selection and annotation state. site::grap adapts a Grap callable to that continuation interface. Insertion and continuation effects are prepared together and installed only if the continuation accepts; Grap explicitly declining or halting declines the whole operation. Ordinary absent results do not veto it. Selection changes are effectful calls, not a special return-value format. Insertion itself does not change selection: the continuation receives the existing selection, and only its explicit effects replace or clear it. A low-level offer with no continuation leaves that selection unchanged, including an active pending query. Stock offer combinators supply the policy: completion::select selects the inserted value, and an insertion continuing with pending_at opens a label's missing value. Text, numbers, and blobs simply select their location; their line editors supply default editing when projected. Completions do not copy editor text, caret, or write-back rules into the selection. Query caret positions are not translated across parsing. These same offers work in Raw without an override, since that projection contains no atomic line editor. Enter commits only through the placed completion control; the shell has no fallback which inserts query text after its offers decline.

The color library's new color offer changes selection to picker state at the same missing location. No color is inserted and no undo entry is made until the first picker interaction. List insertion positions remain stable through that transition. The existing point-control gesture writes the selected color and groups the drag into one undo step. Escape before choosing returns to completion; leaving the location discards the picker without an edit. The seed color belongs only to the picker. An area with the color library switched off, Raw among them, offers none of the library's offers, this one included.

Root grap and fidget offers create a row of two parts sharing a fresh bare cell: a preview on the left, and a record whose domain field names the cell on the right. Fidget's preview applies preview 3d; Grap's renders the evaluated result. The continuation opens the cell's pending document definition through the domain field, in its pane, without inventing a placeholder value. Offers that mint identities construct their value on activation, so reusing an offer creates independent cells. Both are their libraries' starting points, which lead the hole of a document's root.

The placed frame retains the exact visible offers, so hover and commit never reconstruct a different list. Each offer has an activation callback plus explicit text, styling, matching spans, and source attribution. The reusable puri-widgets completion widget shapes and draws rows. Progred's native card widget composes navigation, interaction, and the shared column and scroll container, and places the card against its query; the row widget has no scroll viewport of its own. Its caller supplies state and activation callbacks; the widget knows nothing about paths, insertion, or Grap. The editor owns document operations and query state. See ranking, Raw's offers, committing a choice, and the picker. The card meets the query's painted frame, accounting for the frame outline and both border widths. Placement uses those same drawing parameters above or below the query, and includes the card's stroke when keeping it within the viewport. The card shows up to eight rows and scrolls the rest. It opens below the query when it fits there, otherwise above; when it fits neither, it takes the roomier side, showing only the rows that fit, rather than covering the query.

Changing the query filters the offers and resets selection and scroll. Returning to an older query does not restore an old choice. Down stops at the last row. Pointer and keyboard activation use the same callbacks. Keyboard navigation and unpressed mouse motion over a visible row update the same chosen-row state. Only that row is highlighted, and Enter activates it. Hover remains available for pointer activation but does not paint a second highlight or overwrite the choice during a redraw. Touch motion and active mouse drags do not choose rows, so scrolling and text selection can keep their gestures. Activating a visible offer consumes the input even if its continuation declines; Enter must not then fall through to inserting the raw query.

Panes

The editor lays out its window as a tree of views, a Layout: one view filling it, or a row or column of layouts, each with its share. It starts as the document's view alone, which shows the document's root and can't be closed, and the views the editor opens go at either end of its row. A view whose root value is a row or column splits its part of the window the same way, so the parts that value lists are panes of their own:

{isa: row, parts: [...values...]}      side by side
{isa: column, parts: [...values...]}   one above another

The editor's layout and a view's rows and columns are laid out in one walk. workspace splits the window by a row or column only at a view's root, and a part that's itself a row or column splits again. Deeper in a value, the editor library draws one as its parts laid out the same way, so rows compose anywhere: a column stacks its parts, and a row sets them side by side, as tall as its tallest, since there's no height to divide. A sized value among them draws at 256 points square. A row or column with no parts has nothing to split into and is data too. A view splits while its whole area shows the editor library; Plain and Raw, or turning the editor library off in the Projections menu, show its root whole, rows and all. The document's view and an opened view on a row split alike. A starting point that opens a preview begins as a row of the preview and the record it shows.

Parts take equal shares of their row or column at first, a rule apart, and dragging the rule moves share from one neighbour to the other. Shares are session state, as are the layout and each pane's libraries shown, folds and scroll; a share too small for the minimum width or height draws at the minimum without being rewritten.

A part's pane is an area of its view and draws its part at the part's own path below the view's root, so a pane showing its part reads and writes it, and its state, folds and scroll included, is kept by that path. A part can name a location as data: {isa: location, steps: [...]} from the document's root, or {isa: location, in: cell, steps: [...]} inside a cell's definition, with the steps in the path convention's encoding. A pane tells what its part is by its kind, so any other value, a record that happens to have a steps field included, shows as it is. While its pane shows the editor library, the pane jumps to that place at the part's path and draws and edits it there, so it stays in sync with the document; Plain and Raw show the location itself.

Opened views are the editor's and the document doesn't keep them, so opening, closing and moving one never edits the document, marks it changed, or enters its history. What a view shows, its entry, is Rust state too: a place, or a copy of a computed value. Open Value on Left and Right open the selection's place, starting at its nearest cell, so a cell is a location with no steps, at that end of the editor's row; a computed value has no place and opens as a copy, read-only. A view starts drawing where its entry is: a place from the document's root along the place's own steps, as the document's view would draw it, one inside a cell from a jump there, and a copy as computed. A place that's only empty, as after its value was deleted, draws as any empty place does, ready to write; one that can't be reached, as after its container was deleted, draws a read-only place not found absent carrying the location. The Libraries menu opens a loaded library the same way, as a location at its own cell, which is read-only like every library value, or selects the view already showing it; Open Value on a cell it lists opens that cell's definition beside it. An empty document stays empty, so its root still offers the starting points.

Close Pane closes a view the editor opened, or removes a part from its row or column, which writes the view's value where it's stored and undoes as one; a view's place stays as it is when the view closes. Move Pane moves a view along the editor's row, the document's included, or a part along its row or column in the view's value: left and right in a row, up and down in a column. Moving a part gives it a new list position and retargets the selection and the pane's share, while its path-keyed folds reset. A part that leaves keeps no pane state; one that stays keeps its own.

{isa: projected value, value: source, projection: function} is a presentation-library convention, not workspace configuration. The document's normal projection shows this declaration as editable data. At pane entry, including through cell definitions, the view tries the presentation library's declaration interpreter first. Nested values, computed results, and the source shown after an absent result use the normal projection, so declarations inside them remain data. This pane-entry following is separate from explicit local or scoped projection composition. Raw shows the structural data in either view. See projection composition.

An assigned-size pane uses {isa: sized value, value: source, viewport: function} instead. The function receives value, width, and height (logical display units) and returns ordinary display content, including handlers. Its pane has no automatic padding or document scrolling; the assigned rectangle clips its output. Pane splitting determines that rectangle before the function runs, so there is no feedback from content measurement to pane sizing. View annotations and selection keep their existing per-view ownership. Raw returns to ordinary scrolling source display. The viewport convention applies only at pane entry, including through cell aliases; the document view and nested declarations remain editable data.

The Fidget example and template use this contract. Preview image dimensions are explicit arguments, separate from the Fidget field and camera volume. Raster resolution follows the display scale; rectangular 3D views preserve square pixels rather than stretching the geometry. Ordinary preview calls without size arguments retain the 256-point default.

Fidget's preview functions return data of a kind: preview a slice preview, preview 3d a volume preview and preview mesh a mesh preview, each the field with its size and bounds, which Fidget's projections draw. preview 3d accepts either one Fidget field (white) or a scene: {isa: scene, objects: [{field: sdf, color: rgb}, ...]}. A scene groups separately colored objects; it is not a CSG operator. Geometry is depth-merged before lighting, and equal depths keep the earlier object. Colors use the existing color library's RGB/RGBA values; omitted colors are white and alpha must be opaque. An empty scene is transparent. Fidget's 16-bit object index limits one scene to 65,536 objects. Scene data is inert like other records: Grap code constructs it with ordinary quote/unquote, not implicit evaluation inside the scene. The native renderer uses Fidget's GPU color pass; the CPU/web renderer shades the winning geometry with the same object's color. Their lighting differs.

The IoP example uses an inline Grap viewport function to construct a drawing program with the assigned width and height. Those dimensions also reach tree scene; its drawing units and editable tree parameters are not rescaled.

History, gestures, and persistence

The drawn menu contributes its keyboard handler along with its bar and popups. Frame composition places that handler ahead of content handlers; omitting the menu also omits its shortcuts and keyboard navigation. Undo/redo have a separate editing handler, so embedded tutorials retain history without inheriting Raw, example switching, or pane commands. Native menus keep their own command routing.

A build's version, the commit it came from, is at the drawn bar's far end and in window titles. A click on the drawn one copies it, as Help → Copy Version does in either menu, including the macOS one, where only the title shows it.

Examples and replace-in-place New Document are development/demo conveniences, not the intended production File menu. Cmd+N (Ctrl+N on non-Mac hosts) and the example shortcuts replace the current document after confirming any unsaved changes. With no desktop window, they create one. Cmd+Shift+N / Ctrl+Shift+N is New Window; Open creates a separate window.

Replacement keeps the window, surface, geometry, fonts, text-shaping cache, clipboard, library stack, physical pointer/modifier input, and debug-display preference. It resets document/saved identity, history, selection and text/IME state, every pane, opened ones included, and its annotations (camera and folds among them), scroll, shown libraries, shares, divider state, binders, menus, gestures, queued input, retained handlers/paint, and hover attribution. The successor frame is built immediately. On macOS the old file's frame-autosave name is detached without deleting its saved geometry; the represented file, title, and edited flag are refreshed. These development commands are currently present in optimized make dev builds too; optimization level is not a distribution feature flag.

History is a generic pair of snapshot stacks; recording a new branch clears redo. The editor's snapshot contains its shared document, the selection's path, and per-view folds. Collapse and expand record steps without editing the document. Undo restores fold overrides to their panes, including when a deleted part returns; it leaves current scroll positions, shown libraries, and unrelated annotations alone in surviving panes. The selection keeps its view beside its path, so Undo restores it there rather than in whichever pane happens to be selected when Undo is invoked.

The editor holds its current and saved documents as Rc<Document>. Dirty state is pointer inequality, constant-time at any document size. Successful writes use copy-on-write; rejected writes do not detach the snapshot. Undoing to the saved snapshot clears the dirty flag, while manually recreating equal contents does not. Folding never changes document identity, and branch depth has no bearing on saved state. The GID document and its on-disk representation remain unchanged.

A line's first write records its undo step; subsequent writes in that edit run coalesce. Saving or recording a fold breaks the run. Projection gestures have one caller-owned slot in gesture. An ordinary native widget's accepting handler supplies the continuation; the slot does not distinguish number, camera, or color controls. Widgets process pointer samples, closing over document-edit runs or view-annotation setters supplied by the editor. An edit run groups its successful writes into one undo step. Creating the run, moving the caret, and writing an equal value do not write the document. Release, cancellation, replacing/restoring the document, saving, or recording a fold ends the gesture.

The platform supplies persistence and clipboard capabilities. macOS uses its native atomic write API. Linux writes a unique sibling temporary file, synchronizes it, renames it over the destination, and synchronizes the parent directory. Browser capabilities differ; see persistence and platform notes.

Frame construction, dispatch order, hover, and clipping are described in Puri and the editor frame.