Caspian VS Code Extension

Caspian is a VS Code extension that delivers an HTML-first developer experience for the Caspian ecosystem: Caspian templates, PulsePoint client reactivity, Python components, and Next.js-style file-based routing—without forcing you into a large directive surface area or a build-heavy workflow.

It focuses on one thing: make editing Caspian apps feel as productive as JSX, while keeping your codebase in clean, separable HTML + Python + CSS.

Highlights

Template expressions { ... } in HTML treated as embedded JavaScript:
- syntax highlighting, IntelliSense, and diagnostics
PulsePoint API IntelliSense + hover inside <script> (e.g., pp.)
PulsePoint directive attribute completion (pp-*)
Component IntelliSense (tags + props) backed by a project component map
Auto-import for components using  directives (JSX-like workflow)
Routing intelligence (Next.js-like):
- route completions in href="", src="", and pp.redirect(...)
- Python completions for redirect("...")
- hover, diagnostics, and go-to-definition (F12 / Ctrl+Click)

What this extension is for

If your app looks like this:

HTML files as the UI surface
PulsePoint for reactivity in <script>
Python for component logic and server endpoints
File-based routing under src/app/

…then Caspian provides the missing DX layer: IntelliSense, navigation, and guardrails so you can move quickly without losing correctness.

Feature set

1) Template expressions `{ ... }` (Caspian templates)

Caspian treats single-brace blocks in HTML as embedded JavaScript.

Example:

<script>
  const [count, setCount] = pp.state(0);

  function increment() {
    setCount(count + 1);
  }
</script>

<div class="counter">{count + 1}</div>

DX benefits

You get JavaScript-like IntelliSense while staying in HTML.
Invalid JavaScript inside { ... } is reported as a diagnostic.

What IntelliSense includes

Variables discovered from the <script> block (including pp.state(...) patterns)
Function names extracted from the <script> block
Common JS globals (Date, Math, JSON, console, etc.)

2) PulsePoint completions inside `<script>`

Inside an HTML <script> block, typing a trailing dot triggers PulsePoint suggestions:

<script>
  pp.
</script>

DX benefits

Faster discovery of the PulsePoint surface area
Inline documentation via hover

3) PulsePoint attribute completion (`pp-*` directives)

Inside HTML tags, Caspian suggests common PulsePoint directives such as:

pp-component
pp-spread
pp-ref
pp-ignore
pp-for

When a pp-for loop is present, Caspian also suggests a key="..." attribute for list rendering patterns.

DX benefits

Reduces typo-driven bugs
Makes directive usage discoverable (especially for new team members)

4) Component IntelliSense (tags + props) with JSX-like auto-import

Caspian supports a component map file (see “Project requirements”) that describes discovered components and their props.

You get:

4.1 Tag completion (component names)

Type < and start writing a component:

<But

Caspian suggests known components and can auto-insert the import directive if missing.

4.2 Props completion (with required/default info)

Inside a component tag, Caspian suggests props based on the component map:

<button variant="" size=""></button>

4.3 Auto-import via directives (grouped)

Imports are expressed as HTML comments:

<!-- @import Button from ./components/Button.py -->
<!-- @import Test from ./components/Test.py -->

The extension can also group imports into a compact form (JSX-like ergonomics):

<!-- @import { Button, Test } from ./components -->

4.4 Quick Fix: “Import component …”

If you type a component tag that is not imported, you can use Quick Fix (Ctrl+.) to insert the correct import directive.

4.5 Authoring a Caspian component (Python)

Caspian components are plain Python functions decorated with @component. They are designed to feel familiar to JSX users.

Scaffold instantly (VS Code snippet): In a Python file, type caspcomp and accept the snippet suggestion (Tab/Enter). It inserts the boilerplate pattern shown below, including **props, children, class merging, and attribute rendering.

It follows a few conventions:

**props captures any additional HTML attributes (similar to JSX ...props)
children is treated as a special prop for inner content
merge_classes(...) safely combines your defaults with an incoming class
get_attributes(...) converts the final props dict into a valid HTML attribute string

Example:

from utils.html_attrs import get_attributes, merge_classes
from utils.component_decorator import component


@component
def Untitled1(**props):
    incoming_class = props.pop("class", "")
    final_class = merge_classes("", incoming_class)

    children = props.pop("children", "")

    attributes = get_attributes(props, {
        "class": final_class
    })

    return f'<div {attributes}>{children}</div>'

Usage in HTML:

<!-- @import Untitled1 from ./components/Untitled1.py -->
<Untitled1 class="p-4 rounded-lg">Hello from Caspian</Untitled1>

DX benefits

You don’t need to manually hunt file paths
Imports stay consistent and tidy
Tag/prop completion feels familiar to React/JSX users

5) Next.js-style file-based routing intelligence

Caspian provides route intelligence based on a precomputed file list (see “Project requirements”).

It supports:

5.1 Route completions in HTML

href="..."
src="..."
pp.redirect("...") (PulsePoint redirects in HTML)

Routes are derived from files like:

src/app/index.html → /
src/app/(auth)/signin/index.html → /signin (route group ignored in URL)
src/app/users/[id]/index.html → /users/{id}
src/app/docs/[...slug]/index.html → /docs/{...slug}

Dynamic routes are inserted with snippet placeholders, so you can tab through parameters.

5.2 Static asset completions

Paths are also suggested for assets under public/:

/css/styles.css
/js/app.js
/assets/logo.svg

5.3 Hover + diagnostics

For href/src/redirect targets, Caspian can:

show the resolved file on hover
warn when a referenced route or asset does not exist

External links (e.g., https://..., mailto:..., #...) are ignored by validations and completions.

6) Go to Definition (F12 / Ctrl+Click) for routes and redirects

Caspian enables navigation to source files from:

HTML: href="...", src="...", pp.redirect("...")
Python: redirect("...")-style strings

DX benefits

Jump from a link/redirect straight into the route file
Faster refactors and safer restructuring

Supported files / language modes

HTML (.html) — primary mode
Jinja templates (jinja, jinja-html) — importer completions + component workflow support
Python (.py) — Flask redirect route completions/hover/definition

Project requirements (how the extension “knows” your app)

Caspian’s advanced features intentionally depend on explicit, generated project metadata rather than scanning the full project on every keystroke.

1) `settings/files-list.json` (routes + assets)

This file should contain a JSON array of project file paths (POSIX-like or Windows paths are normalized).

It powers:

route completion/diagnostics/definition
static asset completion/diagnostics/definition

2) `settings/component-map.json` (components + props)

This file should contain discovered components and their prop metadata.

It powers:

component tag suggestions
prop suggestions (including defaults and “required” indication)
auto-import suggestions

Both files are watched for changes and reloaded automatically.

Recommended VS Code settings

To get completions inside HTML comments for @import, enable quick suggestions in comments:

"editor.quickSuggestions": {
  "comments": "on",
  "strings": "on",
  "other": "on"
}

Known limitations

Some features depend on settings/files-list.json and settings/component-map.json. If they are missing or stale, suggestions will be incomplete.
Routing intelligence is intentionally opinionated: it targets src/app/**/index.(html|py) entry files.
Route groups (group) are supported as organizational folders and are ignored in the final URL.

Roadmap (planned / high-value additions)

Broader PulsePoint directive coverage (more pp-* attributes + richer docs)
Smarter route refactors (rename/move route, update all references)
Better multi-root workspace support
Richer component docs (docstrings -> hover, prop types -> completion)
Full “Caspian init” command wiring (bootstrap + generation of metadata files)

Contributing

Contributions are welcome.

Open an issue with a minimal repro (sample .html / .py helps)
Or submit a PR with a focused change and short description

Author

Jefferson Abraham — thesteelninjacode@gmail.com

License

MIT — see LICENSE.

Caspian

Jefferson Abraham Omier

Caspian VS Code Extension

Highlights

What this extension is for

Feature set

1) Template expressions { ... } (Caspian templates)

2) PulsePoint completions inside <script>

3) PulsePoint attribute completion (pp-* directives)

4) Component IntelliSense (tags + props) with JSX-like auto-import

4.1 Tag completion (component names)

4.2 Props completion (with required/default info)

4.3 Auto-import via directives (grouped)

4.4 Quick Fix: “Import component …”

4.5 Authoring a Caspian component (Python)

5) Next.js-style file-based routing intelligence

5.1 Route completions in HTML

5.2 Static asset completions

5.3 Hover + diagnostics

6) Go to Definition (F12 / Ctrl+Click) for routes and redirects

Supported files / language modes

Project requirements (how the extension “knows” your app)

1) settings/files-list.json (routes + assets)

2) settings/component-map.json (components + props)

Recommended VS Code settings

Known limitations

Roadmap (planned / high-value additions)

Contributing

Author

License

1) Template expressions `{ ... }` (Caspian templates)

2) PulsePoint completions inside `<script>`

3) PulsePoint attribute completion (`pp-*` directives)

1) `settings/files-list.json` (routes + assets)

2) `settings/component-map.json` (components + props)