Code‐from‐Phone - amark/gun GitHub Wiki

🤳 Code from Phone (CfP)

CfP_Hero_v6A

We love keyboards, but sometimes we're on the go and don't have our laptop, or its just easier to pull out our phone...so wouldn't it be super nice to have an epic mobile code editor that's fun to use?

🤳 Code from Phone (CfP) reimagines coding as a fun, calculator-like experience. Instead of typing every character on a cramped keyboard, you tap buttons and drag modular “bricks” to form code. This lets you focus on the logic of your program rather than the mechanics of typing while always preserving the full fidelity of your code under the hood.

1. Introduction

1.1 Developer-Focused Overview

🤳 Code from Phone is a mobile-first AST Editor that reimagines code as modular, editable "bricks" rather than raw text strings. It captures both logic and stylistic metadata (like indentation or variable keywords), allowing you to then change how the code looks (for example, hiding const vs. var, or rendering deeply nested calls as streamlined left-to-right pipelines) without altering its underlying logic.

Early-Stage Project: Many of the features described here have not been built yet.

2. Key Features

  1. AST-Centric Editing

    • Treats code as a structured hierarchy (AST), not raw text, so that we can manipulate syntax directly.
    • Preserves all “decorative” details (indentation, spacing, etc.) to enable exact round-trip export.

  2. Brick Model

    • Every statement or expression is a “brick.”
    • Left Decorators (e.g., var, async, function) and Right Decorators (e.g., ), }, ;) wrap around these bricks.

  3. Powerful Theming

    • Themes can hide or show decorators (e.g., hide var, show const, remove semicolons) without permanently altering the code.
    • Renders deeply nested code as a “pipeline” or “chain” for easier readability.

  4. Flexible Export & Transformations

    • By default, re-exporting code preserves original formatting.
    • Developers can opt into style changes (e.g., switching tabs/spaces, standardizing var vs. let vs. const, removing semicolons).
    • Potentially advanced transformations (e.g., rewriting while loops to recursion, or converting JS to another language) can be built on top of the AST structure.

3. High-Level Design

3.1 AST as the Foundation

  • Parsing

    • The project relies on an underlying parser to generate a JavaScript AST.
    • We aim to enhance this parser to retain whitespace, indentations, and other lexical features typically discarded.

  • Bricks

    • Each AST node (e.g., an expression, a function, a block) is viewed as a “brick.”
    • Bricks can contain decorators on the left (e.g., var, indentation, async) and right (e.g., semicolons, parentheses).

3.2 Decorators & Sequences

  • Left Decorators

    • Everything before the core expression/statement (e.g., var, const, function, indentation).
    • This separation allows easy toggling: hide or change function to func, switch from var to let, or preserve indent style.

  • Right Decorators

    • Everything that closes or terminates a statement/block (e.g., semicolons, braces, parentheses).
    • Also used for advanced patterns, like linking subtrees into a “chain” view if you want to display code as left-to-right pipelines.

  • Sequences

    • The “body” or main content between left and right decorators—essentially the heart of the code (e.g., the expression or block logic).

3.3 Mobile Interface Goals

  • Structural Editing

    • Tapping or dragging “bricks” is easier on touch screens than pinpoint text selection.
    • Syntactic errors are harder to introduce when code is manipulated at the AST level.

  • Collapsible Decorators

    • Because each node has these extra tokens, a mobile interface can hide or show them to reduce clutter (e.g., indentation, semicolons) until specifically needed.

4. Theming & Transformations

4.1 Theming Engine

  • Hidden vs. Visible Decorators

    • Themes can define whether to display or mask decorators (e.g., “Hide all var/const/let so code looks more minimal”).
    • Upon export, the original tokens reappear in the text if the developer opts to preserve them.

  • Custom Display Text

    • A theme could replace function with func, replace semicolons with line breaks, etc.
    • Even though visually changed, the underlying AST remains valid JavaScript.

  • Pipe/Chain Rendering

    • For nested calls, a theme can “unwind” them so that code flows left to right in a pipeline style.
    • This is purely a display choice: The original AST and exported code still nest the calls normally.

4.2 Exporting & Style Preservation

  • Default: Non-Destructive

    • By default, re-exporting code does not alter the text’s styling: same indentation, variable declarations, etc.
    • This avoids unwanted diffs in version control.

  • Optional Style Changes

    • The editor can unify all declarations to var or switch them to let/const.
    • Spaces ↔ Tabs, semicolon insertion/removal, arrow functions ↔ standard functions, etc.

  • Potential Language Conversions

    • Because decorators capture so much structure, the system could (in theory) export JS code to other languages if you supply the right transformation logic.
    • (This is not a primary focus but exemplifies the extensibility of the AST approach.)

5. Technical Deep-Dive

5.1 Parser & Metadata

  • Esprima

    • Provides a JavaScript AST.
    • We will add custom fields to track whitespace, indentation levels, semicolons, etc.

  • Preserving Whitespace & Indentation

    • This is crucial for perfect round-trip. We store whitespace as part of the “left decorator” or in a specialized field.
    • The user can choose whether to see or ignore indentation in the UI.

5.2 Graph-Like Extensions

  • AST Graph

    • Normally, an AST is a strict hierarchy, but certain advanced theming can effectively create “pointers” from one node’s right decorator to another subtree, flattening nested calls into a chain.
    • The main tree remains intact; we’re just introducing references to help the UI display it differently.

  • Avoiding Infinite Loops

    • Any cycle-creation for “chained” displays must be guarded by a check so we don’t render the same subtree repeatedly.

5.3 Sample Workflows

  1. Basic Editing

    • User loads a .js file.
    • Parser creates the AST, attaching indentation, semicolons, etc. as decorators.
    • The editor displays a clickable tree of bricks.
    • The user taps a “brick” to modify it (e.g., rename variables, rearrange statements).

  2. Re-Export

    • “Export as text” reassembles the code with all original indentation/tokens unless the user chooses a style transformation.
    • The resulting text can be used in any normal JS environment or version control.

6. Next Steps for the Team

  • Core AST → UI Rendering
    Build the “brick” representation in the UI.
    Let each node have left decorators, main body (sequence), and right decorators.
    Verify that we can easily hide or show tokens like var, function, and semicolons.

  • User Interaction Model
    Prototype how a user taps and drags these bricks on a phone screen.
    Ensure we can do basic structural edits without forcing raw text editing.

  • Theming System
    Start with a basic theme (exactly mirrors the JS code).
    Add a second theme that hides certain decorators (e.g., semicolons, var).
    Demonstrate that re-exporting remains faithful to the original code unless a user intentionally changes style settings.

  • Longer-Term Possibilities
    Advanced theming (e.g., pipeline rendering).
    Language transformations (JS → Rust, or rewriting loops → recursion, etc.).
    Collaboration features, storing AST changes in a real-time database (e.g., GUN.js).

7. Contributing

We welcome all contributions to 🤳 Code from Phone (CfP)! Feel free to open issues or submit pull requests on GitHub. Whether you have ideas for new features, spot a bug, or simply want to improve the documentation, your help is appreciated. Together, we can build a more intuitive, structural way to code on the go.