@runtypelabs/persona 4.19.0 → 4.21.0

package/src/client.ts

@@ -566,6 +566,54 @@ export class AgentWidgetClient {
     return this.clientSession;
   }
 
+  /** Persona's built-in reconnect transport for client-token sessions. */
+  public async reconnectClientTokenStream(ctx: {
+    executionId: string;
+    after: string;
+    signal: AbortSignal;
+  }): Promise<Response> {
+    let session = await this.initSession();
+    let recovered = false;
+
+    for (;;) {
+      const conversationId = session.conversationId;
+      const visitorToken = await this.readVisitorToken();
+      if (session.durableRecovery?.enabled !== true || !conversationId || !visitorToken) {
+        throw new HistoryClientError(
+          'visitor_token_missing',
+          'Durable recovery is not enabled for this client session'
+        );
+      }
+      const path =
+        `${this.clientApiBase()}/v1/client/conversations/` +
+        `${encodeURIComponent(conversationId)}/executions/` +
+        `${encodeURIComponent(ctx.executionId)}/events`;
+      const query = new URLSearchParams({
+        sessionId: session.sessionId,
+        after: ctx.after,
+      });
+      const response = await fetch(`${path}?${query}`, {
+        method: 'GET',
+        headers: {
+          'X-Persona-Version': VERSION,
+          'X-Visitor-Token': visitorToken,
+        },
+        signal: ctx.signal,
+      });
+      if (response.status === 401 && !recovered) {
+        recovered = true;
+        session = await this.recoverFromUnauthorized(
+          await this.readErrorCode(response),
+          null,
+          true
+        );
+        continue;
+      }
+      if (!response.ok) throw await this.historyErrorFor(response, true);
+      return response;
+    }
+  }
+
   /**
    * Initialize session for client token mode.
    * Called automatically on first message if not already initialized.
@@ -709,13 +757,18 @@ export class AgentWidgetClient {
    */
   private async createClientSession(opts: {
     conversationId?: string;
+    durableResume?: boolean;
     identityProof?: string | null;
     storedSessionId?: string | null;
     omitVisitorFields?: boolean;
   }): Promise<ClientSession> {
     const historyCapable = this.isHistoryCapable() && !opts.omitVisitorFields;
+    // Recovery is negotiated independently from the history UI. New servers
+    // return an explicit capability bit; old strict servers reject the
+    // additive request field, which the fallback below handles once.
+    const durableRecoveryRequested = !opts.omitVisitorFields;
     let visitorToken: string | null = null;
-    if (historyCapable) {
+    if (historyCapable || durableRecoveryRequested) {
       // Never read persisted state before the controller's stored-state gate.
       await this.historyInternals.historyBootstrapReady;
       visitorToken = await this.readVisitorToken();
@@ -723,12 +776,16 @@ export class AgentWidgetClient {
 
     const routed = this.routing();
     const sessionTargetId = routed.agentId ?? routed.flowId;
-    const resumeConversationId = historyCapable ? opts.conversationId : undefined;
+    const resumeConversationId =
+      historyCapable || opts.durableResume ? opts.conversationId : undefined;
     const requestBody: Record<string, unknown> = {
       token: this.config.clientToken,
       ...(sessionTargetId && { flowId: sessionTargetId }),
       ...(historyCapable && { visitorHistory: true }),
-      ...(historyCapable && visitorToken ? { visitorToken } : {}),
+      ...(durableRecoveryRequested && { durableRecovery: true }),
+      ...((historyCapable || durableRecoveryRequested) && visitorToken
+        ? { visitorToken }
+        : {}),
       // Independent of the strict conversationId/sessionId union: a proof also
       // binds the visitor on an ordinary init.
       ...(historyCapable && opts.identityProof
@@ -741,7 +798,7 @@ export class AgentWidgetClient {
           : {}),
     };
 
-    const response = await fetch(this.getClientApiUrl('init'), {
+    let response = await fetch(this.getClientApiUrl('init'), {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
@@ -750,6 +807,22 @@ export class AgentWidgetClient {
       body: JSON.stringify(requestBody),
     });
 
+    // Rolling/self-hosted compatibility: pre-recovery servers use a strict
+    // init schema and answer 400 to the additive field. Retry once without it;
+    // the absent response capability keeps Persona on ordinary streaming.
+    if (response.status === 400 && durableRecoveryRequested) {
+      const fallbackBody = { ...requestBody };
+      delete fallbackBody.durableRecovery;
+      response = await fetch(this.getClientApiUrl('init'), {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Persona-Version': VERSION,
+        },
+        body: JSON.stringify(fallbackBody),
+      });
+    }
+
     if (!response.ok) {
       const error = await response.json().catch(() => ({ error: 'Session initialization failed' }));
       if (historyCapable && response.status === 403 && error.error === 'visitor_history_disabled') {
@@ -763,7 +836,17 @@ export class AgentWidgetClient {
         }
         return this.createClientSession({ ...opts, omitVisitorFields: true });
       }
-      if (historyCapable && response.status === 401 && error.error === 'visitor_required') {
+      if (response.status === 403 && error.error === 'durable_recovery_disabled') {
+        throw new HistoryClientError(
+          'history_disabled',
+          'Durable recovery is disabled for this surface'
+        );
+      }
+      if (
+        (historyCapable || opts.durableResume) &&
+        response.status === 401 &&
+        error.error === 'visitor_required'
+      ) {
         throw new HistoryClientError('visitor_required', 'Visitor credential no longer resolves');
       }
       if (resumeConversationId && response.status === 404) {
@@ -797,6 +880,7 @@ export class AgentWidgetClient {
       ...(data.conversationRevision
         ? { conversationRevision: data.conversationRevision }
         : {}),
+      ...(data.durableRecovery ? { durableRecovery: data.durableRecovery } : {}),
       ...(data.visitor ? { visitor: data.visitor } : {}),
       config: {
         welcomeMessage: data.config.welcomeMessage,
@@ -807,15 +891,13 @@ export class AgentWidgetClient {
   }
 
   private async _doInitSession(): Promise<ClientSession> {
-    if (!this.isHistoryCapable()) {
-      const storedSessionId = this.config.getStoredSessionId?.() || null;
-      const session = await this.createClientSession({ storedSessionId });
-      this.config.setStoredSessionId?.(session.sessionId);
-      return session;
-    }
-
     await this.historyInternals.historyBootstrapReady;
     const previousConversationId = this.config.getStoredConversationId?.() || null;
+    const durableResume =
+      this.historyInternals.shouldResumeDurableConversation?.() === true;
+    if (!this.isHistoryCapable() && !durableResume) {
+      return this.ordinaryInit(previousConversationId, false);
+    }
     const storedToken = await this.readVisitorToken();
 
     // Boot resume: reopening the record beats replaying a possibly idle-expired
@@ -824,15 +906,23 @@ export class AgentWidgetClient {
       try {
         const resumed = await this.createClientSession({
           conversationId: previousConversationId,
+          durableResume,
         });
+        if (durableResume && resumed.durableRecovery?.enabled !== true) {
+          this.historyInternals.setStoredResumableHandle?.(null);
+        }
         return this.finishInit(resumed, previousConversationId, false);
       } catch (error) {
         if (
           !isHistoryClientError(error, 'not_found') &&
-          !isHistoryClientError(error, 'visitor_required')
+          !isHistoryClientError(error, 'visitor_required') &&
+          !isHistoryClientError(error, 'history_disabled')
         ) {
           throw error;
         }
+        if (durableResume) {
+          this.historyInternals.setStoredResumableHandle?.(null);
+        }
         // Record gone or credential dead: exactly one ordinary fallback, never a loop.
         return this.ordinaryInit(previousConversationId, true);
       }
@@ -851,7 +941,7 @@ export class AgentWidgetClient {
     continuityBroken: boolean
   ): Promise<ClientSession> {
     const store = this.historyInternals.visitorStore;
-    if (store && this.isHistoryCapable() && !(await this.readVisitorToken())) {
+    if (store && !(await this.readVisitorToken())) {
       return store.withFirstInitLock(() =>
         this.doOrdinaryInit(previousConversationId, continuityBroken)
       );
@@ -893,7 +983,11 @@ export class AgentWidgetClient {
    * unowned; one immediate re-init with `{visitorToken, sessionId}` claims it.
    */
   private async claimFirstConversation(first: ClientSession): Promise<ClientSession> {
-    if (!first.visitor?.token || this.claimInFlight || !this.isHistoryCapable()) {
+    if (
+      !first.visitor?.token ||
+      this.claimInFlight ||
+      (!this.isHistoryCapable() && first.durableRecovery?.enabled !== true)
+    ) {
       return first;
     }
     this.claimInFlight = true;
@@ -1754,6 +1848,10 @@ export class AgentWidgetClient {
 
       // Build the standard payload to get context/metadata from middleware
       const basePayload = await this.buildPayload(options.messages);
+      const recoveryVisitorToken =
+        session.durableRecovery?.enabled === true
+          ? await this.readVisitorToken()
+          : null;
 
       // Build the chat request payload with message IDs for feedback tracking
       // Filter out sessionId from metadata if present (it's only for local storage)
@@ -1813,6 +1911,9 @@ export class AgentWidgetClient {
             headers: {
               'Content-Type': 'application/json',
               'X-Persona-Version': VERSION,
+              ...(recoveryVisitorToken
+                ? { 'X-Visitor-Token': recoveryVisitorToken }
+                : {}),
             },
             body: JSON.stringify(chatRequest),
             signal: options.signal,
@@ -2221,7 +2322,7 @@ export class AgentWidgetClient {
   public async resumeFlow(
     executionId: string,
     toolOutputs: Record<string, unknown>,
-    options?: { streamResponse?: boolean; signal?: AbortSignal }
+    options?: { streamResponse?: boolean; signal?: AbortSignal; after?: string }
   ): Promise<Response> {
     const isClientToken = this.isClientTokenMode();
     const url = isClientToken
@@ -2236,12 +2337,18 @@ export class AgentWidgetClient {
     // trusting the possibly-stale `this.clientSession`. (core#3889; BugBot
     // PR #214 r3367875360.)
     let resumeSessionId: string | undefined;
+    let resumeVisitorToken: string | null = null;
     if (isClientToken) {
-      resumeSessionId = (await this.initSession()).sessionId;
+      const session = await this.initSession();
+      resumeSessionId = session.sessionId;
+      if (session.durableRecovery?.enabled === true) {
+        resumeVisitorToken = await this.readVisitorToken();
+      }
     }
 
     let headers: Record<string, string> = {
       'Content-Type': 'application/json',
+      ...(resumeVisitorToken ? { 'X-Visitor-Token': resumeVisitorToken } : {}),
       ...this.headers
     };
     if (this.getHeaders) {
@@ -2252,6 +2359,7 @@ export class AgentWidgetClient {
       executionId,
       toolOutputs,
       streamResponse: options?.streamResponse ?? true,
+      ...(options?.after ? { after: options.after } : {}),
     };
     // Thread the (refreshed) sessionId through like `/v1/client/chat` does.
     if (resumeSessionId) {
@@ -2737,9 +2845,10 @@ export class AgentWidgetClient {
     // bubble-id segmentation on the wire in place of the legacy `partId`:
     // a new block id means a new bubble, sealed at `text_complete`/tool boundaries.
     let currentTextBlockId: string | null = null;
-    // Raw text accumulated for the open flow block before its bubble is
-    // materialized — lets a whitespace-only block resolve without a stray bubble.
-    let pendingFlowRaw = "";
+    // Raw text accumulated for the open text block, on both the flow and agent
+    // paths — lets a whitespace-only flow block resolve without a stray bubble,
+    // and gives the structured-content parser the whole block on either path.
+    let pendingTextRaw = "";
     // Nested flow-as-tool attribution (PR #4602): a text/reasoning block whose
     // `parentToolCallId` matches a `tool_start.toolCallId` belongs to a flow
     // running as that tool. Keyed by the wire block id, these route the block's
@@ -3134,20 +3243,20 @@ export class AgentWidgetClient {
       finalizeCleanup();
     };
 
-    // === Unified flow text channel ===
-    // Flow prompt-step text streams as `text_delta` blocks (segmented by
-    // `text_start`/`text_complete`) and can be structured JSON, so each block
-    // runs through the per-bubble structured-content parser — agent text stays
-    // plain. This is the legacy step_delta parser core, re-keyed from `partId`
-    // to the wire block-id bubble. The caller materializes the bubble lazily
-    // (whitespace-only blocks around tool boundaries never leave a stray bubble)
-    // and `step_complete.result.response` reconciles the authoritative final.
+    // === Unified text channel ===
+    // Prompt-step and agent text both stream as `text_delta` blocks (segmented by
+    // `text_start`/`text_complete`) and can be structured JSON, so each block runs
+    // through the per-bubble structured-content parser. This is the legacy
+    // step_delta parser core, re-keyed from `partId` to the wire block-id bubble.
+    // The caller materializes the bubble lazily (whitespace-only blocks around
+    // tool boundaries never leave a stray bubble) and `step_complete.result.response`
+    // reconciles the authoritative final.
     let lastSealedFlowBubble: AgentWidgetMessage | null = null;
 
-    // Stream one accumulated chunk of flow block text through the parser, setting
+    // Stream one accumulated chunk of block text through the parser, setting
     // display `content` (extracted) + `rawContent` (raw) and emitting. Mirrors the
     // legacy step_delta chunk path; plain text bypasses the structured parser.
-    const applyFlowTextChunk = (
+    const applyTextChunk = (
       assistant: AgentWidgetMessage,
       accumulatedRaw: string,
       chunk: string,
@@ -3773,7 +3882,7 @@ export class AgentWidgetClient {
           }
           currentTextBlockId =
             typeof payload.id === "string" ? payload.id : currentTextBlockId;
-          pendingFlowRaw = "";
+          pendingTextRaw = "";
         } else if (payloadType === "text_delta") {
           // Nested flow-as-tool text: route to the parent tool's row, through the
           // same structured-content parser, never the top-level assistant channel.
@@ -3793,7 +3902,7 @@ export class AgentWidgetClient {
               executionId: payload.executionId,
               parentToolId: nestedParent,
             };
-            applyFlowTextChunk(nested, nestedRaw, nestedDelta, undefined);
+            applyTextChunk(nested, nestedRaw, nestedDelta, undefined);
             continue;
           }
           currentTextBlockId =
@@ -3804,27 +3913,36 @@ export class AgentWidgetClient {
             // block-id bubble. Materialize lazily so a whitespace-only block
             // (newlines around a tool boundary) never leaves a stray bubble.
             const delta = typeof payload.delta === "string" ? payload.delta : "";
-            pendingFlowRaw += delta;
-            if (pendingFlowRaw.trim() === "") continue;
+            pendingTextRaw += delta;
+            if (pendingTextRaw.trim() === "") continue;
             const assistant = ensureAssistantMessage();
             assistant.agentMetadata = {
               executionId: payload.executionId,
               iteration: payload.iteration,
             };
-            applyFlowTextChunk(assistant, pendingFlowRaw, delta, undefined);
+            applyTextChunk(assistant, pendingTextRaw, delta, undefined);
             lastAssistantInTurn = assistant;
             continue;
           }
+          // Agent text can be structured JSON too, whenever the host configures a
+          // custom `streamParser` (e.g. the page-context demo's `{"text": ...}` /
+          // `{"action": "add_to_cart", ...}` envelope). Accumulate the open block's
+          // raw text and run it through the same structured-content path the flow
+          // branch uses, so the parser sees the whole block and `rawContent` stays
+          // populated for the action manager. With the default plain-text parser
+          // this is byte-identical to appending the delta, so agent demos that
+          // stream prose are unaffected.
+          const agentDelta = typeof payload.delta === "string" ? payload.delta : "";
+          pendingTextRaw += agentDelta;
           const assistant = ensureAssistantMessage();
-          assistant.content += payload.delta ?? '';
           assistant.agentMetadata = {
             executionId: payload.executionId,
             iteration: payload.iteration,
             turnId: openTurnId ?? undefined,
             agentName: agentExecution?.agentName
           };
+          applyTextChunk(assistant, pendingTextRaw, agentDelta, undefined);
           lastAssistantInTurn = assistant;
-          emitMessage(assistant);
         } else if (payloadType === "text_complete") {
           // Nested flow-as-tool text block close: seal its parent-tool-row message.
           const completeBlockId = typeof payload.id === "string" ? payload.id : null;
@@ -3857,7 +3975,7 @@ export class AgentWidgetClient {
             assistantMessage = null;
           }
           currentTextBlockId = null;
-          pendingFlowRaw = "";
+          pendingTextRaw = "";
         } else if (payloadType === "step_complete") {
           // Only process completions for prompt steps, not tool/context steps
           const stepType = (payload as any).stepType;
@@ -4201,7 +4319,7 @@ export class AgentWidgetClient {
             assistantMessage = null;
           }
           currentTextBlockId = null;
-          pendingFlowRaw = "";
+          pendingTextRaw = "";
           lastSealedFlowBubble = null;
 
           // `terminal: true` marks this as a graceful finish (not a drop). The

package/src/components/composer-actions.ts

@@ -32,6 +32,7 @@ import type {
   ComposerActionOverflowConfig,
   ComposerActionPlacement,
   ComposerActionPresentation,
+  ComposerActionVisibility,
   ComposerButtonAction,
   ComposerCustomAction,
   ComposerState,
@@ -345,6 +346,28 @@ const evaluate = (
   return typeof value === "function" ? value(state) === true : value === true;
 };
 
+/**
+ * The draft state `sendButton.visibility` reads: text, a pending attachment, or
+ * a live stream all count as "there is something in flight".
+ */
+const hasDraftContent = (state: Readonly<ComposerState>): boolean =>
+  state.phase === "streaming" ||
+  state.text.trim().length > 0 ||
+  state.attachments.length > 0;
+
+/**
+ * `ComposerAction.visibility` against the current draft. Evaluated on every
+ * state-driven pass, so the answer is always render-time, never patched on.
+ */
+export function matchesComposerActionVisibility(
+  visibility: ComposerActionVisibility | undefined,
+  state: Readonly<ComposerState>
+): boolean {
+  if (!visibility || visibility === "always") return true;
+  const drafting = hasDraftContent(state);
+  return visibility === "when-text" ? drafting : !drafting;
+}
+
 const isCustom = (action: ComposerAction): action is ComposerCustomAction =>
   action.kind === "custom";
 
@@ -937,7 +960,10 @@ export function createComposerActionRenderer(
       let entry = entries.get(resolved.id);
       if (!entry) continue;
       const action = resolved.action;
-      const visible = action ? evaluate(action.visible, state, true) : true;
+      const visible = action
+        ? evaluate(action.visible, state, true) &&
+          matchesComposerActionVisibility(action.visibility, state)
+        : true;
       if (entry.visible !== visible) {
         entry.visible = visible;
         // Managed elements leave the DOM when hidden; the node (and any custom

package/src/components/composer-model-picker.ts

@@ -18,6 +18,7 @@ import { createPopover, type PopoverHandle } from "../plugin-kit";
 import type { ComposerCustomAction, ComposerModel } from "../types";
 import { createElement, createNode } from "../utils/dom";
 import { renderLucideIcon } from "../utils/icons";
+import { forwardMenuTokens } from "./composer-parts";
 
 export const COMPOSER_MODEL_PICKER_ACTION_ID = "core:model";
 export const COMPOSER_MODEL_PICKER_ORDER = 700;
@@ -25,9 +26,8 @@ export const COMPOSER_MODEL_PICKER_ORDER = 700;
 const ROW_ICON_SIZE = 16;
 
 /**
- * Tokens the popover panel reads. It is portaled outside the themed mount, so
- * configured values are forwarded onto it on open; unset ones stamp nothing and
- * the stylesheet's fallbacks stand.
+ * Tokens the popover panel reads, forwarded onto the portaled panel on every
+ * open; unset ones clear so the stylesheet's fallbacks stand.
  */
 const MENU_TOKEN_VARS = [
   "--persona-components-composer-modelPicker-menuBackground",
@@ -62,16 +62,6 @@ export interface ComposerModelPicker {
   repaint: () => void;
 }
 
-const forwardMenuTokens = (from: HTMLElement, to: HTMLElement): void => {
-  const view = from.ownerDocument?.defaultView;
-  if (!view) return;
-  const computed = view.getComputedStyle(from);
-  for (const name of MENU_TOKEN_VARS) {
-    const value = computed.getPropertyValue(name).trim();
-    if (value) to.style.setProperty(name, value);
-  }
-};
-
 /** The wrapper both presentations share: one grid cell, control plus chevron. */
 const createWrapper = (): { wrapper: HTMLElement; chevron: HTMLElement } => {
   // `appearance: none` drops the platform chevron, which Chrome draws
@@ -221,7 +211,7 @@ export function createComposerModelPickerAction(
           onDismiss: () => trigger.setAttribute("aria-expanded", "false"),
         });
       }
-      forwardMenuTokens(trigger, menu);
+      forwardMenuTokens(trigger, menu, MENU_TOKEN_VARS);
       popover.open();
       trigger.setAttribute("aria-expanded", "true");
       const ids = [...rows.keys()];

package/src/components/composer-overflow-menu.ts

@@ -19,6 +19,7 @@ import {
   COMPOSER_CONTROL_CLASS,
   COMPOSER_CONTROL_GLYPH_CLASS,
   COMPOSER_CONTROL_ICON_FALLBACK_PX,
+  forwardMenuTokens,
 } from "./composer-parts";
 
 export interface ComposerOverflowMenuOptions {
@@ -54,6 +55,18 @@ export interface ComposerOverflowMenu {
 const focusableSelector =
   'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
 
+/**
+ * Panel surface tokens, forwarded onto the portaled panel on every open; unset
+ * ones clear so the stylesheet's fallbacks stand.
+ */
+const MENU_TOKEN_VARS = [
+  "--persona-components-composer-overflowMenu-background",
+  "--persona-components-composer-overflowMenu-borderColor",
+  "--persona-components-composer-overflowMenu-borderRadius",
+  "--persona-components-composer-overflowMenu-foreground",
+  "--persona-components-composer-overflowMenu-shadow",
+] as const;
+
 /**
  * Set on the menu row that holds keyboard focus. Rows that shade on
  * `:focus-visible` do not need it; wrapper rows around a live control do.
@@ -249,6 +262,7 @@ export function createComposerOverflowMenu(
   const open = (focusIndex = 0, viaKeyboard = false): void => {
     if (destroyed || isOpen()) return;
     keyboardModality = viaKeyboard;
+    forwardMenuTokens(triggerButton, panel, MENU_TOKEN_VARS);
     ensurePopover().open();
     triggerButton.setAttribute("aria-expanded", "true");
     const targets = focusables();

package/src/components/composer-parts.ts

@@ -41,6 +41,26 @@ export const COMPOSER_CONTROL_FALLBACK_PX = 40;
 /** Icon-size token default in CSS pixels, for the same JS-derived cases. */
 export const COMPOSER_CONTROL_ICON_FALLBACK_PX = 24;
 
+/**
+ * Forward theme vars onto a portaled menu panel, which lives outside the
+ * themed mount. The panel is reused across opens, so an unset var must clear
+ * any previously stamped value for the stylesheet fallback to paint again.
+ */
+export const forwardMenuTokens = (
+  from: HTMLElement,
+  to: HTMLElement,
+  names: readonly string[]
+): void => {
+  const view = from.ownerDocument?.defaultView;
+  if (!view) return;
+  const computed = view.getComputedStyle(from);
+  for (const name of names) {
+    const value = computed.getPropertyValue(name).trim();
+    if (value) to.style.setProperty(name, value);
+    else to.style.removeProperty(name);
+  }
+};
+
 export interface ComposerTextareaParts {
   textarea: HTMLTextAreaElement;
   /**

package/src/generated/runtype-openapi-contract.ts

@@ -58,8 +58,10 @@ export type RuntypeExecutionStreamEvent = ({
   message: string;
 };
   executionId: string;
+  finalOutput?: string;
   kind: "agent" | "flow";
   seq: number;
+  stopReason?: string;
   type: "execution_error";
   upgradeUrl?: string;
 }) | ({

package/src/index-core.ts

@@ -91,6 +91,7 @@ export type {
   ComposerActionBase,
   ComposerActionPlacement,
   ComposerActionPresentation,
+  ComposerActionVisibility,
   ComposerButtonAction,
   ComposerCustomAction,
   ComposerActionContext,
@@ -103,6 +104,7 @@ export type {
   ComposerModelPickerPresentation,
   // Composer modes + mode groups (composer.modes, composer.modeGroups)
   ComposerMode,
+  ComposerModeChipVisibility,
   ComposerModeGroup,
   ComposerModeGroupPresentation,
   // Composer baseline configuration (submit keys, sizing, locks)