URL state is a protocol boundary—not a persistence layer.

interface ApplicationState {
  document: DocumentModel;
  session: AuthenticatedSession;
  runtime: RuntimeState;
  ui: InternalUiState;
}

interface UrlStateV2 {
  version: 2;
  documentId?: string;
  view: {
    tab: "editor" | "preview";
    filters: string[];
    zoom: number;
  };
  snapshot?: PortableDocumentSnapshot;
}

function projectUrlState(state: ApplicationState): UrlStateV2 {
  return {
    version: 2,
    documentId: state.document.persistedId,
    view: normalizeView(state.ui),
    snapshot: state.document.persistedId ? undefined : projectSnapshot(state.document)
  };
}

/workspaces/:workspaceId/documents/:documentId
  ?tab=preview
  &filter=security
  &filter=platform
  #s=v2.deflate.<base64url-payload>

export interface UrlStateBoundary<T> {
  read(url: URL): Promise<ReadResult<T>>;
  project(application: ApplicationState): T;
  normalize(candidate: unknown): T;
  migrate(envelope: UnknownEnvelope): CurrentEnvelope<T>;
  encode(state: T, target: "query" | "fragment"): Promise<URL>;
  write(url: URL, mode: "replace" | "push"): void;
  analyticsUrl(url: URL): URL;
}

export type ReadResult<T> =
  | { ok: true; state: T; source: "query" | "fragment" | "default" }
  | { ok: false; fallback: T; error: UrlStateError };

async function deflate(bytes: Uint8Array): Promise<Uint8Array> {
  const stream = new Blob([bytes])
    .stream()
    .pipeThrough(new CompressionStream("deflate"));

  return new Uint8Array(await new Response(stream).arrayBuffer());
}

async function inflateBounded(
  compressed: Uint8Array,
  maximumBytes = 256_000,
): Promise<Uint8Array> {
  const reader = new Blob([compressed])
    .stream()
    .pipeThrough(new DecompressionStream("deflate"))
    .getReader();

  const chunks: Uint8Array[] = [];
  let total = 0;

  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    total += value.byteLength;
    if (total > maximumBytes) {
      await reader.cancel("Decoded state exceeds limit");
      throw new RangeError("Decoded state exceeds limit");
    }
    chunks.push(value);
  }

  return concat(chunks, total);
}

{
  "version": 2,
  "schema": "url-state/document-snapshot",
  "createdAt": "2026-07-21T00:00:00Z",
  "snapshot": {
    "code": "flowchart LR ..."
  }
}