Caspian VS Code Extension

Caspian is a VS Code extension for Caspian HTML templates, PulsePoint client code, Python components, and file-based routing.

The current implementation is strongest in HTML files inside a Caspian workspace. It adds completions, hover, definitions, diagnostics, quick fixes, and rename support around the parts of the framework that are already represented in generated project metadata.

Highlights

Single-brace template expressions in HTML with IntelliSense, hover, and JS syntax diagnostics
PulsePoint script tooling for pp. and this. inside <script> blocks
PulsePoint and Caspian directive completions inside HTML tags and <template> tags
Component workflow tooling powered by settings/component-map.json:
- component tag and prop completions
- grouped @import rewrites and quick fixes
- hover and go-to-definition for imported components
- diagnostics for missing imports, duplicate aliases, invalid props, and more
Route and asset tooling powered by settings/files-list.json:
- completions, hover, diagnostics, definitions, and document links
- support for HTML links, pp.redirect("..."), and Python redirect("...")
Global helper IntelliSense from .casp/global-functions.d.ts
PulsePoint state rename support inside HTML documents
caspcomp Python snippet for authoring Caspian components

Activation Model

The extension has two modes:

1) Full workspace mode

Full Caspian services boot only when the workspace root contains:

{}

saved as caspian.config.json.

When that file exists, the extension enables:

HTML template diagnostics and completions
component map loading and watchers
route and asset tooling
global helper loading from .casp/global-functions.d.ts
component diagnostics, quick fixes, hover, definitions, and rename support

2) Snippet-only mode

Without caspian.config.json, the full Caspian providers stay dormant.

The caspcomp snippet still works in:

Python files
plain text / untitled files

Current Feature Set

1) Template expressions in HTML

Caspian treats single-brace expressions in HTML as JavaScript-like template expressions.

Example:

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

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

<div>{count + 1}</div>

What the extension currently provides:

completions for state variables discovered from the page <script> block
completions for functions discovered from the page <script> block
completions for common JS globals such as Date, Math, JSON, and console
object-property completions for state like {user.}
loop-alias completions inside pp-for scopes
hover for state variables and functions inside mustache expressions
diagnostics for invalid JavaScript inside single-brace expressions

The validator intentionally skips:

HTML comments
Jinja-style {{ ... }}, {% ... %}, and {# ... #} blocks
excluded regions such as <script>, <style>, and pp-ignore-style parser exclusions

2) PulsePoint tooling inside `<script>`

Inside HTML <script> blocks, typing pp. or this. offers the current PulsePoint API surface.

The shipped completions currently include:

state
effect
layoutEffect
ref
memo
callback
reducer
context
provideContext
portal
props
createContext
mount
redirect
rpc
enablePerf
disablePerf
getPerfStats
resetPerfStats

Hover documentation is available for PulsePoint methods inside <script> blocks.

3) Directive completions in HTML

For ordinary HTML tags, the current PulsePoint directive completion set is:

pp-component
pp-spread
pp-ref
pp-loading-content
pp-loading-url
pp-loading-transition
pp-reset-scroll
pp-spa

For <template> tags, the extension currently suggests:

pp-for
casp-for
casp-if
casp-elif
casp-else

When the cursor is inside a pp-for loop scope, it also suggests a key="..." attribute.

4) Component imports, completions, hover, and diagnostics

Component tooling is driven by settings/component-map.json.

Supported import styles include exact-file and grouped directory imports:

<!-- @import Button from ./components/Button.py -->
<!-- @import Button as PrimaryButton from ./components/Button.py -->
<!-- @import { Button, Card as ProfileCard } from ./components -->

What the extension currently does:

component tag completion in HTML
auto-import edits that rewrite or merge grouped @import headers
prop-name completion for imported components
literal and boolean-ish value suggestions when prop metadata provides options or Literal[...] / bool
hover for component tags and component props
go-to-definition from component tags and from @import identifiers and paths
quick fix: Import component "..."

Current component diagnostics include:

component used but not imported
unresolved component import path or symbol
duplicate component aliases
unused imported components
missing required props
invalid prop values
unexpected props on components that do not accept arbitrary attributes
children passed to components that do not accept children
multiple top-level HTML roots in the same file

The grouped import rewrite logic preserves aliases such as Button as PrimaryButton when merging imports.

5) Global helper functions

If the workspace contains .casp/global-functions.d.ts, the extension loads helper function signatures from that file and exposes them inside:

HTML mustache expressions
HTML <script> blocks

It currently provides:

completion
hover
go-to-definition

The loader expects definitions in this shape:

// @source: ./helpers/format
const formatPrice: (value: number) => string;

The @source comment is used to resolve definition targets.

6) File-based routing and asset intelligence

Routing and asset tooling is driven by settings/files-list.json.

Recognized route entries are derived from:

src/app/index.py or src/app/index.html -> /
src/app/(auth)/signin/index.py -> /signin
src/app/users/[id]/index.py -> /users/{id}
src/app/docs/[...slug]/index.py -> /docs/{...slug}

Route groups such as (auth) are ignored in the public URL.

Current route and asset support includes:

HTML completions in double-quoted href="..."
HTML completions in double-quoted src="..."
HTML completions in pp.redirect("...")
Python completions in redirect("...")
hover for route targets and static assets
diagnostics for missing routes and missing static assets
go-to-definition for routes and assets
document links for href routes and src assets

Dynamic routes are inserted as snippets so you can tab through parameters.

The provider also supports query-parameter fallback matching for dynamic routes, so links such as /users?id=123 can still resolve to /users/{id} when the route metadata matches.

7) Rename support for PulsePoint state

Inside HTML documents, the rename provider supports PulsePoint-oriented symbol updates.

Current behavior:

renaming a program-scope pp.state(...) variable updates both the state variable and its derived setter
matching references in the page <script> block are updated
matching references in HTML markup are updated
local script-scope renames stay local instead of rewriting markup state names

This is document-scoped rename behavior for HTML files, not a general workspace-wide rename engine.

8) Python component snippet

In Python or plain text files, typing caspcomp inserts a Caspian component scaffold.

The snippet is designed around common component conventions such as:

**props
children
class merging
attribute rendering

Supported File Types

HTML: full Caspian feature set
Python: Flask-style redirect("...") completions, hover, definitions, plus the caspcomp snippet
Plain text / untitled: caspcomp snippet only
Jinja / Jinja HTML: importer directive completions inside HTML comments

Jinja support is currently limited. The full HTML provider stack is not registered for Jinja language modes.

Project Metadata

Caspian intentionally depends on explicit generated metadata instead of scanning the whole workspace on every keystroke.

1) `caspian.config.json`

This file is the switch that enables full Caspian workspace services.

2) `settings/component-map.json`

This file should contain an array of component records similar to:

[
  {
    "componentName": "Button",
    "filePath": "C:/project/src/components/Button.py",
    "relativePath": "src/components/Button.py",
    "importRoute": "src.components.Button",
    "acceptsArbitraryProps": true,
    "props": [
      {
        "name": "size",
        "type": "Literal['sm', 'lg']",
        "hasDefault": false,
        "options": ["sm", "lg"]
      }
    ]
  }
]

It powers:

component tag and prop completion
hover and definition resolution for imports and tags
import quick fixes and grouped import rewrites
component diagnostics

3) `settings/files-list.json`

This file should contain a JSON array of known project files. Both Windows and POSIX-style paths are normalized.

It powers:

route completion
static asset completion
route and asset diagnostics
hover, definitions, and document links for routes and assets

4) `.casp/global-functions.d.ts` (optional)

This file is optional. If present, it powers global helper completion, hover, and definitions.

All of these metadata files are watched and reloaded automatically when they change.

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

Full Caspian services do not boot until caspian.config.json exists at the workspace root.
Most advanced features are registered only for HTML documents, not Jinja documents.
HTML route and asset tooling currently targets double-quoted href and src attributes.
pp.redirect("...") and Python redirect("...") support currently targets string literals, not arbitrary computed expressions.
Route detection is intentionally opinionated around src/app/**/index.py and src/app/**/index.html entry files.
If settings/component-map.json, settings/files-list.json, or .casp/global-functions.d.ts are missing or stale, related suggestions and navigation will be incomplete.

Roadmap

broader Jinja-language coverage beyond importer comment completions
richer component documentation in hover text
smarter route refactors and rename/move workflows
better multi-root workspace behavior
workspace bootstrap tooling for generating Caspian metadata files

Contributing

Contributions are welcome.

Open an issue with a minimal repro.
Submit a focused PR with tests when behavior changes.

Author

Jefferson Abraham — thesteelninjacode@gmail.com

License

MIT — see LICENSE.

Caspian

Jefferson Abraham Omier