Experimental APIs

Everything that steps outside the intrinsic layout model is gated, not blocked.

What counts as experimental

ARKlight's default surface is built entirely on the intrinsic layout model: flexbox/grid sizing keywords and the

.stack

.cluster

.switcher

.grid

.sidebar

utility classes from

styling and layout

. Nothing in that model is keyed to a viewport width, device class or browser engine. Any feature that steps outside it is, by definition, an experimental API -- there is no "experimental by convention" bucket; if it isn't registered, it isn't flagged.

Feature	What it is	Why it's gated
css-media-queries	Site.media_query(...), and a per-node responsive_style={...} prop.	Keyed to viewport width/height/orientation -- a deliberate tradeoff against the intrinsic model, not a missing feature.
experimental-install-pwa	A native browser install-prompt button (arklight pwa ... --install-button).	Depends entirely on beforeinstallprompt support in the visiting browser engine.
css-import	Site.import_style(url), a real @import url(...) statement.	Fetched and applied by the browser at request time; ARKlight can't validate the imported file's contents the way it validates everything it generates itself.
script-extension	A ScriptExtension subclass, registered with site.register_script_extension(...).	Hand-written JavaScript: no eval or new Function, but also no syntax guarantee.
provider-integration	Site(provider=Provider.declare(name=..., capabilities=[...])).	The declared external service is entirely outside anything ARKlight can validate; the contract is only an interface.
provider-scripts	Page(scripts=[{"src": "..."}]), loading a real vendor SDK.	The referenced script is fetched and run at request time, same reasoning as css-import.
raw-postprocess	Removed. Calling it only logs a pointer to script-extension.	Used to hand the entire build output to an unchecked function; kept registered for historical reasons only.

script-extension: the one you'll actually reach for

It is the sole surviving successor to the now-removed

raw-postprocess

, and covers the job most of those uses were actually for: hand-written JS alongside

arklight.js

. You subclass

ScriptExtension

, and its

script

is restricted to the

<script>

portion of a Svelte-single-file-component-style block -- a

<template>

<style>

block is refused outright, not just warned. ARKlight lowers only that block to plain JS text and appends it to

arklight.js

; it never writes an arbitrary output file the way

raw_postprocess

used to.

Usage is expected to carry a

#include <expapilib.ARKlight>

marker comment in the subclass's own source file. Its absence doesn't block the build -- it just adds one more warning on top of the normal experimental banner.

How it surfaces at build time

Every registered experimental feature prints an inline banner the moment it's detected, interleaved with the normal

[ARKlight]

stage log, plus one end-of-run summary block per distinct feature actually used (not once per occurrence). It also shows up in

sbom.txt

and is discoverable with

arklight search <name>

WARNING: [EXPERIMENTAL FEATURE ACTIVE]: Component 'Button' unlocked an experimental API.
   -> Feature: experimental-install-pwa
   -> Note: Runtime stability relies entirely on native browser engine support.

Why gate instead of block

ARKlight could simply refuse to offer these. It doesn't, because each is a legitimate answer to a real constraint -- a design that genuinely must key off viewport characteristics, a PWA that wants a native install affordance. Gating keeps the default path entirely intrinsic (nobody hits this without opting in by name) while making the tradeoff visible at build time, every time, rather than a landmine found later on a device nobody tested.

See

why ARKlight

for the honest limits this trades against, or

the CLI

for the

--debug

--verbose

flags that print every build stage.

Experimental APIs

What counts as experimental

script-extension: the one you'll actually reach for

How it surfaces at build time

Why gate instead of block

Related