-
-
Notifications
You must be signed in to change notification settings - Fork 0
API‐Reference
Complete reference for all classes, methods, and functions.
Main class for content analysis.
WispScanner(html_content: str)Parameters:
-
html_content(str): HTML string to analyze
Example:
scanner = WispScanner('<html><body><p>Test</p></body></html>')Performs complete content analysis.
Returns: ContentAnalysis named tuple containing:
-
context(str): 'narrative', 'dashboard', 'form', or 'minimal' -
pattern(str): 'prose', 'structured', 'technical', or 'navigational' -
density(float): 0.0 to 1.0 -
depth(int): Maximum DOM nesting level
Example:
result = scanner.analyze()
print(result.context) # 'narrative'Calculates text-to-element density.
Returns: Float between 0.0 and 1.0
Example:
density = scanner.analyze_content_density()Identifies content pattern type.
Returns: One of: 'prose', 'structured', 'technical', 'navigational'
Determines presentation context.
Returns: One of: 'narrative', 'dashboard', 'form', 'minimal'
Calculates maximum DOM nesting.
Returns: Integer depth level
Generates complete CSS output.
Parameters:
-
analysis(ContentAnalysis, optional): Use specific analysis, or use internal
Returns: CSS string with variables and base styles
Example:
css = scanner.generate_css()
# Or with custom analysis:
css = scanner.generate_css(custom_analysis)Generates only CSS variables.
Returns: Dictionary of variable names to values
Example:
vars = scanner.generate_css_variables()
# Returns: {'--wisp-context': 'narrative', ...}Named tuple returned by analysis methods.
Fields:
density: floatpattern: strdepth: intcontext: str
Class for fetching and processing remote URLs.
WispFetcher(url: str, selector: str = None)Parameters:
-
url(str): URL to fetch -
selector(str, optional): CSS selector for content extraction
Retrieves remote content.
Returns: True if successful, False otherwise
Example:
fetcher = WispFetcher('https://example.com')
if fetcher.fetch():
# Process contentExtracts main content from fetched HTML.
Returns: HTML string of extracted content
Performs analysis on fetched content.
Returns: Dictionary with:
-
analysis: ContentAnalysis object -
scanner: WispScanner instance -
content: Extracted HTML -
title: Page title -
url: Source URL
Generates CSS from fetched content.
Parameters:
-
minify(bool): Whether to minify output
Returns: CSS string
Generates complete standalone HTML.
Parameters:
-
inline_css(bool): Whether to inline CSS or link externally
Returns: Complete HTML document as string
Browser runtime object available after loading wisp.js.
Returns version string.
console.log(Wisp.version); // '0.1.0'Configuration defaults.
Wisp.defaults = {
densityThreshold: { low: 0.3, high: 0.7 },
motionPrefers: boolean
};Analyzes container and applies styling.
Parameters:
-
container(HTMLElement): Root element to analyze (default: body)
Returns: Analysis result object with:
-
context: Detected context -
pattern: Detected pattern -
density: Density value
Example:
const result = Wisp.scan();
console.log(result.context); // 'narrative'
// Scan specific element
const article = document.querySelector('article');
Wisp.scan(article);Returns analysis without applying styles.
Returns: Object with density, pattern, depth, context
Generates CSS variable mappings.
Returns: Object mapping variable names to values
Wisp automatically scans on DOMContentLoaded. To prevent this:
<script>
window.WispAutoInit = false;
</script>
<script src="wisp.js"></script>
<script>
// Manual init later
Wisp.scan();
</script>Command-line interface for fetching and optimizing URLs.
wisp-fetch <URL> [options]Positional:
-
URL: Target webpage URL (required)
Options:
-
-o, --output: Output file path -
-c, --css-only: Output CSS only (no HTML wrapper) -
-m, --minify: Minify output -
-s, --selector: CSS selector for content extraction -
--open: Open result in browser (macOS only)
-
0: Success -
1: Network error or invalid URL -
2: File system error
Static CSS generator module.
python -m src.cli.bake <input.html> <output.css> [context]-
input.html: Source HTML file -
output.css: Output CSS file path -
context(optional): Force specific context ('narrative', 'dashboard', 'form', 'minimal')
Build automation script.
Functions:
-
build(): Main build process - File copying and minification
- Size reporting
Usage:
python scripts/build.pyDashboard HTML generator.
Functions:
-
generate_dashboard(output_dir='public'): Creates analysis dashboard
Usage:
python scripts/generate_dashboard.py| Value | Description | Triggers |
|---|---|---|
narrative |
Long-form reading | >50% paragraphs |
dashboard |
Data-dense UI | Tables, 4+ cards |
form |
Input collection | ≥2 form controls |
minimal |
General purpose | Default fallback |
| Value | Description | Elements |
|---|---|---|
prose |
Paragraph-heavy |
<p> dominant |
structured |
List-heavy |
<ul>, <ol> dominant |
technical |
Code-heavy |
<pre>, <code> dominant |
navigational |
Heading-heavy |
<h1>-<h6> dominant |
| Variable | Type | Description |
|---|---|---|
--wisp-context |
string | Detected context name |
--wisp-pattern |
string | Detected pattern name |
--wisp-density |
number | 0.0 - 1.0 |
--wisp-depth |
integer | DOM nesting level |
--wisp-spacing-unit |
length | Base spacing (rem) |
--wisp-line-height |
number | Line height multiplier |
--wisp-max-width |
length | Content max-width |
--wisp-base-font |
length | Base font size |
--wisp-motion |
time | Transition duration |
| Variable | Default | Description |
|---|---|---|
--wisp-fg |
#1a1a1a | Text color |
--wisp-bg |
#ffffff | Background color |
--wisp-muted |
#666666 | Secondary text |
--wisp-accent |
#0066cc | Primary accent |
--wisp-border |
rgba(0,0,0,0.1) | Border color |
--wisp-xs |
0.25rem | Extra small spacing |
--wisp-sm |
0.5rem | Small spacing |
--wisp-md |
1rem | Medium spacing |
--wisp-lg |
1.5rem | Large spacing |
--wisp-xl |
2rem | Extra large spacing |