draw-ui 0.1.0__tar.gz

draw_ui-0.1.0/DRAW_PUBLIC_API.txt

@@ -0,0 +1,793 @@
+================================================================================
+DRAW-LIB (v0.1.0) — COMPLETE PUBLIC API REFERENCE MANUAL
+================================================================================
+Library: Draw-lib (Python Declarative 2D Canvas, Layout, Physics & UI Library)
+Base Engine: PySide6 (Qt 6)
+Entry Point: import Draw
+
+--------------------------------------------------------------------------------
+TABLE OF CONTENTS
+--------------------------------------------------------------------------------
+ 1. Core & Application Lifecycle
+ 2. Window Management (Draw.window)
+ 3. Shapes & Vector Geometry (Draw.shape / Draw.shapes)
+ 4. Typography & Caret Inputs (Draw.text, Draw.lineedit, Draw.textedit)
+ 5. Declarative Graphing & Charts (Draw.graph)
+ 6. Physics Links & Input Senses (Draw.connectors, Draw.senses)
+ 7. Procedural 2D Motion Engine (Draw.motion, Draw.custom, Draw.timeline)
+ 8. Layout Engines (Draw.room, Draw.table, Draw.grid)
+ 9. Panels & Floating Windows (Draw.panel)
+10. Live Display Surface (Draw.screen)
+11. Hardware-Accelerated OpenGL Engine (Draw.super / Draw.super_mode)
+12. Performance & Math Optimization (Draw.optimize, Draw.performance_mode)
+13. Reactive Variables (Draw.live, Draw.input_field)
+14. Mathematical Expression Evaluator (Draw.calculator / Draw.calculater)
+15. Color & Dynamic Themes (Draw.color / Draw.colour)
+16. Scene State Checkpoints (Draw.checkpoint)
+17. Native Qt Controls & Layout Boxes (Draw.widget, Draw.box)
+18. File Tree Explorer (Draw.filetree)
+19. Point Paths & Pen Drawing (Draw.point, Draw.turtle)
+20. System Utilities (Draw.clipboard, Draw.filedialog, Draw.schedule, Draw.simulate)
+21. Debugging, Watchdog & Profiling (Draw.debug)
+22. Global Constants & Position Tokens
+
+================================================================================
+1. CORE & APPLICATION LIFECYCLE
+================================================================================
+
+Draw.get_app() -> QApplication
+    Returns or lazily creates the global PySide6 QApplication instance.
+
+Draw.quit()
+    Exits the entire application process cleanly.
+
+Draw.close_all()
+    Closes and destroys all active windows and associated resources.
+
+__version__ : str
+    Current library release version (e.g. "0.1.0").
+
+
+================================================================================
+2. WINDOW MANAGEMENT (Draw.window)
+================================================================================
+
+Draw.window(
+    tag="main",                     # Unique identifier for the window
+    title="",                       # Window title bar text
+    width=800,                      # Initial width in pixels
+    height=600,                     # Initial height in pixels
+    x=None,                         # Absolute screen x position
+    y=None,                         # Absolute screen y position
+    align=None,                     # "center" | "top-left" | "top-right" | "bottom" | ...
+    background_color="white",       # Hex string, named color, RGB tuple, or QColor
+    transparency=100,               # Opacity percentage (0 to 100)
+    frameless=False,                # If True, removes OS title bar & window borders
+    always_on_top=False,            # If True, keeps window above other apps
+    resizable=True,                 # Enable/disable window resizing
+    min_width=100,                  # Minimum resize width
+    min_height=100,                 # Minimum resize height
+    max_width=None,                 # Maximum resize width
+    max_height=None,                # Maximum resize height
+    icon=None,                      # File path to window icon
+    draggable=True,                 # If True, enables click-drag moving for frameless windows
+    on_resize=None,                 # Callback fn(width, height)
+    on_move=None,                   # Callback fn(x, y)
+    on_focus=None,                  # Callback fn(is_focused)
+    on_close=None                   # Callback fn() -> bool (return False to cancel close)
+) -> QMainWindow
+
+Window Methods:
+    Draw.window.show(tag="main")
+    Draw.window.hide(tag="main")
+    Draw.window.close(tag="main")
+    Draw.window.run(tag="main")      # Shows window and runs Qt event loop
+    Draw.window.get(tag="main") -> QMainWindow
+    Draw.window.list_tags() -> list[str]
+    Draw.window.move(tag, x, y)
+    Draw.window.resize(tag, width, height)
+    Draw.window.set_background_color(tag, color)
+    Draw.window.set_transparency(tag, opacity)
+    Draw.window.set_always_on_top(tag, flag)
+    Draw.window.set_title(tag, title)
+
+
+================================================================================
+3. SHAPES & VECTOR GEOMETRY (Draw.shape / Draw.shapes)
+================================================================================
+
+Draw.shape(
+    display="main",                 # Window or panel tag to draw upon
+    shape=[{                        # List of shape dictionary definitions
+        # ── Geometry ──
+        "ip": "unique_shape_id",    # Unique shape identifier for event/style binding
+        "vertices": 4,              # Number of polygon vertices (None or 4 = rect, 3 = tri, 6 = hex)
+        "size": [100, 100],         # [width, height], "100px", or percentage "50%"
+        "x": None,                  # Absolute pixel x coordinate
+        "y": None,                  # Absolute pixel y coordinate
+        "align": "center",          # "center" | "top-left" | "bottom-right" | "ip:other_id"
+        "border_radius": 0,         # Pixel radius or "50%" for circle
+        "rotation": 0,              # Rotation angle in degrees (or dynamic AST formula)
+        "rotation_center": None,    # Pivot (x, y) tuple, default is center
+        "z": 0,                     # Z-index layer (higher = further back)
+        "overlap": True,            # Collision layer participation flag
+
+        # ── Appearance ──
+        "color": "cyan",            # Fill color (named string, hex, RGBA tuple, or formula)
+        "border_color": "white",    # Stroke outline color
+        "border_width": 1,          # Stroke outline width in pixels
+        "border_style": "solid",    # "solid" | "dashed" | "dotted" | "none"
+        "opacity": 100,             # Opacity 0-100 (or formula)
+        "glow_color": None,         # Outer neon glow color
+        "glow_blur": 0,             # Outer neon glow radius in pixels
+        "shadow_color": None,       # Drop shadow color
+        "shadow_blur": 0,           # Drop shadow blur radius
+        "shadow_offset": [0, 0],    # Drop shadow [dx, dy]
+
+        # ── Procedural Deformations & Modifiers ──
+        "curve_mode": "line",       # "line" | "smooth" | "slope" | "wave" | "arc" | "bend_all"
+        "bend_amount": 40,          # Deflection amount for bend_all mode
+        "bend": [{                  # Per-side curvature deformation list
+            "side": 1,              # 1=top, 2=right, 3=bottom, 4=left
+            "affect": "-100%->100%",# Extent along the edge
+            "offset": 30,           # Deflection offset in pixels
+            "smooth": 60,           # Spline smoothness
+            "direction": "out",     # "out" | "in"
+        }],
+        "warp": [                   # 2D Mesh warping displacement grid
+            [(0, 0), (5, -10), (0, 0)],
+            [(0, 0), (0, 0),   (0, 0)]
+        ],
+        "symmetry": {               # Symmetry generation
+            "type": "radial",       # "radial" | "mirror" | "grid"
+            "count": 4
+        },
+        "exclude": [{               # Boolean cutouts / exclusions
+            "scale": [50, 50],
+            "let_it": "center"
+        }],
+
+        # ── Hitbox & Interaction ──
+        "hitbox_mode": None,        # None | "shape" | "closed_rec"
+        "hit_box": "shape",         # Accurate polygon or bounding box hit test
+        "properties": ["builder"],  # "builder" enables interactive drag-to-create
+    }],
+    text=[...]                      # Optional list of text definitions
+)
+
+Shape Methods:
+    Draw.shapes.get(ip) -> ShapeDef
+    Draw.shapes.list(display="main") -> list[ShapeDef]
+    Draw.shapes.remove(ip)
+    Draw.shapes.clear(display="main")
+    Draw.shapes.move(ip, x, y)
+    Draw.shapes.resize(ip, width, height)
+    Draw.shapes.update(ip, **kwargs)
+
+Auxiliary Constructors:
+    Draw.hitbox(display, ...)
+    Draw.container(display, ...)
+    Draw.image(display, ip, src, size, x, y, ...)
+    Draw.video(display, ip, src, size, x, y, loop=True, autoplay=True, muted=False)
+    Draw.loader(display, ip, type="spinner", ...)
+
+
+================================================================================
+4. TYPOGRAPHY & CARET INPUTS (Draw.text, Draw.lineedit, Draw.textedit)
+================================================================================
+
+Draw.text(
+    display="main",
+    text=[{
+        "ip": "lbl1",               # Unique identifier
+        "text": "Hello World",      # Text content or dynamic LiveTextBinding
+        "x": 100,                   # Pixel x
+        "y": 100,                   # Pixel y
+        "align": "center",          # Alignment anchor
+        "font_family": "Segoe UI",  # Font family name
+        "font_size": 16,            # Font size in pixels
+        "color": "white",           # Text color
+        "bold": False,              # Bold styling
+        "italic": False,            # Italic styling
+        "letter_spacing": 0,        # Pixel kerning
+        "line_height": 1.2,         # Line height multiplier
+        "arc": None,                # Arc radius for circular text curving
+        "typewriter": None,         # Typewriter animation speed in chars/sec
+        "glow_color": None,         # Neon text glow
+        "glow_blur": 0,
+        "background_color": None,   # Text bubble fill color
+        "background_padding": 4,    # Text bubble padding in pixels
+        "z": 0,
+        # Interactive text editing
+        "input": False,             # If True, acts as an editable canvas text field
+        "input_caret": True,        # Show blinking caret
+        "input_mask": None,         # Character filter regex / mask
+        "input_max_len": None,      # Maximum character count
+        "on_change": None,          # Callback fn(new_text)
+        "on_submit": None,          # Callback fn(submitted_text)
+    }]
+)
+
+Native Text Edit Wrappers:
+    Draw.lineedit(ip, display, x, y, width, height, placeholder="", text="", on_change=None)
+    Draw.textedit(ip, display, x, y, width, height, placeholder="", text="", on_change=None)
+    Draw.lineedit.get_text(ip) -> str
+    Draw.lineedit.set_text(ip, text)
+    Draw.textedit.get_text(ip) -> str
+    Draw.textedit.set_text(ip, text)
+
+
+================================================================================
+5. DECLARATIVE GRAPHING & CHARTS (Draw.graph)
+================================================================================
+
+Draw.graph(
+    ip="sales_chart",               # Unique chart identifier
+    type="bar",                     # Chart type (see list below)
+    display="main",                 # Window tag
+    graph=[                         # Chart series data
+        {"label": "Q1", "value": 450, "color": "cyan"},
+        {"label": "Q2", "value": 720, "color": "blue"},
+        {"label": "Q3", "value": 580, "color": "purple"},
+        {"label": "Q4", "value": 910, "color": "pink"},
+    ],
+    customise={                     # Visual and interaction customization
+        "width": 500,               # Chart bounding width
+        "height": 300,              # Chart bounding height
+        "x": 50,                    # Position x
+        "y": 50,                    # Position y
+        "title": "Quarterly Sales", # Chart header title
+        "title_color": "white",
+        "grid_lines": True,         # Show background grid lines
+        "grid_color": "#333333",
+        "show_values": True,        # Show data numbers over bars/points
+        "bar_width": 40,            # Bar width in pixels
+        "inner_radius": 60,         # Donut hole radius (for pie/donut charts)
+        "draggable": True,          # Interactive drag chart across canvas
+        "hover": True,              # Interactive hover highlights
+        "tooltip": True,            # Floating tooltip cards
+        "live": None,               # Dynamic LiveRef data binding
+        "animate": "spring",        # Entry animation ("spring" | "fade" | "pop")
+    }
+)
+
+Supported Chart Types:
+    - "bar"           : Standard vertical bar chart
+    - "stacked_bar"   : Multi-series stacked vertical bars
+    - "line"          : Continuous vector line spline
+    - "area"          : Filled gradient area chart
+    - "stacked_area"  : Multi-series filled area chart
+    - "dot" / "scatter": Scatter coordinate plot
+    - "pie"           : Circular pie proportion wedges
+    - "donut"         : Pie chart with configurable center hole
+    - "radar" / "spider": Multi-axis radial radar webs
+
+Graph Management:
+    Draw.graph.update_live(window_tag="main")
+    Draw.graph.get_pixel_bounds(ip) -> tuple[float, float, float, float]
+    Draw.graph.get_intrinsic_size(ip) -> tuple[float, float]
+    Draw.graph.move_by_ip(ip, dx, dy)
+    Draw.graph.resize_by_ip(ip, new_w, new_h)
+    Draw.graph.clear(ip=None, display="main")
+
+
+================================================================================
+6. PHYSICS LINKS & INPUT SENSES (Draw.connectors, Draw.senses)
+================================================================================
+
+Draw.connectors(
+    from_ip="bob",                  # Anchor or leader shape ID
+    to_ip="stick",                  # Dependent or attached shape ID
+    link="pin",                     # Physics link constraint (see list below)
+    properties={                    # Constraint parameters
+        "anchor": "bottom",         # Anchor point ("center" | "top" | "bottom" | "left" | "right")
+        "rotate_with": True,        # Rotate dependent together with leader
+        "length": 150,              # Rod/rope length in pixels
+        "gravity": 980,             # Downward acceleration (px/s²)
+        "stiffness": 200,           # Spring constant (N/px)
+        "damping": 0.05,            # Damping friction ratio (0.0 to 1.0)
+        "mass": 1.0,                # Bob mass in kg
+        "speed": 90,                # Orbital speed in deg/sec
+    },
+    group="default"                 # Connector group tag
+)
+
+Link Constraint Types:
+    - "pin"          : Rigid multi-body joint attachment
+    - "pendulum"     : Gravitational pendulum with angular damping
+    - "spring"       : Hooke's law oscillating spring joint
+    - "rope"         : Flexible tension-only hanging rope
+    - "sync"         : Property synchronization (x, y, rotation, color, opacity)
+    - "orbit"        : Constant radial orbital motion
+    - "magnet"       : Inverse-square magnetic attraction force
+    - "distance_lock": Hard rod distance constraint
+
+Draw.senses(
+    sense_type="click",             # "click" | "hover" | "drag" | "proximity" | "key"
+    id="btn_click",                 # Unique sense ID
+    ip="my_button",                 # Target shape ID
+    target=None,                    # Secondary target (for proximity senses)
+    threshold=30,                   # Proximity distance threshold in pixels
+    work=callback_fn,               # Action callback fn(record)
+    debounce=0.1                    # Debounce period in seconds
+)
+
+Senses & Connector Control:
+    Draw.connectors.pause_group(group="physics")
+    Draw.connectors.resume_group(group="physics")
+    Draw.connectors.stop_ticker()
+    Draw.senses.first_click(display) -> tuple[float, float]
+    Draw.senses.last_release(display) -> tuple[float, float]
+    Draw.senses.region(display) -> tuple[float, float, float, float]
+    Draw.senses.capture_region(display)
+
+
+================================================================================
+7. PROCEDURAL 2D MOTION ENGINE (Draw.motion, Draw.custom, Draw.timeline)
+================================================================================
+
+Draw.motion(
+    target="shape",                 # Target category: "shape" | "hitbox" | "custom.motion"
+    ip="ball",                      # Target shape ID
+    motion="spring",                # Motion type (see list below)
+    params={                        # Motion parameters
+        "stiffness": 180,
+        "damping": 12,
+        "mass": 1.0,
+        "dx": 200,
+        "dy": 0,
+        "duration": 1.5,
+    }
+)
+
+Supported Motion Types (38 Total):
+    - Spatial: "move", "position", "x", "y", "path", "projectile"
+    - Scale: "scale", "expand", "stretch_squash", "pulse"
+    - Rotation: "rotate", "rotate_x", "rotate_y", "rotate_3d", "perspective", "skew", "shear"
+    - Color & Style: "color", "opacity", "blur", "glow", "stroke_dash", "trim_path"
+    - Procedural & Physics: "shake", "wiggle", "wave", "pulse", "gravity", "bounce_physics",
+                           "spring", "inertia", "pendulum", "orbit", "polygon_orbit",
+                           "benzene", "lissajous", "spiral", "attractor", "noise", "morph"
+
+Timeline & Custom Easing:
+    Draw.timeline(ip="anim", duration=3.0, loops=0, on_tick=fn, on_finish=fn)
+    Draw.custom(ip="curve", expression="sin(t * 4) * 50")
+
+
+================================================================================
+8. LAYOUT ENGINES (Draw.room, Draw.table, Draw.grid)
+================================================================================
+
+Draw.room(
+    display="main",                 # Window tag
+    scene="card_layout",            # Room layout scene name
+    general={                       # General canvas constraints
+        "margin": 20,
+        "padding": 10,
+    },
+    sizes={                         # Relative topological layout schema
+        "header": {"align": "top", "height": 60, "width": "100%"},
+        "sidebar": {"align": "left", "inside": "header", "width": 200, "height": "fill"},
+        "content": {"align": "right", "inside": "sidebar", "width": "fill", "height": "fill"},
+        "footer": {"align": "bottom", "height": 40, "width": "100%"},
+    }
+)
+
+Draw.table(
+    ip="grid_table",
+    display="main",
+    rows=4,
+    columns=3,
+    margin=10,
+    padding=5,
+    show_lines=True,
+    line_color="#444444"
+)
+
+Draw.grid(
+    grid_ip="calc_keypad",
+    dimension=[4, 3],               # [rows, cols]
+    template={"size": [60, 60], "color": "#222222", "border_radius": 8},
+    text_template={"font_size": 18, "color": "white"},
+    items=[
+        {"text": "7", "ip": "btn_7"}, {"text": "8", "ip": "btn_8"}, {"text": "9", "ip": "btn_9"},
+        {"text": "4", "ip": "btn_4"}, {"text": "5", "ip": "btn_5"}, {"text": "6", "ip": "btn_6"},
+        {"text": "1", "ip": "btn_1"}, {"text": "2", "ip": "btn_2"}, {"text": "3", "ip": "btn_3"},
+        {"text": "0", "ip": "btn_0"}, {"text": ".", "ip": "btn_dot"}, {"text": "=", "ip": "btn_eq"},
+    ]
+)
+
+
+================================================================================
+9. PANELS & FLOATING WINDOWS (Draw.panel)
+================================================================================
+
+Draw.panel(
+    ip="settings_panel",            # Unique panel ID
+    display="main",                 # Parent window tag
+    title="Settings",               # Title bar text
+    width=320,                      # Initial width
+    height=400,                     # Initial height
+    x=50,                           # Position x inside parent canvas
+    y=50,                           # Position y inside parent canvas
+    align=None,                     # "center" | "top-right" | ...
+    background_color="#1e1e2e",     # Panel body fill color
+    title_color="#cdd6f4",          # Title text color
+    title_background="#313244",     # Title bar background color
+    border_color="#45475a",         # Border outline color
+    border_width=1,
+    border_radius=8,
+    transparency=100,               # Opacity (0 to 100)
+    draggable=True,                 # Allow user to drag panel by title bar
+    resizable=False,                # Allow user to resize panel
+    closable=True,                  # Show close button
+    minimizable=False,              # Show minimize button
+    frameless=False,                # Hide title bar completely
+    always_on_top=False,            # Float above other panels
+    shadow=True,                    # Render drop-shadow around panel
+    shadow_color="#000000",
+    shadow_blur=12
+)
+
+Panel Methods:
+    Draw.panel.show(ip)
+    Draw.panel.hide(ip)
+    Draw.panel.close(ip)
+    Draw.panel.move(ip, x, y)
+    Draw.panel.resize(ip, width, height)
+    Draw.panel.get(ip) -> PanelDef
+    Draw.panel.list() -> list[str]
+
+
+================================================================================
+10. LIVE DISPLAY SURFACE (Draw.screen)
+================================================================================
+
+Draw.screen(
+    tag="display_surface",          # Display surface ID
+    display="main",                 # Parent window tag
+    width=640,
+    height=480,
+    x=0,
+    y=0,
+    align="center",
+    keep_aspect=True,               # Maintain frame aspect ratio during scaling
+    drawing_mode=False,             # Enable interactive freehand pen drawing stream
+    pen_color="red",
+    pen_width=3,
+    on_click=None,                  # Callback fn(x, y, button)
+    on_drag=None,                   # Callback fn(x, y, dx, dy)
+    on_draw=None                    # Callback fn(stroke_points)
+)
+
+Screen Methods:
+    Draw.screen.update_frame(tag, frame)  # Accepts numpy ndarray, PIL Image, QImage, QPixmap, bytes, or file path
+    Draw.screen.clear(tag)
+    Draw.screen.get_frame(tag) -> QImage
+    Draw.screen.get_strokes(tag) -> list
+
+
+================================================================================
+11. HARDWARE-ACCELERATED OPENGL ENGINE (Draw.super / Draw.super_mode)
+================================================================================
+
+Draw.super(
+    display="main",                 # Target window tag (or None for all)
+    precompile=True,                # Upfront geometry compilation and spatial warm-up
+    mode="max",                     # Performance profile: 'dev' or 'max'
+    vsync=False,                    # Disable VSync for uncapped high FPS
+    batch_capacity=65536            # Max vertex buffer allocation for GPUGeometryBatcher
+) -> _DrawOpenGLCanvas
+
+Aliases:
+    Draw.super_engine
+    Draw.super_mode
+
+
+================================================================================
+12. PERFORMANCE & MATH OPTIMIZATION (Draw.optimize, Draw.performance_mode)
+================================================================================
+
+Draw.optimize(
+    scene=None,                     # Target list of shapes (or all active)
+    mode="max",                     # "dev" | "max"
+    gc_tune=True,                   # Tune Python GC generation thresholds
+    render_profile="fast"           # "quality" | "fast" | "ultra"
+) -> dict                           # Diagnostic compile telemetry
+
+Draw.performance_mode() -> str      # Returns active mode ("dev" or "max")
+Draw.set_performance_mode(mode)     # Sets mode ("dev" or "max")
+Draw.performance_info() -> dict     # Returns active backend, GC status, and compiled stats
+
+
+================================================================================
+13. REACTIVE VARIABLES (Draw.live, Draw.input_field)
+================================================================================
+
+Draw.live.ref(initial_value, key=None) -> LiveRef
+    Creates a reactive pointer reference to a variable.
+
+Draw.live.text(ref_or_callable) -> LiveTextBinding
+    Creates a reactive text binding for Draw.text() labels.
+
+Draw.live.get(key, default=None) -> Any
+    Reads a live reactive variable.
+
+Draw.live.set(key, value)
+    Updates a live reactive variable and triggers canvas refresh.
+
+Draw.live.subscribe(key, callback_fn)
+    Attaches a change listener callback to a reactive key.
+
+Draw.input_field(display, ip, x, y, width, height, ...)
+    Convenience alias creating an editable text entry field.
+
+
+================================================================================
+14. MATHEMATICAL EXPRESSION EVALUATOR (Draw.calculator)
+================================================================================
+
+Draw.calculator(expr: str, variables: dict = None) -> float
+    Evaluates safe mathematical expression strings using Python's AST parser.
+
+Draw.calculator.eval_expression(expr: str, variables: dict = None) -> float
+Draw.calculator.is_expression(value: Any) -> bool
+
+Available Math Functions:
+    sin, cos, tan, asin, acos, atan, sinh, cosh, tanh,
+    abs, min, max, sqrt, log, ln, log2, floor, ceil, round,
+    degrees, radians, lerp(a, b, t), step(edge, x)
+
+Available Constants:
+    pi, e, time (in dynamic contexts)
+
+Alias:
+    Draw.calculater (preserved for backward compatibility)
+
+
+================================================================================
+15. COLOR & DYNAMIC THEMES (Draw.color / Draw.colour)
+================================================================================
+
+Draw.color(
+    ip="shape_id",                  # Target shape ID or window tag
+    color="hsl(time * 60, 100%, 50%)", # Static string or dynamic formula
+    border_color=None,
+    border_width=None,
+    gradient=None,                  # Gradient definition dict
+    shadow_color=None,
+    shadow_blur=0,
+    glow_color=None,
+    glow_blur=0
+)
+
+Color Theme Management:
+    Draw.save_tokens(filepath="theme.json")
+    Draw.load_tokens(filepath="theme.json")
+    Draw.color.register_dynamic(ip, resolver_fn)
+    Draw.color.has_binding(ip) -> bool
+    Draw.color.resolve_for_shape(ip, shape_x, shape_y, shape_w, shape_h) -> dict
+
+
+================================================================================
+16. SCENE STATE CHECKPOINTS (Draw.checkpoint)
+================================================================================
+
+Draw.checkpoint(
+    ip="scene_slot",                # Checkpoint slot name (REQUIRED)
+    display="main",                 # Window tag
+    save=False,                     # Snapshot current canvas state
+    reload=False,                   # Restore snapshot back to canvas
+    offload=False,                  # Clear canvas from memory (keeps snapshot)
+    new=None,                       # Offload + execute builder_fn()
+    load=None,                      # Restore a different checkpoint by name
+    path=None,                      # Persist/load snapshot file to/from disk (safe pickle)
+    on_save=None,                   # Hook callback fn(ip, state)
+    on_load=None,                   # Hook callback fn(ip, state)
+    properties={}                   # Arbitrary snapshot metadata
+)
+
+Checkpoint Methods:
+    Draw.checkpoint.get(ip) -> CheckpointState
+    Draw.checkpoint.list() -> list[str]
+    Draw.checkpoint.delete(ip)
+    Draw.checkpoint.clear_all()
+
+
+================================================================================
+17. NATIVE QT CONTROLS & LAYOUT BOXES (Draw.widget, Draw.box)
+================================================================================
+
+Draw.widget(
+    ip="btn_submit",                # Unique widget ID
+    type="button",                  # Control type (see list below)
+    display="main",                 # Window tag
+    x=20,                           # Position x
+    y=20,                           # Position y
+    width=120,                      # Control width
+    height=32,                      # Control height
+    text="Submit",                  # Label text
+    checked=False,                  # Toggle state (checkbox/radio)
+    items=["Option 1", "Option 2"], # Selection items (combobox/listbox)
+    value=0,                        # Numeric value (slider/spinbox/progressbar)
+    min_val=0,                      # Minimum range
+    max_val=100,                    # Maximum range
+    on_click=None,                  # Action callback fn()
+    on_toggle=None,                 # Toggle callback fn(is_checked)
+    on_change=None,                 # Change callback fn(new_val)
+    on_select=None                  # Selection callback fn(item_text)
+)
+
+Supported Native Widget Types:
+    "button", "checkbox", "radio", "combobox", "listbox",
+    "slider", "spinbox", "progressbar", "tabs", "scrollarea", "canvas"
+
+Draw.box(
+    ip="sidebar_box",
+    display="main",
+    direction="vertical",           # "vertical" (QVBoxLayout) | "horizontal" (QHBoxLayout)
+    x=10,
+    y=10,
+    width=240,
+    height=500,
+    spacing=8,                      # Inter-widget spacing in pixels
+    children=["btn_submit", ...]    # List of child widget IPs
+)
+
+Widget & Box Control:
+    Draw.widget.get_value(ip) -> Any
+    Draw.widget.set_value(ip, value)
+    Draw.widget.get(ip) -> QWidget
+    Draw.widget.list() -> list[str]
+    Draw.widget.show(ip)
+    Draw.widget.hide(ip)
+    Draw.widget.close(ip)
+    Draw.box.add_child(ip, child_ip)
+    Draw.box.add_stretch(ip)
+
+
+================================================================================
+18. FILE TREE EXPLORER (Draw.filetree)
+================================================================================
+
+Draw.filetree(
+    ip="project_tree",
+    display="main",
+    root_path=".",                  # Root filesystem directory
+    x=20,
+    y=20,
+    width=260,
+    height=400,
+    on_select=None                  # Callback fn(selected_filepath)
+)
+
+Filetree Methods:
+    Draw.filetree.selected(ip) -> str
+    Draw.filetree.refresh(ip)
+    Draw.filetree.get(ip) -> QTreeWidget
+
+
+================================================================================
+19. POINT PATHS & PEN DRAWING (Draw.point, Draw.turtle)
+================================================================================
+
+Draw.point(
+    tag="main",                     # Window tag
+    graph=[800, 600],               # Coordinate space dimensions [w, h]
+    points=[{                       # Sequence of path segments
+        "path": "10,10 ; 100,50 ; 200,180", # Semicolon-delimited coordinate string
+        "colour": "cyan",           # Stroke color
+        "width": 2,                 # Stroke width in pixels
+        "edge": "curve",            # "straight" | "curve"
+        "smooth": "40%",            # Catmull-Rom spline tension
+        "fill": False,              # Close and fill path
+        "fill_colour": "blue",      # Fill color
+        "opacity": 100,
+        "animation": {              # Path drawing animation
+            "line_animation": {"0%-100%": "ease"}
+        }
+    }]
+)
+
+Draw.turtle(display="main", width=800, height=600) -> turtle.RawTurtle
+    Creates a standard library Turtle instance mirrored onto the Qt canvas.
+
+Alias:
+    Draw.pen (alias for Draw.turtle)
+
+
+================================================================================
+20. SYSTEM UTILITIES (Clipboard, File Dialogs, Schedule, Simulation)
+================================================================================
+
+Draw.clipboard.copy(text: str)
+Draw.clipboard.read() -> str
+
+Draw.filedialog.open_file(title="Open", filter="All Files (*.*)") -> str
+Draw.filedialog.open_files(title="Open Files", filter="All Files (*.*)") -> list[str]
+Draw.filedialog.save_file(title="Save As", filter="All Files (*.*)") -> str
+Draw.filedialog.choose_directory(title="Select Folder") -> str
+
+Draw.after(seconds: float, fn: Callable) -> QTimer
+    Runs a callback once after a delay in seconds.
+
+Draw.every(seconds: float, fn: Callable) -> QTimer
+    Runs a callback repeatedly at an interval in seconds.
+
+Draw.simulate.click(display="main", ip="button_ip", button="left")
+Draw.simulate.drag(display="main", ip="shape_ip", dx=100, dy=50)
+Draw.simulate.key(display="main", key="Return")
+
+
+================================================================================
+21. DEBUGGING, WATCHDOG & PROFILING (Draw.debug)
+================================================================================
+
+Draw.debug.safeplay()
+    Activates developer safe mode with recommended watchdog defaults.
+
+Draw.debug.settings() -> DebugSettings
+    Returns configurable runtime threshold settings:
+        .fps_limit = 60             # Target framerate clamp
+        .memory_limit = 4096        # Max process RAM limit in MB
+        .cpu_limit = 90             # Max CPU limit percentage
+        .gpu_limit = 95             # Max GPU limit percentage
+        .render_timeout = 5         # Freeze detection timeout in seconds
+        .show_console = True        # Open live HUD console
+
+Draw.debug.process_monitor() -> dict
+    Returns real-time hardware telemetry:
+        - "cpu_percent"
+        - "memory_rss_mb"
+        - "gpu_usage_percent"
+        - "fps"
+        - "draw_calls"
+        - "vertices"
+
+Draw.debug.log(message: str, level="INFO")
+Draw.debug.fps() -> float
+Draw.debug.memory_usage() -> float
+
+
+================================================================================
+22. GLOBAL CONSTANTS & POSITION TOKENS
+================================================================================
+
+Draw.onwindow : str = "onwindow"
+    Binds layout coordinates relative to window client bounds.
+
+Draw.onscreen : str = "onscreen"
+    Binds layout coordinates relative to physical monitor screen dimensions.
+
+Draw.onip : str = "onip"
+    Binds layout coordinates relative to another shape/widget IP anchor.
+
+
+================================================================================
+23. VISIBILITY OPTIMIZATION ENGINE (Draw.veo / Draw.voe / Draw.dust_remover)
+================================================================================
+
+Draw.veo.set_enabled(enabled: bool)
+    Globally enables or disables visibility culling passes.
+
+Draw.veo.set_occlusion_enabled(enabled: bool)
+    Enables or disables 2D front-to-back occlusion culling.
+
+Draw.veo.get_stats() -> dict
+    Returns real-time optimization statistics:
+        - "total_items": Total scene items
+        - "visible_items": Items passed to render queue
+        - "culled_frustum": Items culled outside viewport
+        - "culled_occlusion": Items occluded behind opaque foreground shapes
+        - "cull_time_ms": Culling execution latency in milliseconds
+        - "init_time_ms": Spatial indexing preprocessing time in milliseconds
+
+Draw.veo.preprocess_scene(shape_items, text_items, cw, ch)
+    Compiles the two-level hierarchical 2D spatial grid and caches static bounds.
+
+Draw.veo.cull_scene(shapes, texts, viewport_w, viewport_h, scroll_x=0.0, scroll_y=0.0) -> list
+    Executes viewport, spatial grid, and occlusion culling, returning compact sorted render queue.
+
+================================================================================
+END OF DRAW-LIB PUBLIC API REFERENCE MANUAL
+================================================================================