Part of the architecture notes indexed in AGENTS.md. Keep each topic in its bullet here; AGENTS.md only lists the topics.
cad_ui.rs holds Import CAD (file dialog and dropped files) and the properties and layers of an imported drawing. AppState (state.rs) holds the Document, cached geometry/drawings, selection, active Tool, dialog flags. app.rs lays out the quick access toolbar + ribbon, options bar, left panel (project browser over properties), the egui_dock view tabs (app::show_views; tab_list.rs draws the open views list in the right margin each tab bar keeps free, issue #371: the bar’s views by view type in the browser’s order, Close Other Views and Close All Views queued in TabBar::close for sync_tabs, and the tab of every opened view scrolled into view through TabBar::reveal and the tab rects Tabs::on_tab_button records; the wheel over a crowded bar scrolls it, as egui_dock does), and the home screen (home.rs) when show_home. Tools (tools.rs) run inside 2D canvases; jobs.rs runs opening and imports (actions::open_path, IFC, SKP, component loads, cad_ui CAD and image imports) on a worker thread over a fresh document or a clone of the open one (jobs::Base; Document is Clone), shows the modal progress dialog, blocks shortcuts and dropped files while jobs::busy, and installs the result in jobs::poll (tests and startup call jobs::wait); side_panels.rs docks the Project Browser and Properties (PanelLayout in Preferences::panels: columns per side from the window’s edge inward, each stacking panes; moved by dragging a header onto a side strip or another panel’s edge, or from the header’s menu; the component environment’s panel takes Properties’ place); gestures.rs reads the scroll and pinch over a view (gestures::read: a wheel, reporting lines, zooms; a trackpad, reporting points, pans with two fingers and zooms with a pinch, unless Preferences::trackpad_pans is off), used by every canvas, the 3D view, the editors, the graph editor and the site map; preferences.rs holds the app preferences (AppState::prefs: theme, interface scale and text size, ribbon, tooltips, library/macros/projects folders, autosave, recent count), every eframe storage key with their validated load/save, sync_look (applies theme, zoom and font scale each frame) and the Preferences window (Ctrl+,; Cancel restores a snapshot); plugins_ui.rs loads the plugins folder into the session at startup (Preferences::plugins_dir; plugins_off are not loaded and run no code, plugins_files get the files permission; AppState::replace_document keeps the extension) and is the Plugins window (Installed and Available tabs; the index and archives are downloaded with ureq in background threads, never in tests) and the ribbon’s Plugin Commands menu, which opens a command in the palette (palette::open_command; the palette lists Session::commands); graph_ui.rs is the visual programming editor (AppState::graph, a panel under the views: an in-house canvas on egui’s painter, the node search over graph_nodes, an inspector, its own undo; runs go through graph_run; its keys take over while the pointer is over it, see graph_ui::keys); macro_ui.rs is the macro editor (AppState::macro_editor, a panel in the graph editor’s place, never both): the text with its gutter, script::check a moment after typing, and stepping through one script::Stepper whose steps follow the text while those that ran are unchanged (Stepper::set_steps), its keys taking over while the pointer is over it or its text has focus; Insert Command… opens the palette in its insert mode (palette::open_insert); library.rs is the component library window (the .ccomp files of Preferences::library_folders, edited in Preferences → File locations, listed by component_library_list); phases_dialog.rs holds the Phases dialog, the phase rows of view and element properties and the Demolish tool, and AppState::sync sets the creation phase to the active view’s (phase_creation_set); two-letter shortcuts are matched in app.rs::shortcuts. preselect.rs is Tab cycling of the Select tool’s pre-selection in 2D views (issue #406): Drawing2D::hits_at (the pick order; hit_test is its first) plus wall_ops::wall_chain after the first wall make the candidates, the raw input hook takes Tab over a canvas the Select tool armed the frame before (take_tab; not while a widget has the focus or a modal is open), frame applies the steps and the reset rules (pointer 3 points off the anchor, another view, a new revision, a click), and the status bar shows the candidate through AppState::hint (StatusHint, set each frame, in place of the message). Space with the Select tool (app.rs::shortcuts) flips a selected section mark, else runs tools::rotate_selection (elements_turn: components and columns turn, doors and windows flip, walls swap sides; see Wall flip in walls.md); tools that place or draw take Space for their own preview (rotation, hand, the wall tool’s Interaction::wall_flip).crafthouse.rs is the second source of the Component Library window (library::Source::Online, picked beside My Folders): the open library published at https://3dcrafthouse.constructcraft.net, a static site whose library/catalog.json lists each component (file, component, author, kind, parameters, types, optional thumbnail) and serves the files under library/components/<folder>/<name>.ccomp. Catalog contract for pictures: thumbnail is a path relative to the library URL, thumbnails/<folder>/<name>.png exactly two levels under thumbnails/, <folder> and <name> of 1 to 80 lowercase ASCII letters, digits and hyphens; the file is a PNG, nominally 360×240 (3:2), at most 1 MiB and 2048 pixels on each side; any other value is dropped and the component lists with no picture (library::Entry::thumbnail is None). AppState::crafthouse (CraftHouse) holds the catalog and the downloads for as long as the app runs; CraftHouse::sync, called each frame the source is shown (library::body), reads the catalog, downloads the file of the component picked (only that one, one at a time) and the pictures asked for since the last frame (want_picture, called by the cards in sight; up to 4 at once, the rest forgotten until their cards ask again), in background threads through plugins_ui::get and spawn (HTTPS only, bounded sizes, nothing in tests or with update checks disabled by the environment). The network is touched only once the user picks the source. The catalog is hostile input: parse_catalog keeps only entries whose file is components/<folder>/<name>.ccomp and pictures that are thumbnails/<folder>/<name>.png, with lowercase letters, digits and hyphens (plain_parts), so a download stays inside the cache folder (crafthouse in the app’s data folder; pictures in its thumbnails/<folder>/), caps the entries and the text lengths; a downloaded file is kept only when component_file::load reads it, and a picture only when check_picture decodes it whole with the png crate within the limits (else it is deleted and marked failed, not asked for again until Refresh). Copies kept from an earlier run (kept, looked for once per catalog path in looked) are used without the network: a component’s by local_or_kept, a picture’s by want_picture. Load into Project is disabled until the file has arrived and then runs component_load on it, as for a folder’s file (actions::load_component_path); the plan thumbnail shows once it is downloaded. The window (library::show) is three columns of a fixed height, each scrolling on its own: sidebar (the kind filters with their counts from kinds, the folder or author filter, the source’s buttons and status), grid (the count, the cards of shown, which applies the search, the filters and Library::sort, and the empty states with Manage Folders…, Clear Filters or Try Again) and details; Save Project Component… in the footer shows save_section under them. Tests fake the catalog, a download and a picture with CraftHouse::set_catalog, set_downloaded and set_picture.library::card_ui, picture; the details column’s picture too) shows a 3D picture of the component’s first type. An online card shows, in this order, the picture its catalog entry gives once it has arrived (library::online_picture: CraftHouse::want_picture, then picture), the thumbnail the app renders when the component’s file is local (downloaded or kept), or the placeholder icon; a picture that failed leaves the placeholder with no mark (the warning mark is for a component file that failed). thumbnails::component_scene builds a new project in a Session of its own, loads the file with component_load and places one instance: component_place at the origin, or, a door or a window, door_create/window_create in the shortest of three walls that takes it. thumbnails::process (the app loop, where the GPU is) renders Job::Component with Renderer3D::render_to_rgba, framed by the model’s bounds with no least size (render_component), one a frame, into component-<hash>.png of the thumbnails folder (component_file: the hash is of the path, size and modification time, so a changed file gets a new picture); the list loads it with home::load_thumbnail. The grid lays out only the rows of cards in sight (ScrollArea::show_rows), and a card asks for its thumbnail only while it is in sight and once per window (Library::thumbnails_asked); a component with nothing to render keeps the placeholder icon. An online card renders its own thumbnail only from a file already local: CraftHouse::local_or_kept takes the copy kept in the cache folder from an earlier run, and no component file is downloaded for a thumbnail; Refresh (CraftHouse::reset) sets fresh, so kept copies are downloaded again. Tests have no GPU and see no kept copies: they check the scene (a_component_scene_holds_the_component_placed) and the file naming.