The Document Behind M3E Canvas
M3E Canvas's most important technical decision is to represent a design as a structured document rather than as a picture. This chapter examines what that document remembers—screens, parts, groups, state, navigation, and author notes—and why the distinction matters whenever a sketch is saved, shared, previewed, or handed to a coding tool. By the end, the reader should be able to look at a M3E Canvas design as a small system with explicit entities and boundaries, not as a collection of shapes waiting to be redrawn.
A screen is more than a rectangle
In M3E Canvas, a screen is represented by a frame. The frame has a name, a position on the canvas, and optional dimensions, but those are only its visible skeleton. It can also carry a background role, a sentence describing the screen's purpose, a choice about where its body content should sit when the layout is tidied, and destinations for left, right, up, or down swipes. These fields answer different questions. The name gives a later prompt something stable to call; dimensions establish the viewport being designed; the background contributes a theme decision; the purpose note states why the screen exists; and the swipe map describes a gesture relationship that cannot be recovered from position alone.
That distinction between geometry and meaning is easy to miss when looking at a canvas. A frame placed beside another frame suggests a relationship to a human viewer, but it does not necessarily mean that one screen opens the other. M3E Canvas stores navigation explicitly. An item can point to another frame or to a back operation, and a frame can name a destination for a swipe. The editor can later show and exercise those relationships because they are data, not visual guesses.
A frame also does not own a private list of children in the way a conventional scene graph might. Groups and parts live in canvas coordinates, and the editor determines which frame contains a group from the group's bounds and center. That choice makes it possible to move a complete screen and everything on it together. It also creates a condition for success: a part must remain geometrically inside the intended frame, or it may be treated as loose canvas material rather than screen content. The coordinate system is therefore practical and flexible, but it is not a substitute for naming or notes when a relationship matters.
The second level is the group. A group can hold one part, a connected run, or a hand-made collection whose members retain their own offsets. A connected run is a compact structural statement. Several buttons in one horizontal run are not merely near one another; they form a row whose order and spacing matter. Several list items in one vertical run are not unrelated cards; they are a list with a reading order. The group gives the editor a place to move that unit while preserving the relationship among its members.
A free group serves a different purpose. When an author selects several parts and groups them, M3E Canvas records each part's offset inside the group. That allows a box to remain behind the things placed on it, or a badge to remain over the corner of an icon, while the composition moves as a whole. The parts are not forced into a new row or column merely because they share a parent. The free group preserves a hand-made arrangement; a connected run describes a regular arrangement that the editor can lay out along an axis.
The distinction is valuable because it separates two kinds of intent that are often flattened by design tools. A row says, in effect, “these parts belong together in this order.” A free group says, “these parts move together, but their internal geometry is part of the design.” If both were stored as a flat set of rectangles, later operations would have to rediscover the relationship from proximity and overlap. M3E Canvas can still use geometry when it needs to, but the author's grouping choice gives that geometry a stronger signal.
An item is the smallest semantic unit. Its fields cover the visible surface—kind, label, icon, variant, size, and optional color or image choices—but also the state and behavior that a screenshot cannot carry. A navigation bar has destinations and a selected index. A dropdown has options and possibly an initial selection. A switch, checkbox, chip, or button can have an on/off state. A button can have a toggle look that replaces its label, icon, or style when tapped. An item can carry a behavior note in the author's own words, a direct action to another screen, or separate actions for slots such as the icons on a top app bar and the destinations in a navigation bar.
Those fields are deliberately small, but they are not trivial decoration. Consider a row labeled “Saved.” Its text and icon identify the visible object. Its action says whether tapping it opens a detail screen. Its note can explain whether the action saves a record, opens a filter, or asks for confirmation. Its selected state may tell the eventual implementation which navigation destination is active on first render. Each fact has a different owner. The item owns its label and state; the action owns the transition relationship; the author's note owns product-specific behavior that the component type cannot know.
The top-level document also carries choices that apply across the design: title, brief, palette, optional custom scheme, dynamic color, platform, and theme. This is how a single sketch can express an app-wide direction without copying the same decision into every part. A frame may override its background or a component may use a particular role, but the document still supplies the common context from which the rendering and prompt generation can work.
The class diagram is conceptual rather than a claim that M3E Canvas uses an object-oriented runtime with these classes. Its point is to show the interfaces around one document. A validator checks whether an incoming value has the shape the editor relies on. The preview reads the same authored actions and states. The prompt compiler reads the same groups, frames, and theme. A share link carries a sanitized projection of the document. No subsystem needs to reinterpret a screenshot in isolation.
Portability needs a lifecycle, not just a format
A document becomes useful only when it can survive transitions. M3E Canvas supports two straightforward entry points: a project file and a share link. A project file is JSON. When the author chooses a file, the editor parses it and checks the shape of the document before treating it as a design. The checks reach into nested groups, frames, and items, looking for the fields that the renderer and editor depend on: valid identifiers, known component kinds and variants, finite coordinates, sensible dimensions, correctly shaped tabs, and valid optional values.
This is a syntactic boundary, not a semantic verdict. A structurally valid document can still describe a confusing product. It can contain a screen with a vague name, a button whose note is misleading, or an action that is technically well formed but product-inappropriate. Conversely, a document saved by an older version may omit newer optional fields without being rejected. The project code is designed to tolerate legacy shapes and let the editor's migration path bring them forward. That is a useful maintenance posture: the file format can evolve without requiring every old sketch to be manually rewritten before it can be opened.
The validator's restraint is as important as what it checks. It verifies that an item says what kind of item it is and that its values have the expected types. It does not decide whether a list item should navigate, whether a screen needs a search action, or whether a color choice has good product judgment. Those are authoring questions. Treating them as validation errors would make the file boundary appear safer than it really is, because semantic completeness cannot be inferred from the shape of a JSON object.
The share path has a different purpose from the project-file path. A project file is a local working document and may contain a picked image encoded in browser data, along with history that lets an AI rewrite be undone. A share link is intended to carry a design to another canvas. Before encoding it, M3E Canvas removes frame and item note history and omits local image data. It keeps an image source only when it is an explicit HTTP(S) URL, which another browser can reasonably request. This is not merely a compression optimization. It defines what the author is willing to put into a public-looking URL.
The link then carries the sanitized JSON in the URL fragment. When the browser provides the relevant compression stream, the document is raw-deflate compressed and base64url encoded under a docz parameter; a plain JSON parameter is available as a fallback. The fragment is processed in the browser and does not need a server-side lookup table. That is what allows a static site to open a design directly from its link. It is also the source of a clear limitation: the link contains the design itself, so its length grows with the number of screens, notes, and structural choices. It is portable, but it is not a shared database with server-side revisions, membership, or access control.
The browser-local operating model continues after a document is loaded. The editor stores the current document and interface preferences in localStorage. When the browser supports Web Locks, the first tab obtains an editing lock and a later tab becomes read-only rather than competing to write the same document. This protects against one narrow class of accidental concurrent editing. It does not turn localStorage into durable collaboration infrastructure, and it does not make secrets safe. The convenience is real, but so are the browser's storage limits and the exposure of data to anyone who can use that browser profile.
State ownership becomes especially important when the document enters the preview. Authored state belongs in the document when it describes the initial design: a selected navigation destination, a checked switch, or a toggle's alternate appearance. Preview state belongs to the preview when it records what a visitor has just tapped, dragged, or selected while trying the flow. A slider value changed during a preview should not silently rewrite the author's layout document. Keeping those concerns separate lets the preview behave like a testable interaction surface without pretending that it is the application's database.
The same boundary appears in AI assistance. A behavior note suggested by a model is not accepted as an invisible mutation of the design's meaning. The helper keeps the previous wording so the author can restore it. A whole-design draft arrives as a candidate document and goes through the normal replacement path; on desktop, the previous design waits for an explicit keep or undo decision. The document remains the object the editor can validate, save, preview, and share. The model supplies a proposal at one boundary, not a new source of truth that bypasses the others.
This lifecycle clarifies what “portable” means in M3E Canvas. It does not mean that every detail survives every path unchanged. A local picked image is appropriate for a private working document but is intentionally removed from a share link. AI rewrite history is useful for recovery but is not part of the public design. Runtime slider and dropdown changes are useful for trying a flow but are not automatically authored requirements. Portability means that the design's intended structural and behavioral core can cross a file or link boundary in a form the editor can recognize, while each boundary makes an explicit decision about incidental or private state.
The result is a document that is stronger than a screenshot without becoming a complete product specification. It can name screens, preserve groups, express states, point actions at destinations, carry theme and platform context, and give later systems a stable input. It cannot decide every domain rule, guarantee the quality of a downstream implementation, or know the rationale behind an unrecorded overlap. The next challenge is therefore operational rather than merely representational: how can a person arrange this model quickly while keeping its explicit relationships intact? That is the problem the magnetic editor, Tidy, layers, and locks will answer.