Return standard Web objects instead of library-owned wrappers.
Importing a module must not start work or mutate global state.
Prefer leaf-module imports over broad namespace imports.
Use AbortSignal as the shared lifecycle and cancellation protocol.
Do not wrap a modern native API when it is already sufficient.
Do not require a compiler, bundler, package manager, or application runtime.
Do not place legacy-browser fallbacks or deprecated entry points in the core library.
Development tools may be used to test the repository. Consumers receive ordinary, directly importable ESM.
Repository structure
animation/ timing and Web Animations workflowsasync/ asynchronous workflowsbrowser/ browser-level capabilitiescollections/ collection and record workflowscrypto/ Web Crypto workflowsdatetime/ date, time-zone, and duration workflowsdevices/ device and sensor capabilitiesdom/ DOM workflowsencoding/ binary and textual encodingsfiles/ File and Blob workflowsgraphics/ Canvas and color workflowslocalization/ locale and plain-text message workflowsmedia/ media capture workflowsnavigation/ URL/history navigation workflowsnet/ network protocols beyond native fetchstorage/ storage workflowsstreams/ Web Streams workflowselements/ optional Web Componentsadapters/ optional framework adaptersintegrations/ provider-specific APIslabs/ experiments outside the core admission boundaryvendor/ isolated third-party sourceexamples/ browser examplesdocs/ architecture and project decisions
The allowed dependency direction is:
Web Platform <- capability modules <- elements / adapters / integrations / examples
Capability modules must never depend on optional layers, labs/, or vendor/.
Optional adapters may use pinned bare package specifiers. Browser consumers of
those adapters own the corresponding import map; capability modules remain
dependency-free.
Current usage
Use relative paths while developing against this checkout and import the narrowest module that provides the capability:
import { delay } from './async/delay.js';import { on } from './dom/events.js';import { $ } from './dom/query.js';on($('#save'), 'click', save);
For an immutable release-candidate URL, replace the relative prefix with https://cdn.jsdelivr.net/gh/lsongdev/scripts@v0.1.0-rc.1/. A floating latest URL is not recommended for production use.
The same files are published to npm unchanged, with no bundle and no entry point; import leaves by path:
npm install @lsongdev/scripts@next
import { delay } from '@lsongdev/scripts/async/delay.js';
Compatibility policy
Core modules target the standard API directly. Vendor-prefixed APIs, deprecated signatures, forwarding files, and behavior compatibility are not maintained in the core.
When a downstream environment lacks a required capability, the downstream application may choose a separate adapter or polyfill. Such compatibility code must not become a transitive dependency of this library. See the full roadmap and compatibility policy.
Status
The project is currently in the boundary and correctness phases of the roadmap:
classify every module;
make imports inert and dependencies one-directional;
remove native reimplementations and incomplete APIs;
add contract tests and real-browser tests;
publish a deliberately small, immutable versioned surface.
No module is stable until those gates are satisfied.
Verification
Run the repository gate before committing:
npm run check
On a new development machine, install the pinned test dependencies and browser engines once:
npm cinpx playwright install
The local gate checks JavaScript syntax, relative-import resolution, local HTML assets, the absence of root-level JavaScript entry points, core dependency direction, the Node contract suite, core import smoke tests, the browser contract harness, and representative examples in Chromium and WebKit. CI additionally runs the same browser suite in Firefox. Playwright and its browser binaries are development-only; published modules have no runtime dependency on them.