ogygia/markup

This page is generated from the package’s own .d.ts files on every build, so the signatures, descriptions and examples below always match the source.

import { … } from 'ogygia/markup';

Exports check_script · liftRegions · localizeMarks · restore · restoreRegions · scanRegions · transformMarkup · LiftedRegion · LiftResult · RegionSpan · Settled · RegionKind · TransformKind

check_script

function

The dev check's payload: each planned Svelte-owned host's original children, by its id.

function check_script(check: Record<string, string>): string;

liftRegions

function

Lift every TOP-LEVEL <ogygia-region> out of html, leaving an <og-lift> placeholder where each was. Hand shell to the foreign renderer (and, to render a lake / hole, its innerHtml — recurse with liftRegions there so islands nested inside it stay protected), then restoreRegions. Islands come back verbatim. A region deeper than top level rides inside its parent's outerHtml.

function liftRegions(html: string): LiftResult;

localizeMarks

function

STABLE MARKS FOR A CACHING TRANSFORM. ogygia numbers hosts across the whole document, so the same block carries other ids on another page, and a render cache keyed on its markup never hits. localizeMarks(block) renumbers the block's marks from 0 (in order of appearance): cache on the result, then back(rendered) puts the document's ids back on whatever the render returned.

const local = localizeMarks(block);
const rendered = cache.get(local.html) ?? cache.set(local.html, await render(local.html));
return local.back(rendered);

function localizeMarks(html: string): {
  html: string;
  back: (rendered: string) => string;
};

restore

function

THE RESTORER — the browser half of reversible transforms (server/reversible.ts). An app's server transform rendered each planned custom element (og-h) in scoped form: its rendered tree in the host's light DOM, Svelte's children moved into <slot> wrappers inside it. This puts it back into the form hydration and the component's runtime both expect:

1. stand-ins (<og-as tag="a">: tags the HTML parser would have restructured) become their real element, in place — a DOM operation, which no content-model rule applies to;
2. for each planned host, innermost first: an open shadow root with the host's keyed sheets, the rendered tree moved into it (its <slot> wrappers become real slots), Svelte's children back in the light DOM in their original order and exactly as Svelte rendered them (attributes reset, trimmed or dropped text put back), the host's attributes back to Svelte's (except og-keep).

The page stays painted the same throughout: the scoped form and the shadow form render alike, and each host is restored in one task. It must run before anything reads the markup — before an island snapshots or hydrates, before Kit starts, before a web-component runtime upgrades a host. So the handle inlines it at the end of the document's body (restore.toString(): this function is self-contained, no imports, no outer names), and the runtime calls it on a hole / lake answer before insertion and on an incoming page before a router swap.

A host that already has a shadow root when it is reached was upgraded first — the restore came too late. It is left as served and reported (ogygia:restore-late on the host), never restored into a root the component's own constructor made (that tree would render twice).

function restore(root: Document | DocumentFragment | Element): number;

restoreRegions

function

Splice lifted regions back over their <og-lift> placeholders, transplanting any attributes the foreign renderer stamped on a placeholder (scoped slot marks — a sc-* class, c-id, s-sn) onto the region's opening tag. The placeholder is matched loosely because the renderer annotates it; only opening-tag attributes are merged, never the region's light DOM. An unknown placeholder is left in place rather than dropped.

function restoreRegions(shell: string, regions: readonly LiftedRegion[]): string;

scanRegions

function

Yield every <ogygia-region> in html, in document order, an island's subtree treated as atomic (its nested regions are not yielded). One linear pass, O(html length); allocates no copy of the document. See the module doc for why this exists and how to use it.

function scanRegions(html: string): Generator<RegionSpan, void, undefined>;

transformMarkup

function

The whole server round trip for one piece of markup: mark → the app's transform → settle. Kit-free (exported from ogygia/markup for tests that harvest markup and run a transform over it).

function transformMarkup(html: string, transform: (html: string) => string | Promise<string>, opts?: {
  kind?: TransformKind;
  csr?: boolean;
  dev?: boolean;
}): Promise<Settled>;

LiftedRegion

interface

interface LiftedRegion {/*…*/}

LiftedRegion.kind

island bytes must be restored VERBATIM (reshaping them breaks hydration); a lake / hole MAY be reshaped first via LiftedRegion.withInner.

readonly kind: RegionKind;

LiftedRegion.attrs

The opening tag's attributes (wake / endpoint / entry …), lower-cased.

readonly attrs: Readonly<Record<string, string>>;

LiftedRegion.openTag

<ogygia-region …> — the opening tag, verbatim.

readonly openTag: string;

LiftedRegion.innerHtml

The region's inner HTML ('' for a self-closed or unterminated region).

readonly innerHtml: string;

LiftedRegion.closeTag

</ogygia-region> — the closing tag ('' for a self-closed or unterminated region).

readonly closeTag: string;

LiftedRegion.outerHtml

openTag + innerHtml + closeTag.

readonly outerHtml: string;

LiftedRegion.index

Ties this region to its <og-lift data-i="…"> placeholder in the shell.

readonly index: number;

LiftedRegion.withInner

A copy with the inner HTML replaced — for a lake / hole whose inner a caller has rendered. The opening / closing tags and the index are preserved. Do NOT call this for an island.

withInner(innerHtml: string): LiftedRegion;

LiftResult

interface

interface LiftResult {/*…*/}

LiftResult.shell

The document with every TOP-LEVEL region replaced by an <og-lift data-i="…"></og-lift> placeholder — the only part a foreign renderer should be handed.

shell: string;

LiftResult.regions

The lifted regions, in document order, index-aligned to their placeholders.

regions: LiftedRegion[];

RegionSpan

interface

interface RegionSpan {/*…*/}

RegionSpan.kind

island = a hydrated region (its bytes are off-limits to any post-SSR reshaping); lake = a frozen (wake="none") subtree, server HTML the browser never re-creates; hole = a deferred region whose current markup is the page's fallback, not a hydration tree.

kind: RegionKind;

RegionSpan.start

Index of the < that opens <ogygia-region …>.

start: number;

RegionSpan.end

Index one past the > that closes </ogygia-region>. [start, end) is the whole element.

end: number;

RegionSpan.innerStart

Index one past the > of the OPENING tag — the first byte of the region's inner HTML.

innerStart: number;

RegionSpan.innerEnd

Index of the < of the CLOSING tag — one past the last byte of the inner HTML. [innerStart, innerEnd) is the inner HTML a reshaping pass may edit for a lake / hole.

innerEnd: number;

RegionSpan.attrs

The opening tag's attributes (unquoted values). Read wake / endpoint / entry here.

attrs: Readonly<Record<string, string>>;

RegionSpan.depth

Nesting depth — 0 for a top-level region, 1 for one directly inside a lake / hole, and so on. Island subtrees are never entered, so a region deeper than 0 is always inside a lake or hole (never inside another island).

depth: number;

Settled

interface

interface Settled {/*…*/}

Settled.html

html: string;

Settled.planned

planned hosts (with a shadow plan) — the page needs the restorer

planned: number;

Settled.stand_ins

stand-ins written

stand_ins: number;

Settled.head

data-og-head assets lifted out of a document's body, for its head (deduped by key)

head: string[];

Settled.check

dev: each planned Svelte-owned host's original children, for the browser's check

check?: Record<string, string>;

RegionKind

type

type RegionKind = "island" | "lake" | "hole";

TransformKind

type

document: a page render. region: a region answer (a hole, a lake remount) — every custom element in it gets a plan, since the page morphs it over live hosts.

type TransformKind = "document" | "region";