/** * The bit of the preview page that exists for automation. * * A stage page is a real, directly-navigable document — an agent driving a * browser can open one and photograph a single component instead of the whole * Explorer, which is the difference between a ~2000-token screenshot and a * ~2-token one. Two things make that reliable, and neither can be guessed from * outside the page: *when* the stage is done rendering, and *how far past its * own box* a component actually paints. */ /** A short, stable handle for one stage — the thing a person can read off the * screen and say out loud ("look at sdocs:k3f9a"). Derived from the same * identity the preview URL encodes, so it never becomes a second naming * scheme to keep in sync; it's a nickname for a route, not a new address. */ export declare function stageId(relPathWithSlugs: string): string; /** The identity string a stage id hashes: doc path + entity + snippet. * * Deliberately the **absolute** path. A relative one would have to agree on a * root, and the two callers don't have the same one — the dev server encodes * against its staging directory, the MCP server against the project — which * would hand a person one id on screen and the tool a different id for the * same stage. Nothing leaks: the hash is five characters and never ships in a * built site. */ export declare function stageIdentity(filePath: string, entitySlug: string, snippetSlug: string): string; export interface StageIdentityAttrs { id: string; kind: string; name: string; component?: string | null; } /** One photographable stage: what it is, what it shows, and how to address it. * Dev, build, and the MCP server all describe stages through this, so a stage * id means the same thing wherever it's printed. */ export interface StageDescriptor extends StageIdentityAttrs { /** URL segment within the entity */ slug: string; } /** Describe every stage of one entity that has its own preview page. */ export declare function describeStages(entity: { kind: string; slug: string; }, planned: Array<{ slug: string; name: string; role: string; componentName?: string | null; }>, filePath: string): StageDescriptor[]; /** `` attributes carrying the stage's identity into the document, so the * page can answer "what am I?" without the caller decoding a URL. */ export declare function stageAttrs(stage: StageIdentityAttrs | null): string; /** * Runs before the stage module, so a stage that fails to even load still ends * up in a state an automated client can read instead of hanging on a selector * that will never appear. A blank page and a broken page look identical from * outside; this makes them distinguishable. */ export declare const PREVIEW_BOOTSTRAP_JS: string; /** * The capture API, injected into every stage page as `window.__sdocs`. * * `captureRect` exists because `boundingBox()` returns the border box, and a * component's *visible* extent is usually bigger: a shadow, a glow, a focus * ring, an outline offset. Cropping to the border box cuts exactly the pixels * a design review is looking at. So the rect is grown by the ink each element * actually casts, read from computed styles rather than assumed. */ export declare const PREVIEW_RUNTIME_JS: string; /** Apply `?theme=` / `?css=` / `?axis-=` from the stage URL, so a direct * visit can ask for a variant without an Explorer to click in. */ export declare const PREVIEW_URL_PARAMS_JS: string;