================================================================================
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
================================================================================
