@valbuild/shared 0.150.10 → 0.150.12

package/dist/declarations/src/internal/pageInspection.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Looking at a page from the design tab (valbuild/home `docs/design-tab.md`):
+ * where it is -- its path and scroll, so a new build opens at the same place
+ * -- and what is on it, so the assistant can check its own change
+ * (`read_page`).
+ *
+ * Plain DOM and in `shared` for the reason `elementPicker.ts` is: the canvas
+ * bridge (`@valbuild/next`, `@valbuild/tanstack`) runs it inside the
+ * proposal's page, which is another origin than the tab and the only place
+ * the page can be read. Only what is returned here crosses the frame
+ * (`valCanvasProtocol.ts`).
+ */
+/** Where the page is: what a new build is opened at. */
+export type PageLocation = {
+    /** Its path and query, without the canvas's own parameter. */
+    path: string;
+    scrollX: number;
+    scrollY: number;
+};
+/** A box on the page, in CSS pixels from the top of the document. */
+export type PageBox = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** One thing a reader would notice on the page, in document order. */
+export type PageOutlineItem = {
+    kind: "heading" | "text" | "link" | "button" | "image" | "input" | "section";
+    tag: string;
+    /** How to find it again: `read_page` with this `selector`. */
+    selector: string;
+    /** The words in it, shortened. Absent for an image or an empty element. */
+    text?: string;
+    /** `h1` is 1. */
+    level?: number;
+    href?: string;
+    alt?: string;
+    src?: string;
+    box: PageBox;
+};
+/** One element in detail: what `read_page` answers for a `selector`. */
+export type PageElementDetail = {
+    selector: string;
+    tag: string;
+    text: string;
+    box: PageBox;
+    /** How many lines its text wraps to, when it can be told. */
+    lines?: number;
+    /** The computed styles a change to a design is usually about. */
+    styles: Record<string, string>;
+    /** Its children, one level down. */
+    children: Array<{
+        tag: string;
+        selector: string;
+        text?: string;
+        box: PageBox;
+    }>;
+};
+export type PageSnapshot = {
+    /** The page's own address. */
+    url: string;
+    title: string;
+    viewport: {
+        width: number;
+        height: number;
+        scrollY: number;
+        /** How tall the whole page is. */
+        pageHeight: number;
+    };
+    outline: PageOutlineItem[];
+    /** Cut short at `maxItems`: narrow with a `selector`. */
+    truncated?: true;
+    /** The element asked for by `selector`. */
+    element?: PageElementDetail;
+    /** The `selector` matched nothing. */
+    notFound?: string;
+};
+/** Where `win` is now. */
+export declare function pageLocationOf(win: Window): PageLocation;
+/**
+ * Report where the page is as it moves: on scroll, a little after it settles,
+ * and when it navigates -- which a client-side router does without an event,
+ * so the address is also looked at now and then. Returns the way to stop.
+ */
+export declare function watchPageLocation(win: Window, onChange: (location: PageLocation) => void, options?: {
+    settleMs?: number;
+    pollMs?: number;
+}): () => void;
+/**
+ * Scroll to where the last build was, once the page is tall enough to: a page
+ * that is still loading its content is shorter than it will be, so this tries
+ * again each frame for a while rather than stopping at the bottom of half a
+ * page. Returns the way to stop trying.
+ */
+export declare function restoreScroll(win: Window, x: number, y: number, options?: {
+    withinMs?: number;
+}): () => void;
+/**
+ * What is on the page, as a reader would take it in: headings, text, links,
+ * buttons, images and inputs, in order, each with where it is. With a
+ * `selector`, that element in detail -- its computed styles, how many lines
+ * its text wraps to, and its children.
+ *
+ * `root` is what selectors are written from: the body, as `describeElement`
+ * writes them for a picked element.
+ */
+export declare function readPageSnapshot(doc: Document, options?: {
+    selector?: string;
+    maxItems?: number;
+}): PageSnapshot;
+/**
+ * The element a selector names, written as `describeElement` writes them --
+ * from the body down, or from an element with an id -- or any selector a
+ * person would write.
+ */
+export declare function findBySelector(root: Element, selector: string): Element | null;

package/dist/declarations/src/internal/quickPreview.d.ts

@@ -0,0 +1,91 @@
+/**
+ * A quick preview: a proposal's page, running the proposal's CLIENT code
+ * built in the design tab, without a build being uploaded or served
+ * (valbuild/home `docs/design-tab.md`).
+ *
+ * A full build of a proposal bundles the app for the server and the browser,
+ * uploads it, and has the platform render every page before it is served --
+ * minutes. Most of what the design tab changes is components and styles,
+ * which the browser half alone shows. So the tab bundles the app in its
+ * builder worker, and a service worker on the proposal's address hands the
+ * page that bundle instead of the served one:
+ *
+ * 1. The tab sends the files (`/_app/app.js`, its chunks, the stylesheet and
+ *    assets) to the page in the preview, over the canvas protocol.
+ * 2. The page -- the bridge, which is the only thing at that origin the tab
+ *    can talk to -- registers {@link QUICK_PREVIEW_SERVICE_WORKER_SOURCE}
+ *    and stores the files in it (Cache Storage, so a worker the browser
+ *    stopped still has them).
+ * 3. The tab opens the page with `?val_quick=<id>`. The worker serves that
+ *    document's `/_app/` requests from the files, and everything else from
+ *    the network: the HTML is the last build's, rendered by its server, and
+ *    the new code takes it over in the browser.
+ *
+ * What it cannot show, and the tab says so: anything on the server. Server
+ * functions, API routes and loaders that run there are the last build's, as
+ * is the page's first render and its `head`. A new dependency is not there
+ * either. A build is still what decides, before Publish.
+ *
+ * Only a document opened with the parameter is served from the files, so a
+ * visitor to the proposal's address -- even in the same browser -- is never
+ * given them.
+ */
+/** The parameter a quick preview's page is opened with. */
+export declare const QUICK_PREVIEW_PARAM = "val_quick";
+/** Where Val's API serves the worker: under `/api/val`. */
+export declare const QUICK_PREVIEW_SERVICE_WORKER_PATH = "/quick-preview-sw.js";
+/** What the page sends the worker to store a preview's files. */
+export declare const QUICK_PREVIEW_STORE_MESSAGE = "val-quick-preview-store";
+/**
+ * A preview's files, by their path under `/_app/`: `app.js`, `c-<hash>.js`,
+ * `app.css`, `a/<hash>.png`. A binary file is base64.
+ */
+export type QuickPreviewFiles = Record<string, {
+    body: string;
+    contentType: string;
+    base64?: true;
+}>;
+/**
+ * The files of a quick preview: paths under `/_app/` with no way out of it,
+ * each a string body and a type.
+ */
+export declare function isQuickPreviewFiles(value: unknown): value is QuickPreviewFiles;
+/**
+ * The worker, as the source it is served as: plain, and small, because it is
+ * served as a file of its own (`demoServiceWorker.ts` is the same).
+ */
+export declare const QUICK_PREVIEW_SERVICE_WORKER_SOURCE = "\n\"use strict\";\nconst PARAM = \"val_quick\";\nconst CACHE = \"val-quick-preview\";\nconst PREFIX = \"/__val_quick/\";\nconst INDEX = PREFIX + \"index\";\nconst KEEP = 4;\n\nself.addEventListener(\"install\", () => self.skipWaiting());\nself.addEventListener(\"activate\", (event) => {\n  event.waitUntil(self.clients.claim());\n});\n\nself.addEventListener(\"message\", (event) => {\n  const data = event.data;\n  if (!data || data.type !== \"val-quick-preview-store\") return;\n  const port = event.ports && event.ports[0];\n  event.waitUntil(\n    store(data.id, data.files).then(\n      () => port && port.postMessage({ ok: true }),\n      (error) =>\n        port &&\n        port.postMessage({\n          ok: false,\n          message: String((error && error.message) || error),\n        }),\n    ),\n  );\n});\n\nfunction keyOf(id, path) {\n  return PREFIX + id + \"/\" + path;\n}\n\nasync function store(id, files) {\n  const cache = await caches.open(CACHE);\n  for (const path of Object.keys(files)) {\n    const file = files[path];\n    const body = file.base64\n      ? Uint8Array.from(atob(file.body), (c) => c.charCodeAt(0))\n      : file.body;\n    await cache.put(\n      keyOf(id, path),\n      new Response(body, {\n        headers: { \"Content-Type\": file.contentType, \"Cache-Control\": \"no-store\" },\n      }),\n    );\n  }\n  // The newest few previews are kept; older ones are deleted.\n  const index = await cache.match(INDEX);\n  const ids = [id].concat(\n    (index ? await index.json() : []).filter((other) => other !== id),\n  );\n  const dropped = ids.slice(KEEP);\n  if (dropped.length > 0) {\n    for (const request of await cache.keys()) {\n      const path = new URL(request.url).pathname;\n      if (dropped.some((old) => path.startsWith(PREFIX + old + \"/\"))) {\n        await cache.delete(request);\n      }\n    }\n  }\n  await cache.put(INDEX, new Response(JSON.stringify(ids.slice(0, KEEP))));\n}\n\n/** Which preview a document is: by its id, or by the address it was opened at. */\nconst byClient = new Map();\nasync function previewOf(clientId) {\n  if (!clientId) return null;\n  if (byClient.has(clientId)) return byClient.get(clientId);\n  const client = await self.clients.get(clientId);\n  const id = client ? new URL(client.url).searchParams.get(PARAM) : null;\n  byClient.set(clientId, id);\n  return id;\n}\n\nself.addEventListener(\"fetch\", (event) => {\n  const url = new URL(event.request.url);\n  if (url.origin !== self.location.origin) return;\n  if (event.request.mode === \"navigate\") {\n    if (event.resultingClientId) {\n      byClient.set(event.resultingClientId, url.searchParams.get(PARAM));\n    }\n    return;\n  }\n  if (!url.pathname.startsWith(\"/_app/\")) return;\n  event.respondWith(serve(event, url));\n});\n\nasync function serve(event, url) {\n  const id = await previewOf(event.clientId);\n  if (id) {\n    const hit = await caches.match(keyOf(id, url.pathname.slice(6)), {\n      cacheName: CACHE,\n    });\n    if (hit) return hit;\n  }\n  return fetch(event.request);\n}\n";
+/**
+ * Store a preview's files in the worker, registering it first: what the
+ * bridge does when the tab sends `quickPreview`. `swUrl` is the worker's
+ * address on this origin (`/api/val` + {@link QUICK_PREVIEW_SERVICE_WORKER_PATH}).
+ */
+export declare function storeQuickPreview(id: string, files: QuickPreviewFiles, options: {
+    swUrl: string;
+    container?: ServiceWorkerContainer;
+}): Promise<void>;
+/** The address of a page as a quick preview `id`. */
+export declare function withQuickPreviewParam(url: string, id: string): string;
+/**
+ * The one origin allowed to send this page a quick preview: the site's, where
+ * the design tab is, as this page's own Val server says it (the proposals
+ * list's `siteUrl`). `null` when it does not say.
+ *
+ * A quick preview is code that runs on this address, so the bridge takes one
+ * only from its parent, and only when that parent is the site: a page that
+ * framed this one could otherwise post a script into the worker and open
+ * the frame on it.
+ */
+export declare function quickPreviewSiteOrigin(api: string, fetchImpl?: typeof fetch): Promise<string | null>;
+/**
+ * Whether `origin` may ask this page for what only the design tab should
+ * have -- what is on it (`readPage`), or code to run (`quickPreview`): this
+ * page's own origin (the Studio's canvas), or the site's, where the design
+ * tab is ({@link quickPreviewSiteOrigin}). Asked of the server once, and
+ * again only while it has not said.
+ */
+export declare function isDesignTabOrigin(origin: string, options: {
+    api: string;
+    own: string;
+    fetchImpl?: typeof fetch;
+}): Promise<boolean>;

package/dist/declarations/src/internal/valCanvasProtocol.d.ts

@@ -21,6 +21,8 @@
  */
 import type { ModuleFilePath, SourcePath } from "@valbuild/core";
 import type { PickedElement, PickModifier } from "./elementPicker.js";
+import type { PageLocation, PageSnapshot } from "./pageInspection.js";
+import { type QuickPreviewFiles } from "./quickPreview.js";
 /** Marks a page load as the studio's canvas frame. */
 export declare const VAL_CANVAS_PARAM = "val_canvas";
 /**
@@ -188,6 +190,30 @@ export type ValCanvasPageMessage = {
      */
     val: typeof VAL_CANVAS_MESSAGE;
     type: "elementPickingStopped";
+} | ({
+    /**
+     * Where the page is: its path and scroll, as it moves. The design tab
+     * opens a new build there (`scrollTo`), so a new version replaces the
+     * page in place rather than starting over at the top of the front page.
+     */
+    val: typeof VAL_CANVAS_MESSAGE;
+    type: "location";
+} & PageLocation) | {
+    /** What `readPage` asked for, or why it could not be read. */
+    val: typeof VAL_CANVAS_MESSAGE;
+    type: "pageRead";
+    requestId: string;
+    snapshot: PageSnapshot | null;
+    error?: string;
+} | {
+    /**
+     * A quick preview's files are stored in the page's worker, and a page
+     * opened with its id is served them (`quickPreview.ts`) -- or why not.
+     */
+    val: typeof VAL_CANVAS_MESSAGE;
+    type: "quickPreviewStored";
+    id: string;
+    error?: string;
 };
 /** What the studio tells the page. */
 export type ValCanvasStudioMessage = {
@@ -291,6 +317,33 @@ export type ValCanvasStudioMessage = {
     modifier: PickModifier;
     /** Whether the studio still holds the last pick: false takes its outline down. */
     keepPicked: boolean;
+} | {
+    /** Scroll to where the page before this one was (`location`). */
+    val: typeof VAL_CANVAS_MESSAGE;
+    type: "scrollTo";
+    x: number;
+    y: number;
+} | {
+    /**
+     * Read what is on the page (`readPageSnapshot`): the assistant's
+     * `read_page`. Answered with `pageRead` and the same `requestId`. A
+     * bridge that predates it never answers, and the tab says so.
+     */
+    val: typeof VAL_CANVAS_MESSAGE;
+    type: "readPage";
+    requestId: string;
+    selector?: string;
+    maxItems?: number;
+} | {
+    /**
+     * Store a quick preview's files in this origin's worker
+     * (`storeQuickPreview`): the tab cannot, being another origin.
+     * Answered with `quickPreviewStored`.
+     */
+    val: typeof VAL_CANVAS_MESSAGE;
+    type: "quickPreview";
+    id: string;
+    files: QuickPreviewFiles;
 };
 /** Narrow an unknown `event.data` to a message from the page. */
 export declare function isValCanvasPageMessage(data: unknown): data is ValCanvasPageMessage;

package/dist/declarations/src/publish/buildProposal.d.ts

@@ -45,7 +45,14 @@ export type ProposalBuildOutcome<P> = {
 } | {
     status: "failed";
     message: string;
+    /**
+     * Stopped by whoever started it (`signal`), not by anything wrong with
+     * the build: nothing to fix, and nothing to show as an error.
+     */
+    cancelled?: true;
 };
+/** What a cancelled build answers. */
+export declare const BUILD_CANCELLED_MESSAGE = "The build was cancelled.";
 /**
  * Where a build of the proposal is, around the deploy: the deploy's own steps
  * are the Studio's deploy state (`useStudioDeployState`), and these are the
@@ -93,13 +100,21 @@ export declare function buildProposal<P extends BuiltProposal>(deps: {
      * on the layer content had built for it; `undefined` builds on the site's,
      * as every build of a proposal did before.
      */
-    deploy: (files: Record<string, string | null>, target: BuildTargetResponse | undefined) => Promise<StudioDeployResult>;
+    deploy: (files: Record<string, string | null>, target: BuildTargetResponse | undefined, signal: AbortSignal | undefined) => Promise<StudioDeployResult>;
     /**
      * Whether this document can build at all (`canBuildHere`): Safari cannot,
      * and a proposal's build has no builder tab to hand off to yet.
      */
     canBuildHere: () => boolean;
     onStep?: (step: ProposalBuildStep) => void;
+    /**
+     * Stops the build: Cancel, or a watchdog that saw it stall. Answered at
+     * once, whatever the build was waiting on, and nothing after it is done --
+     * a build stopped while it uploads is never served. Aborted with an `Error`
+     * of its own, the build fails with that error's message; otherwise it is
+     * `cancelled`.
+     */
+    signal?: AbortSignal;
     /** For tests: the clock, and waiting on it. */
     now?: () => number;
     sleep?: (ms: number) => Promise<void>;

package/dist/declarations/src/publish/buildQuickPreview.d.ts

@@ -0,0 +1,46 @@
+import type { BuildOutput } from "@valbuild/tanstack-build";
+import type { BuildTargetResponse } from "../internal/index.js";
+import type { QuickPreviewFiles } from "../internal/quickPreview.js";
+import type { StudioBuilder } from "./builder.js";
+export type QuickPreviewOutcome = {
+    status: "built";
+    files: QuickPreviewFiles;
+    /** What the proposal's files were staged as: the build is of these. */
+    inputs: string | null;
+} | {
+    status: "failed";
+    message: string;
+};
+export declare function buildQuickPreview(deps: {
+    name: string;
+    /** The proposal's files, and what they build on. */
+    proposals: {
+        files(name: string): Promise<{
+            files: Record<string, string | null>;
+            staged: {
+                inputs: string | null;
+            };
+        }>;
+        buildTarget(name: string): Promise<{
+            target: BuildTargetResponse;
+            layer: "site" | "own";
+        }>;
+    };
+    /** The site's source, which the proposal's files are laid over. */
+    siteSource: () => Promise<Record<string, string> | null>;
+    /** The site's build target: what the proposal's address serves. */
+    siteTarget: () => Promise<BuildTargetResponse>;
+    loadBuilder: () => Promise<StudioBuilder>;
+    /** Generates `src/routeTree.gen.ts`: see `runStudioDeploy`. */
+    generateRouteTree?: (files: Record<string, string>) => Promise<Record<string, string>>;
+    /** Each step as it begins: for the tab's progress and timings. */
+    onStep?: (label: string) => void;
+    signal?: AbortSignal;
+}): Promise<QuickPreviewOutcome>;
+/**
+ * The browser half of a build, as the worker serves it under `/_app/`. The
+ * stylesheet only when the tab compiled one: an empty one is the case where a
+ * build ships the site's live stylesheet (`liveStylesheet` on
+ * `runStudioDeploy`), and the page already has that.
+ */
+export declare function clientFilesOf(build: BuildOutput): QuickPreviewFiles;

package/dist/declarations/src/publish/index.d.ts

@@ -15,9 +15,10 @@ export type { StudioBuilder } from "./builder.js";
 export { StudioPublishError, callJson, isTransientPublishError, onPublishRefusal, } from "./callJson.js";
 export { StudioUploadError, createStudioPublishClient, isExpiredSlot, publishApiOf, type CarriedArtifact, type LivePublicFiles, type PublishApiAt, type StudioPublishClient, } from "./publishClient.js";
 export { runStudioPublish, type PublishPhase, type StudioPublishResult, } from "./runStudioPublish.js";
-export { carriedInto, runStudioDeploy, splitBinaryFiles, withCommittedFiles, type CommittedBinaryFiles, type DeployPhase, type StudioDeployOptions, type StudioDeployResult, } from "./runStudioDeploy.js";
+export { DEPLOY_STOPPED_MESSAGE, carriedInto, runStudioDeploy, splitBinaryFiles, withCommittedFiles, type CommittedBinaryFiles, type DeployPhase, type StudioDeployOptions, type StudioDeployResult, } from "./runStudioDeploy.js";
 export { STUDIO_OUT_OF_DATE, STUDIO_OUT_OF_DATE_MESSAGE, layerMoved, loadedLayer, markStudioOutOfDate, readLiveLayer, rememberLoadedLayer, resetLoadedLayerForTests, siteMovedSinceLoad, studioOutOfDateRefusals, subscribeStudioOutOfDate, type LayerReading, } from "./loadedLayer.js";
 export { MergePrepareAnswer, createStudioJobClient, isMergeChange, type PreparedJob, type StudioJobClient, } from "./jobClient.js";
 export { RENEW_EVERY_MS, runJobToEnd, runStudioJob, type JobPhase, type StudioJobResult, } from "./runStudioJob.js";
-export { SERVE_POLL_MS, SERVE_WAIT_MS, buildProposal, withoutLockfiles, type BuiltProposal, type ProposalBuildClient, type ProposalBuildOutcome, type ProposalBuildStep, } from "./buildProposal.js";
+export { BUILD_CANCELLED_MESSAGE, SERVE_POLL_MS, SERVE_WAIT_MS, buildProposal, withoutLockfiles, type BuiltProposal, type ProposalBuildClient, type ProposalBuildOutcome, type ProposalBuildStep, } from "./buildProposal.js";
 export { proposalProject } from "./proposalProject.js";
+export { buildQuickPreview, clientFilesOf, type QuickPreviewOutcome, } from "./buildQuickPreview.js";

package/dist/declarations/src/publish/runStudioDeploy.d.ts

@@ -211,6 +211,14 @@ export interface StudioDeployOptions {
      */
     generateRouteTree?: (files: Record<string, string>) => Promise<Record<string, string>>;
     onPhase: (phase: DeployPhase) => void;
+    /**
+     * Stops the deploy between its steps: a cancelled proposal build. What is
+     * in flight is the caller's to stop -- the requests, through the client's
+     * `fetchImpl`; the builder, by stopping its worker -- and nothing after the
+     * step it was on is started, so a build stopped before its upload is never
+     * declared.
+     */
+    signal?: AbortSignal;
 }
 export declare function runStudioDeploy(options: StudioDeployOptions): Promise<StudioDeployResult>;
 /**
@@ -242,3 +250,5 @@ export declare function splitBinaryFiles(files: Record<string, string>): {
 export declare function carriedInto(built: ReadonlyArray<{
     key: string;
 }>, carried: ReadonlyArray<CarriedArtifact>, committed: Record<string, string | null> | null): CarriedArtifact[];
+/** What a deploy stopped by its `signal` answers. */
+export declare const DEPLOY_STOPPED_MESSAGE = "The build was stopped.";