@lightspeed-js/core 0.1.0

package/dist/types/src/ssg/rebuild.d.ts

@@ -0,0 +1,49 @@
+import type { ComponentDefinition } from "../runtime/components/index.js";
+/**
+ * Re-render built pages against fresher content, without the bundler.
+ *
+ * `fetchAt: "build"` content is exactly as stale as the last build (ADR-013),
+ * so publishing a corrected paragraph would otherwise mean rebuilding the whole
+ * site. The intended shape is a CMS webhook naming what changed, and only the
+ * pages that read it being re-rendered.
+ *
+ * Nothing about the JavaScript or CSS changes, so none of it is rebuilt: the
+ * shells recorded at build already carry the hashed asset tags, and the same
+ * `renderPage` runs over them again.
+ */
+export interface RebuildOptions {
+    /** Build output directory - where re-rendered pages are written. */
+    dist: string;
+    /**
+     * The build manifest, if it is not at `.lightspeed/manifest.json`.
+     *
+     * It lives outside `dist` because it is build metadata, not site output:
+     * page shells alone were ~17% of a deployed build that nobody fetches. A
+     * build agent has the working tree, so it has this.
+     */
+    manifest?: string;
+    /** Component definitions, compiled from source. */
+    definitions: ComponentDefinition[];
+    /**
+     * Restrict to pages reading this content key - what a webhook would pass.
+     * Omitted, every page with build-time content is re-rendered.
+     */
+    cell?: string;
+    /** Restrict to named pages, e.g. `blog.html`. Wins over `cell`. */
+    pages?: string[];
+    css?: "inline" | "external";
+}
+export interface RebuildResult {
+    /** Pages written, in the order they were rendered. */
+    rebuilt: string[];
+    /** Paths that did not exist before - new entries. */
+    added?: string[];
+    /** Paths whose entry is gone; their files were deleted. */
+    removed?: string[];
+    /** Pages considered and skipped, with why. */
+    skipped: Array<{
+        page: string;
+        reason: string;
+    }>;
+}
+export declare function rebuildPages(options: RebuildOptions): Promise<RebuildResult>;

package/dist/types/src/ssg/render.d.ts

@@ -0,0 +1,104 @@
+import type { ComponentDefinition } from "../runtime/components/index.js";
+/**
+ * Render a page's islands to HTML at build time.
+ *
+ * Runs the **real runtime** against a DOM rather than reimplementing rendering:
+ * `$for`, `$if`, props, blocks and bindings all behave identically for free,
+ * and there is no second renderer to drift.
+ *
+ * jsdom specifically, because it parses with parse5 - the same parser browsers
+ * implement. A looser parser could serialise markup a browser would rearrange,
+ * which is precisely the class of bug that bit the old element markers.
+ */
+export interface RenderPageOptions {
+    html: string;
+    definitions: ComponentDefinition[];
+    /**
+     * Ship inert islands as plain HTML.
+     *
+     * **On by default.** The build mounts every component and records what it
+     * needed the browser for; an island that needed nothing loses its markers,
+     * so the client never adopts it and never fetches its chunk.
+     *
+     * `$hydrate="always"` keeps one the evidence gets wrong - a listener
+     * attached from a promise, a library reaching for the element after mount.
+     * Turn the whole thing off only to compare against what hydration would have
+     * done.
+     */
+    flattenStatic?: boolean;
+    /**
+     * Inline this page's critical CSS, or leave it for the caller to emit as a
+     * cacheable file. Inline avoids a render-blocking round trip and any CLS;
+     * external trades that for cross-page caching.
+     */
+    css?: "inline" | "external";
+    /**
+     * Cell values seeded before rendering.
+     *
+     * How a route's params reach the page: they are an ordinary cell, so
+     * `shared.route` binds, `$needs` gates on it and it travels in the state
+     * payload like any other build-time content - no separate mechanism, and no
+     * routing API on the runtime.
+     */
+    seed?: Record<string, unknown>;
+    /**
+     * A pattern the *client* resolves against the URL.
+     *
+     * Only for a page whose paths could not be enumerated at build: one file
+     * answers many URLs, so the params cannot be baked and the pattern travels
+     * instead.
+     */
+    routePattern?: string;
+    /**
+     * Compiled expressions from the page's own island markers.
+     *
+     * They belong to no component, so the build renders with the same table the
+     * browser will get from the entry chunk.
+     */
+    pageExpressions?: {
+        expressions?: Record<string, any>;
+        writers?: Record<string, any>;
+    };
+}
+export interface RenderPageResult {
+    html: string;
+    /** Islands rendered, and islands left as a skeleton. */
+    rendered: number;
+    skipped: number;
+    /** Component ids this page can reach, following `uses` transitively. */
+    used: string[];
+    /** Critical CSS for those components - inlined unless css is "external". */
+    css: string;
+    /** Deferred CSS for those components. */
+    cssDeferred: string;
+    /**
+     * Cell keys this page fetched at build.
+     *
+     * Recorded so a rebuild can be targeted: a CMS webhook says which content
+     * changed, and only the pages that read it need re-rendering.
+     */
+    content: string[];
+    /**
+     * The state payload this page shipped.
+     *
+     * Returned so a caller can read build-time content back out - which is what
+     * lets a route enumerate its rows from the same cell the page rendered.
+     */
+    state: Record<string, unknown>;
+    /**
+     * What each island would need the browser for.
+     *
+     * Evidence gathered while it rendered, not read out of its source. An island
+     * with no reasons is one nothing would happen to if the client never mounted
+     * it - a candidate for shipping as plain HTML.
+     */
+    hydration: {
+        id: string;
+        componentId: string;
+        live: boolean;
+        reasons: string[];
+    }[];
+    /** Islands shipped as plain HTML because nothing needed them in the browser. */
+    flattened: number;
+}
+export declare function renderPage(options: RenderPageOptions): Promise<RenderPageResult>;

package/dist/types/src/types/lsp.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Ambient types for consumers.
+ *
+ * A `.lsp` file becomes a JS module at build time, so TypeScript needs telling
+ * what that module looks like. Equivalent to the `*.vue` shim Vue ships.
+ */
+
+declare module "*.lsp" {
+  const component: import("../runtime/index.js").ComponentDefinition
+  export default component
+
+  export const template: string
+  export const skeleton: string
+  export const style: string
+  export const logic: string
+  export const scopeId: string
+}
+
+interface Window {
+  /** Set by the app so hot reload can reach the running runtime. */
+  lightspeed?: import("../runtime/index.js").LightspeedRuntime
+}

package/dist/types/src/types/optional.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Compilers the Vite plugin will use if they happen to be installed.
+ *
+ * They are loaded through a dynamic import inside a try/catch and are NOT
+ * dependencies - esbuild, which Vite already brings, is the default. These
+ * declarations keep that optional path typecheckable without pulling anything
+ * in.
+ */
+declare module "@swc/core" {
+  export function transform(
+    code: string,
+    options?: any,
+  ): Promise<{ code: string }>
+}

package/dist/types/src/types/virtual.d.ts

@@ -0,0 +1,4 @@
+declare module "virtual:lightspeed/components" {
+  /** Component id to a dynamic import, generated by the Vite plugin. */
+  export const components: Record<string, () => Promise<unknown>>
+}

package/dist/types/src/vite/csp.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CSP hashes for the inline `<style>` blocks in a built page.
+ *
+ * A **nonce cannot work for static output**: it must differ per response, and a
+ * file on disk carries one value forever, which is a nonce in name only.
+ * Hashes are the static equivalent - the content is fixed, so the build can
+ * state exactly what a host should allow via `style-src 'sha256-...'`.
+ *
+ * Build-side only. `manifest.ts` is imported by the runtime, so nothing that
+ * reaches for `node:crypto` can live there.
+ */
+export declare function styleHashes(html: string): string[];

package/dist/types/src/vite/index.d.ts

@@ -0,0 +1,2 @@
+export { lightspeedPlugin } from "./plugin.js";
+export type {} from "./plugin.js";

package/dist/types/src/vite/layout.d.ts

@@ -0,0 +1,17 @@
+export declare const LAYOUT_PREFIX = "_";
+export declare const DEFAULT_LAYOUT_FILE = "_layout.html";
+/** `plain` → `_plain.html`, `layouts/admin` → `layouts/_admin.html`. */
+export declare function layoutFileName(name: string): string;
+export interface LayoutResult {
+    html: string;
+    /** Every layout file involved, so dev can watch them. */
+    sources: string[];
+}
+/**
+ * Expand a page into its layout, if it has one.
+ *
+ * Layouts may themselves declare a layout, which is how a section layout wraps
+ * a site one. Depth is capped so a cycle fails loudly rather than hanging the
+ * dev server.
+ */
+export declare function expandLayout(html: string, filename: string, root: string): Promise<LayoutResult>;

package/dist/types/src/vite/plugin.d.ts

@@ -0,0 +1,69 @@
+import type { Plugin } from "vite";
+interface LightspeedPluginOptions {
+    typescript?: boolean;
+    /**
+     * Emit every page as a directory index, so URLs carry no `.html`.
+     *
+     * Opt-in rather than default: it changes the shape of the output, and a
+     * project that links to `about.html` would break. Pages declaring
+     * `<!-- lsp:route -->` produce real files per row regardless of this.
+     */
+    routes?: boolean;
+    /**
+     * Ship islands that needed nothing from the browser as plain HTML.
+     *
+     * The build watches every component render and records what it needed the
+     * browser for. With this on, anything that needed nothing loses its markers:
+     * no adoption, no logic, and no chunk fetched.
+     *
+     * On by default. `$hydrate="always"` is the escape hatch for anything the
+     * evidence gets wrong, and `$hydrate="never"` is an assertion that fails the
+     * build when something live is inside a subtree declared static.
+     */
+    flattenStatic?: boolean;
+    /**
+     * Which host's syntax to emit rewrite rules in, for runtime-resolved routes.
+     *
+     * Only used by a route with no `from` - a baked route needs no server
+     * cooperation at all.
+     */
+    rewrites?: "_redirects" | "caddy" | "nginx";
+    compiler?: "tsc" | "esbuild" | "swc";
+    /**
+     * Where a page's critical CSS goes.
+     *
+     * "inline" (default) costs no round trip and cannot cause CLS. "external"
+     * emits a hashed file that caches across pages, at the cost of a
+     * render-blocking request - worth it for a site with heavy internal
+     * navigation, not for a landing page.
+     */
+    css?: "inline" | "external";
+    /**
+     * Render islands to HTML during `vite build`.
+     *
+     * Off in dev: the client mounts anyway, so rendering twice would only slow
+     * reloads. On in build, where it is the difference between shipping markers
+     * and shipping content a crawler can read.
+     */
+    render?: boolean;
+    /**
+     * Where else to look for `.lsp` components, besides the project's `src`.
+     *
+     * A component library is a package of components, and until this existed a
+     * package could not ship any: the scan only ever looked in the app being
+     * built, so a shared picker had to be copied into every app that mounted it
+     * - and copies drift.
+     *
+     * Paths are relative to the Vite root. Components are compiled by *this*
+     * build rather than shipped pre-built, so the host's styling, hydration
+     * policy and CSP apply to them exactly as they do to its own.
+     *
+     * Names are a flat namespace: a component is its filename, lowercased, from
+     * wherever it was found. The project's own `src` is searched first and wins,
+     * so an app can replace a package's component by giving a file the same
+     * name - deliberate, and announced in the build log rather than silent.
+     */
+    componentDirs?: string[];
+}
+export declare function lightspeedPlugin(options?: LightspeedPluginOptions): Plugin[];
+export {};

package/dist/types/src/vite/routes.d.ts

@@ -0,0 +1,139 @@
+import type { ComponentDefinition } from "../runtime/components/index.js";
+import { type ParsedRoute, type RouteDeclaration } from "../parser/route.js";
+/**
+ * Re-anchor relative asset URLs for a file at a different depth.
+ *
+ * With a relative `base`, Vite computes each page's `../` prefix from where
+ * that page sits - correct for pages it emits, and wrong for the copies a
+ * route makes, which sit deeper. A row whose slug contains a slash is deeper
+ * still, so this cannot be a constant per route.
+ *
+ * Absolute URLs need nothing, which is why an absolute `base` sidesteps all of
+ * this.
+ */
+export declare function reanchorRelativeUrls(html: string, fromDepth: number, toDepth: number): string;
+export interface RoutePage {
+    /** Page file basename, e.g. `blog.html`. */
+    page: string;
+    route: ParsedRoute;
+    declaration: RouteDeclaration;
+    /** The markup the build started from, before islands were rendered. */
+    shell: string;
+    /** Where the shell itself sits in the output, for re-anchoring. */
+    shellDepth: number;
+}
+export interface EmittedRoute {
+    path: string;
+    file: string;
+    params: Record<string, string>;
+    /**
+     * Build-time cells this page read.
+     *
+     * Per emitted path, not per source page: a routed page produces one output
+     * per row, and each row reads its *own* entry. Without this a rebuild can
+     * only re-render every page enumerated from a collection - a typo in one
+     * post rebuilding a thousand of them.
+     */
+    content?: string[];
+}
+/**
+ * Read the rows a route enumerates out of the page's own build-time content.
+ *
+ * Deliberately the *same* cell the page renders from, rather than a second
+ * declaration: a blog page already fetches its posts at build, and the route
+ * names that cell rather than re-fetching it.
+ */
+export declare function rowsFrom(state: Record<string, unknown>, from: string, page: string): Array<Record<string, unknown>>;
+/** Compute every path a route produces, failing on a collision. */
+export declare function pathsFor(page: RoutePage, rows: Array<Record<string, unknown>>): EmittedRoute[];
+/**
+ * Render one real file per row.
+ *
+ * The shell is re-rendered per row rather than string-substituted, so a routed
+ * page is rendered exactly the way any other page is - `$for`, `$if`, slots
+ * and build-time content all behave identically, because it is the same call.
+ */
+export declare function emitRoutePages(options: {
+    dir: string;
+    page: RoutePage;
+    routes: EmittedRoute[];
+    definitions: ComponentDefinition[];
+    css?: "inline" | "external";
+    /** Ship inert islands as plain HTML - see `renderPage`. */
+    flattenStatic?: boolean;
+}): Promise<{
+    written: number;
+    flattened: number;
+}>;
+/** `blog.html` + `<!-- lsp:route … -->` → a parsed, validated route page. */
+export declare function toRoutePage(page: string, shell: string, declaration: RouteDeclaration & {
+    pattern: string;
+}, shellDepth?: number): RoutePage;
+/**
+ * Rewrite rules for a page whose URLs are resolved at runtime.
+ *
+ * The host has to map every URL matching the pattern onto the one shell that
+ * answers them. That is the cost of this kind of route, and the reason a baked
+ * route is better whenever the paths *can* be enumerated: it needs no server
+ * cooperation at all.
+ */
+export interface RewriteRule {
+    pattern: string;
+    target: string;
+}
+/**
+ * Netlify / Cloudflare Pages `_redirects`. A 200 is a rewrite, not a redirect.
+ *
+ * These hosts check static files before redirect rules, so a real page always
+ * wins over a pattern that would also match it. The Caddy and nginx formats
+ * have to say so explicitly, via `try_files`.
+ */
+export declare function formatRedirects(rules: RewriteRule[]): string;
+export declare function formatCaddy(rules: RewriteRule[]): string;
+export declare function formatNginx(rules: RewriteRule[]): string;
+export declare const REWRITE_FORMATS: {
+    readonly _redirects: {
+        readonly file: "_redirects";
+        readonly format: typeof formatRedirects;
+    };
+    readonly caddy: {
+        readonly file: "rewrites.caddy";
+        readonly format: typeof formatCaddy;
+    };
+    readonly nginx: {
+        readonly file: "rewrites.nginx";
+        readonly format: typeof formatNginx;
+    };
+};
+export type RewriteFormat = keyof typeof REWRITE_FORMATS;
+/**
+ * Warn when a routed page's content is not keyed by its own params.
+ *
+ * A routed page should read *its own* entry, so a change to one entry rebuilds
+ * one page. If every output reads the same collection-wide cells, a change to
+ * any of them fans out to all of them - O(n) work for an O(1) edit, which is
+ * exactly what surgical rebuilds exist to avoid.
+ *
+ * Reading a collection-wide cell is legitimate on its own: that is how paths
+ * are enumerated, and how a listing gets its data. The problem is reading
+ * *only* those, which is why this checks for the absence of a parameterised
+ * cell rather than the presence of a shared one.
+ *
+ * Returns null when there is nothing to say.
+ */
+export declare function fanOutWarning(page: string, routes: EmittedRoute[]): string | null;
+/**
+ * Whether a host has to resolve this route, or the build already did.
+ *
+ * A pattern alone does not say: a route enumerated from a cell has one too,
+ * and its pages are real files on disk. `from` - the cell it was enumerated
+ * from - is what separates them.
+ *
+ * One predicate rather than the same expression in several places: the bug it
+ * replaces was exactly two of them disagreeing, so a baked page was served
+ * from a shell that had never been emitted and 404ed.
+ */
+export declare function resolvedByHost(entry: {
+    pattern?: string;
+    from?: string;
+}): boolean;

package/dist/types/test/adopted-styles.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/adoption.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/agent.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/audit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/bindings.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/branches-in-loops.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/build.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/buildtime.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/built.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/cell-props.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/comments.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/compile-expressions.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/compile-logic.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/components.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/composition.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/declared-needs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/diagnostics.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/dynamic.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/example.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/faq.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/flatten-nested.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/html-binding.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/hydration-report.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/hydration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/layout-resolution.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/layout.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/lazy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/manifest.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/model-props.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/model.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/mounting.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/needs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/nested-rows.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/on-mounted.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/on-update.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/page-island.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/pages.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/reactivity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/rebuild-keeps-logic.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/rebuild.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/reenumerate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/refresh.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/refs.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/reorder.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/route.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/routes-build.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/routes-dev.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/routes-emit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/test/routes-runtime.test.d.ts

@@ -0,0 +1 @@
+export {};