@multiplatform.one/forms 7.5.0 → 7.6.1

package/src/FieldDisplay/FieldDisplay.spec.tsx

@@ -119,11 +119,20 @@ describe("FieldDisplay", () => {
     expect(root?.getAttribute("data-field")).toBe("datepicker");
   });
 
-  it("draws a QR matrix when barcode fieldProps.formats starts with qr", () => {
+  /**
+   * The qr format reaches BarcodePreview (the round trip is asserted there),
+   * but a display cell's bound is the glyph size — around 20px — and a QR
+   * needs one WHOLE pixel per module, 29 minimum. So the cell draws no matrix
+   * and, because it already prints the value beside the symbol, contributes
+   * nothing rather than a second copy of the string (textFallback={false}).
+   * Growing the row to fit a scannable square is the thing LC-06 forbids.
+   */
+  it("prints the barcode value once and draws no unreadable QR at a display bound", () => {
     const result = renderWithProviders(
       <FieldDisplay field="barcode" value="SKU-001234" fieldProps={{ formats: ["qr"] }} />,
     );
-    expect(result.container.querySelector('[data-testid="barcode-preview-qr"]')).not.toBeNull();
+    expect(result.container.querySelector('[data-testid="barcode-preview-qr"]')).toBeNull();
     expect(result.container.querySelector("canvas")).toBeNull();
+    expect(result.container.textContent?.split("SKU-001234").length).toBe(2); // exactly once
   });
 });

package/src/FieldDisplay/index.tsx

@@ -563,11 +563,16 @@ function BarcodeDisplay({ value, fieldProps }: { value: any; fieldProps?: Record
   return (
     <XStack alignItems="center" minWidth={0} flexShrink={1} {...knobProps.gap}>
       <ValueText mono>{text}</ValueText>
+      {/* The value is already printed beside the symbol, so an undrawable one
+          contributes NOTHING rather than a second copy of the string. At this
+          bound that is every QR past a short value at a large size — a display
+          cell cannot hold 33 whole-pixel modules without growing the row. */}
       <BarcodePreview
         value={text}
         height={Math.max(12, glyphSize)}
         moduleWidth={1}
         format={typeof format === "string" ? format : undefined}
+        textFallback={false}
       />
     </XStack>
   );

package/src/FloatingPanel/index.tsx

@@ -607,6 +607,18 @@ function FloatingPanelWeb({
   // animation=none → no CSS tween (same contract as knobProps.transition === undefined)
   const webTransition = panel.knobProps.transition ? panelTransition : "none";
 
+  // `elevatedSurface` carries a web-only `style: { boxShadow }` (MPO-69,
+  // d326cc0c2). Two `style` props on one element do NOT merge — the later
+  // spread replaces the earlier — so spreading the complete fragment after the
+  // positioning style silently dropped `position: fixed`, `top`, `left`,
+  // `zIndex` and `overflow`, and every web FloatingPanel rendered in normal
+  // flow, pushing the page down instead of floating over it. Measured on
+  // origin/main 048289071: DatePicker's panel sat at trigger.bottom + 5.39 (the
+  // field container's flex gap), not the contract's 0.
+  // The complete fragment still goes on the element (AGENTS.md) — its style is
+  // folded into the positioning style rather than competing with it.
+  const { style: elevatedSurfaceStyle, ...elevatedSurfaceProps } = panel.knobProps.elevatedSurface;
+
   // Same slot problem as the sheet branch, but only half of it lands here. The
   // POINTER path survives, because `useClick(..., { event: "mousedown" })`
   // listens on mousedown and Tamagui only stops the click. The KEYBOARD path
@@ -650,6 +662,13 @@ function FloatingPanelWeb({
         })}
         cursor={disabled ? "not-allowed" : "pointer"}
         opacity={disabled ? 0.5 : 1}
+        // The cover contract is stated as a relation between the panel's top
+        // edge and THIS element's bottom edge — the box floating-ui anchors
+        // to, which is the whole trigger, not whatever glyph inside it was
+        // clicked. Marking it keeps the measurement unambiguous (a ColorPicker
+        // read from its swatch measures the swatch's inset, not the gap).
+        // Same idiom TreeSelect already uses for `data-fp-panel`.
+        data-fp-reference=""
       >
         {trigger}
       </View>
@@ -659,6 +678,7 @@ function FloatingPanelWeb({
           {...getFloatingProps({
             ref: panel.refs.setFloating,
             style: {
+              ...elevatedSurfaceStyle,
               position: panel.strategy,
               top: overlayStyleRef.current?.top ?? panel.y ?? 0,
               left: panel.x ?? 0,
@@ -675,9 +695,10 @@ function FloatingPanelWeb({
             onScroll: handleScroll,
           })}
           data-testid="floating-panel-viewport"
+          data-fp-panel=""
           {...panelChromeFocus}
           pointerEvents={panel.visible ? "auto" : "none"}
-          {...panel.knobProps.elevatedSurface}
+          {...elevatedSurfaceProps}
           // Complete elevatedSurface fragment above is the ONLY surface source
           // (SF-OVERLAY "including border and elevation", Round 2 docket).
           // The one layered exception is anatomy, not surface: the dropdown

package/src/FloatingPanel/panelWidthContract.spec.ts

@@ -27,6 +27,7 @@ const fieldShapedPickers = [
   "DatePicker/DatetimePicker.tsx",
   "TimePicker/index.tsx",
   "ColorPicker/parts.tsx",
+  "Icon/index.tsx",
 ];
 
 /** Panels opened from an icon/button trigger, where fit-content is correct. */

package/src/InputParts/index.tsx

@@ -819,6 +819,7 @@ const InputAreaImpl = InputFrame.styleable<{
         {...knobProps.body}
         type={secureTextEntry ? "password" : props.type}
         padding={0}
+        // size-recipe-escape: zero-reset — Input.Box owns the inset (LC-71); the inner field paints no padding
         paddingHorizontal={0}
         paddingVertical={0}
         keyboardType={resolvedKeyboardType}
@@ -907,24 +908,115 @@ const InputButton = styled(TButton, {
   } as const,
 });
 
-const InputButtonImpl = InputButton.styleable((buttonProps, ref) => {
+/**
+ * LC-71 RING-ANATOMY / LC-49 ONE-TAB-STOP — the `glyphRing` end cap.
+ *
+ * A bare Input.Button is DECORATIVE: the Box rings for it and it takes no
+ * tab stop of its own (Stepper carets, Select/Combobox chevrons). Pass
+ * `glyphRing` to promote it to the field's SECOND focusable — the Password
+ * reveal, the CopyField copy — where it must ring its own GLYPH, not the
+ * 44px hit box. A band on the box would double with the Box's composite
+ * ring; a band on the glyph is the chip-dismiss recipe
+ * (`.mp-chip-dismiss` + `.mp-chip-dismiss-ring`, keyboardFocusRing.ts).
+ *
+ * It renders a View rather than TButton because TButton swallows a consumer
+ * className and pins its own tabIndex, so the ring class never reaches the
+ * node that actually receives focus. SearchInput hand-rolled exactly this
+ * pair for that reason (fields/SearchInput/index.tsx:348-380) and left a
+ * note saying the classes "cannot ride Input.Button until glyphRing" lands.
+ * This is that pair made reusable, so the square comes from the size recipe
+ * (LC-70) instead of every call site measuring its own.
+ */
+const InputGlyphButton = styled(View, {
+  name: "InputGlyphButton",
+  context: InputContext,
+  justifyContent: "center",
+  alignItems: "center",
+  backgroundColor: "transparent",
+  borderWidth: 0,
+  borderRadius: 0,
+  cursor: "pointer",
+  flexShrink: 0,
+  outlineWidth: 0,
+  focusStyle: { outlineWidth: 0 },
+  focusVisibleStyle: { outlineWidth: 0 },
+
+  variants: {
+    scaleIcon: {
+      ":number": {} as any,
+    },
+    size: {
+      ...sizeRecipeEndCapVariants,
+      "...size": sizeRecipeEndCapFallback,
+    },
+  } as const,
+});
+
+const InputButtonImpl = InputButton.styleable<{ glyphRing?: boolean }>((buttonProps, ref) => {
   const {
     children,
     color: colorProp,
+    glyphRing,
+    size: sizeProp,
+    tabIndex: tabIndexProp,
+    className,
     ...props
   } = buttonProps as typeof buttonProps & {
     color?: string;
+    glyphRing?: boolean;
+    size?: FontSizeTokens;
+    tabIndex?: number;
+    className?: string;
   };
-  const { size, color: contextColor } = InputContext.useStyledContext();
+  const { size: contextSize, color: contextColor } = InputContext.useStyledContext();
   const { knobProps } = useResolvedKnobs();
   const theme = useTheme();
-  const square = knobProps.control.height;
+  const size = (sizeProp ?? contextSize) as FontSizeTokens;
   const paint = resolveGlyphPaint(theme as never, colorProp ?? contextColor);
   const getThemedIcon = useGetThemedIcon({
     size: knobProps.controlIcon.width,
     color: paint as never,
   });
 
+  if (glyphRing) {
+    // A real tab stop must square off the token it was HANDED, not the
+    // knob's: a $2 field inside a $4 knob would otherwise ship a 44px stop
+    // on a 32px frame. LC-77 keeps the sub-floor case pressable via the
+    // caller's hitSlop, never by inflating the cap.
+    const square = sizeRecipeForToken(String(size ?? "$true"), { touch: isTouchSurface() }).height;
+    const disabled = (props as { disabled?: boolean }).disabled === true;
+    if (isWeb) ensureCompositeFocusRing();
+    return (
+      <InputGlyphButton
+        ref={ref as never}
+        role="button"
+        size={size}
+        height={square}
+        width={square}
+        paddingHorizontal={0} // size-recipe-escape: square end-cap; pad lives on Input.Box
+        opacity={disabled ? 0.5 : 1}
+        {...props}
+        aria-disabled={disabled || undefined}
+        tabIndex={tabIndexProp ?? (disabled ? -1 : 0)}
+        className={
+          isWeb
+            ? ["mp-chip-dismiss", className].filter(Boolean).join(" ")
+            : (className ?? undefined)
+        }
+        data-end-cap={square}
+      >
+        <View
+          className={isWeb ? "mp-chip-dismiss-ring" : undefined}
+          alignItems="center"
+          justifyContent="center"
+        >
+          {children}
+        </View>
+      </InputGlyphButton>
+    );
+  }
+
+  const square = knobProps.control.height;
   return (
     <InputButton
       ref={ref}
@@ -933,7 +1025,12 @@ const InputButtonImpl = InputButton.styleable((buttonProps, ref) => {
       width={square}
       paddingHorizontal={0} // size-recipe-escape: square end-cap; pad lives on Input.Box
       color={paint}
+      // LC-49: the decorative cap is not a tab stop. tabIndex alone is not
+      // enough — TButton re-derives focusability and stamps tabindex="0".
+      focusable={false}
       tabIndex={-1}
+      className={className}
+      data-end-cap={square}
       {...props}
     >
       {getThemedIcon(children)}

package/src/fields/Barcode/BarcodePreview.spec.tsx

@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { BarcodePreview, barcodePreviewSymbology } from "./BarcodePreview";
 import { countModules, encodeCode128B } from "./code128";
-import { encodeQr } from "./qr";
+import { QR_QUIET_ZONE_MODULES, encodeQr } from "./qr";
 import { resolveHtml5FormatIds, resolveNativeBarcodeTypes } from "./scannerTypes";
 
 /** Rebuild the module string ("1" = bar) from the encoder's runs. */
@@ -101,8 +101,27 @@ describe("barcodePreviewSymbology — scanner round trip", () => {
 });
 
 describe("BarcodePreview — qr format", () => {
+  /** The field's own default bound (Barcode/index.tsx): 36 comfortable, 24 compact. */
+  const formHeight = 36;
+
+  it("QR modules paint $color on $background (themed polarity; MPO-94 is not this lane)", () => {
+    const result = renderWithProviders(<BarcodePreview value="SHC-42" format="qr" height={120} />);
+    const square = result.container.querySelector(
+      '[data-testid="barcode-preview-qr"]',
+    ) as HTMLElement | null;
+    expect(square).not.toBeNull();
+    expect(square!.className).toContain("_bg-background");
+    const darkModule = [...square!.querySelectorAll("*")].find((el) =>
+      (el as HTMLElement).className?.toString().includes("_bg-color"),
+    ) as HTMLElement | undefined;
+    expect(darkModule).toBeTruthy();
+    expect(darkModule!.className).not.toMatch(/_bg-(?:white|black|color12)\b/);
+  });
+
   it("draws the QR matrix canvas-free (labeled image, real module rows)", () => {
-    const result = renderWithProviders(<BarcodePreview value="SKU-001234" format="qr" />);
+    const result = renderWithProviders(
+      <BarcodePreview value="SKU-001234" format="qr" height={formHeight} />,
+    );
     const preview = result.container.querySelector('[data-testid="barcode-preview"]');
     expect(preview).not.toBeNull();
     expect(preview?.getAttribute("aria-label")).toContain("SKU-001234");
@@ -114,12 +133,16 @@ describe("BarcodePreview — qr format", () => {
   });
 
   it("draws QR for the Frappe fieldtype's qrcode token via the shared alias table", () => {
-    const result = renderWithProviders(<BarcodePreview value="SKU-001234" format="qrcode" />);
+    const result = renderWithProviders(
+      <BarcodePreview value="SKU-001234" format="qrcode" height={formHeight} />,
+    );
     expect(result.container.querySelector('[data-testid="barcode-preview-qr"]')).not.toBeNull();
   });
 
   it("draws values the 1-D strip cannot encode (the closed asymmetry)", () => {
-    const result = renderWithProviders(<BarcodePreview value="héllo" format="qr" />);
+    const result = renderWithProviders(
+      <BarcodePreview value="héllo" format="qr" height={formHeight} />,
+    );
     expect(result.container.querySelector('[data-testid="barcode-preview-qr"]')).not.toBeNull();
   });
 
@@ -130,7 +153,9 @@ describe("BarcodePreview — qr format", () => {
 
   it("falls back to honest mono text past version 10 capacity", () => {
     const long = "x".repeat(214);
-    const result = renderWithProviders(<BarcodePreview value={long} format="qr" />);
+    const result = renderWithProviders(
+      <BarcodePreview value={long} format="qr" height={formHeight} />,
+    );
     expect(result.container.querySelector('[data-testid="barcode-preview-qr"]')).toBeNull();
     expect(result.container.textContent).toContain(long);
   });
@@ -141,3 +166,126 @@ describe("BarcodePreview — qr format", () => {
     expect(result.container.querySelector('[data-testid="barcode-preview"]')).not.toBeNull();
   });
 });
+
+/**
+ * Whole-pixel modules. Measured on the media-11 board at DPR 2 BEFORE this
+ * rule existed: bounds 33, 72 and 96 decoded and bounds 18, 24, 44 and 56 did
+ * not — not a size floor (33 read, 44 did not) but a resampling one. 33/33
+ * modules is exactly 1.000 px per module; 44/33 is 1.333, and a fractional
+ * module rounds to different widths across the grid. It reached the field's
+ * own default path: at height 36 / moduleWidth 1 a payload over 26 bytes
+ * clamps under one pixel per module and stops reading, which is precisely the
+ * scan-to-draw round trip MPO-53 AC-9 exists to close.
+ */
+describe("BarcodePreview — qr geometry is whole-pixel or nothing", () => {
+  const qrSquare = (ui: React.ReactElement) =>
+    renderWithProviders(ui).container.querySelector(
+      '[data-testid="barcode-preview-qr"]',
+    ) as HTMLElement | null;
+
+  /**
+   * Tamagui compiles geometry to atomic classes (`_w-87px`, `_pt-12px`), not
+   * inline style, so the measurement reads the class list. Same numbers, and
+   * it is the class the browser actually applies.
+   */
+  const px = (el: HTMLElement, prefix: string) => {
+    const hit = (el.getAttribute("class") ?? "")
+      .split(/\s+/)
+      .find((c) => c.startsWith(`_${prefix}-`));
+    return hit ? Number.parseFloat(hit.slice(prefix.length + 2)) : Number.NaN;
+  };
+  const edgeOf = (el: HTMLElement) => px(el, "w");
+  const quietOf = (el: HTMLElement) => px(el, "pt");
+
+  /** Modules per side including the 4-module quiet zone on each side. */
+  const totalModules = (value: string) => encodeQr(value)!.size + 2 * QR_QUIET_ZONE_MODULES;
+
+  it("draws at the natural size when moduleWidth fits under the bound", () => {
+    // 6 bytes → version 1 → 21 + 8 = 29 modules. moduleWidth 3 asks for 3px
+    // modules and the 120px bound allows 4, so 3 wins: 29 × 3 = 87.
+    const value = "SHC-42";
+    expect(totalModules(value)).toBe(29);
+    const square = qrSquare(
+      <BarcodePreview value={value} format="qr" height={120} moduleWidth={3} />,
+    );
+    expect(square).not.toBeNull();
+    expect(edgeOf(square!)).toBe(87);
+    expect(px(square!, "h")).toBe(87);
+    expect(quietOf(square!)).toBe(12); // 4 modules × 3px
+  });
+
+  it("treats the height bound as a CEILING, never a target", () => {
+    // 18 bytes → version 2 → 25 + 8 = 33 modules at moduleWidth 1 = 33px. A
+    // 44px bound does not stretch it to 44 and a fractional 1.333px module.
+    const value = "SHC-COMPOSE01-0417";
+    expect(totalModules(value)).toBe(33);
+    for (const height of [36, 44, 56]) {
+      const square = qrSquare(<BarcodePreview value={value} format="qr" height={height} />);
+      expect(edgeOf(square!)).toBe(33);
+      expect(quietOf(square!)).toBe(4);
+    }
+  });
+
+  it("snaps the module DOWN to a whole pixel rather than draw a fractional one", () => {
+    // 33 modules under a 96px bound would be 2.909px per module. Snap to 2.
+    const square = qrSquare(
+      <BarcodePreview value="SHC-COMPOSE01-0417" format="qr" height={96} moduleWidth={9} />,
+    );
+    expect(edgeOf(square!)).toBe(66);
+    expect(quietOf(square!)).toBe(8);
+  });
+
+  it("never draws a module narrower than one whole pixel — every bound, every payload", () => {
+    for (const value of ["SHC-42", "SHC-COMPOSE01-0417", "SHC-COMPOSE01-BACKUP-2026-08-28"]) {
+      for (const height of [18, 24, 29, 33, 36, 37, 44, 66, 96, 120]) {
+        for (const moduleWidth of [1, 2, 3]) {
+          const square = qrSquare(
+            <BarcodePreview value={value} format="qr" height={height} moduleWidth={moduleWidth} />,
+          );
+          if (!square) continue; // honest text fallback — asserted below
+          const edge = edgeOf(square);
+          const pad = quietOf(square);
+          const cell = edge / totalModules(value);
+          expect(Number.isInteger(cell)).toBe(true);
+          expect(cell).toBeGreaterThanOrEqual(1);
+          expect(cell).toBeLessThanOrEqual(moduleWidth);
+          expect(edge).toBeLessThanOrEqual(height); // LC-10 containment
+          expect(pad).toBe(cell * QR_QUIET_ZONE_MODULES);
+        }
+      }
+    }
+  });
+
+  it("falls back to honest text under one whole pixel per module", () => {
+    // compact (24) cannot hold 33 modules at a whole pixel each.
+    const value = "SHC-COMPOSE01-0417";
+    const result = renderWithProviders(<BarcodePreview value={value} format="qr" height={24} />);
+    expect(result.container.querySelector('[data-testid="barcode-preview-qr"]')).toBeNull();
+    expect(result.container.textContent).toContain(value);
+  });
+
+  it("falls back to honest text when the payload outgrows the form bound", () => {
+    // 31 bytes → version 3 → 29 + 8 = 37 modules, which does not fit 36px at
+    // one whole pixel each. This is the case that silently shipped unreadable.
+    const value = "SHC-COMPOSE01-BACKUP-2026-08-28";
+    expect(totalModules(value)).toBe(37);
+    const result = renderWithProviders(<BarcodePreview value={value} format="qr" height={36} />);
+    expect(result.container.querySelector('[data-testid="barcode-preview-qr"]')).toBeNull();
+    expect(result.container.textContent).toContain(value);
+  });
+
+  it("draws nothing at all when the host already shows the value (textFallback false)", () => {
+    const value = "SHC-COMPOSE01-0417";
+    const result = renderWithProviders(
+      <BarcodePreview value={value} format="qr" height={24} textFallback={false} />,
+    );
+    expect(result.container.querySelector('[data-testid="barcode-preview-qr"]')).toBeNull();
+    expect(result.container.textContent).not.toContain(value);
+  });
+
+  it("leaves the 1-D strip's geometry untouched", () => {
+    const result = renderWithProviders(<BarcodePreview value="SKU-001234" height={18} />);
+    expect(result.container.querySelector('[data-testid="barcode-preview"]')).not.toBeNull();
+    expect(result.container.querySelector('[data-testid="barcode-preview-qr"]')).toBeNull();
+  });
+});

package/src/fields/Barcode/BarcodePreview.stories.tsx

@@ -0,0 +1,104 @@
+/**
+ * BarcodePreview — the drawn face of the barcode field, not the input.
+ * Barcode.stories.tsx mounts the field; this file mounts the preview alone
+ * so Kitchen Sink can show QR and Code 128 without a scanner.
+ *
+ * QR polarity is themed ($color on $background). MPO-94 is Clay's call;
+ * these stories do not pin dark-on-light.
+ */
+
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Text, XStack, YStack } from "tamagui";
+import { BarcodePreview } from "./BarcodePreview";
+
+const meta: Meta<typeof BarcodePreview> = {
+  title: "Forms/BarcodePreview",
+  component: BarcodePreview,
+  parameters: {
+    status: { type: "stable" },
+    docs: {
+      description: {
+        component:
+          "Canvas-free barcode/QR preview. Theme ink on theme surface in both schemes. MPO-94 (pin vs themed QR polarity) is not taken here.",
+      },
+    },
+  },
+  argTypes: {
+    value: { control: "text" },
+    format: { control: "select", options: ["code128", "qr", "qrcode"] },
+    height: { control: "number" },
+    moduleWidth: { control: "number" },
+    showText: { control: "boolean" },
+    textFallback: { control: "boolean" },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof BarcodePreview>;
+
+export const Main: Story = {
+  name: "Main",
+  args: {
+    value: "SKU-001234",
+    height: 36,
+    showText: true,
+  },
+};
+
+export const Code128: Story = {
+  args: {
+    value: "SKU-001234",
+    format: "code128",
+    height: 36,
+    showText: true,
+  },
+};
+
+/**
+ * QR face (MPO-53 AC-9). Height 120 so a short payload draws at a whole
+ * pixel per module. Polarity stays themed — MPO-94 is not this lane.
+ */
+export const Qr: Story = {
+  args: {
+    value: "SHC-42",
+    format: "qr",
+    height: 120,
+    showText: true,
+  },
+};
+
+/** Host owns the empty marker; the preview paints nothing. */
+export const Empty: Story = {
+  render: () => (
+    <YStack gap="$2">
+      <Text fontSize="$2" color="$color10">
+        empty value — preview is null
+      </Text>
+      <BarcodePreview value="" format="qr" height={72} />
+    </YStack>
+  ),
+};
+
+/**
+ * Themed polarity specimen. Both faces paint $color on $background, so a
+ * scheme flip restyles them with the rest of the screen. Do not treat this
+ * as a pin-to-dark-on-light preview; that decision lives on MPO-94.
+ */
+export const ThemedPolarity: Story = {
+  render: () => (
+    <XStack gap="$6" flexWrap="wrap" padding="$4" alignItems="flex-end">
+      <YStack gap="$2" alignItems="center">
+        <Text fontSize="$2" color="$color10">
+          QR (themed)
+        </Text>
+        <BarcodePreview value="SHC-42" format="qr" height={120} showText />
+      </YStack>
+      <YStack gap="$2" alignItems="center">
+        <Text fontSize="$2" color="$color10">
+          Code 128 (themed)
+        </Text>
+        <BarcodePreview value="SKU-001234" format="code128" height={36} showText />
+      </YStack>
+    </XStack>
+  ),
+};

package/src/fields/Barcode/BarcodePreview.tsx

@@ -11,15 +11,16 @@
  *
  * Containment contract (LC-10): the symbol never exceeds its host. The strip
  * caps width at 100% and bars shrink proportionally (preserving relative
- * module widths) instead of painting past the frame; the QR square renders at
- * its natural module size and shrinks uniformly once the `height` bound
- * clamps it — always square, never letterboxed or clipped. Hosts bound the
- * height via the `height` prop (table cells keep it under the row height).
+ * module widths) instead of painting past the frame; the QR square is drawn at
+ * a WHOLE number of pixels per module, capped by `moduleWidth` and by the
+ * `height` bound — always square, never letterboxed or clipped. Hosts bound
+ * the height via the `height` prop (table cells keep it under the row height).
  *
  * Honest states: an empty value renders nothing (hosts show their own empty
  * marker); a value the symbology cannot encode (non-ASCII for Code 128 B,
- * over version 10 capacity for QR) falls back to the raw value as mono text —
- * never a fake or truncated symbol.
+ * over version 10 capacity for QR), or a QR whose modules would be under one
+ * whole pixel at the host's bound, falls back to the raw value as mono text —
+ * never a fake, truncated or unreadable symbol.
  */
 
 import { Text, View, XStack, YStack } from "tamagui";
@@ -44,10 +45,11 @@ export interface BarcodePreviewProps {
   value?: string;
   /**
    * Symbol height bound in px — content geometry, bounded by the host. The
-   * 1-D strip always fills it; the QR square uses it as a maximum edge.
+   * 1-D strip always fills it; the QR square uses it as a CEILING and draws at
+   * the largest whole-pixel module that fits under it.
    */
   height?: number;
-  /** Width of one barcode module in px. */
+  /** Width of one barcode module in px. Fractional values floor for QR. */
   moduleWidth?: number;
   /** Render the human-readable value under the symbol. */
   showText?: boolean;
@@ -56,6 +58,15 @@ export interface BarcodePreviewProps {
    * alias of `qr` draws the QR matrix; others draw the Code 128 strip.
    */
   format?: string;
+  /**
+   * Render the raw value as mono text when the symbology cannot draw it —
+   * non-ASCII for Code 128 B, over capacity or under one whole pixel per
+   * module for QR. Default true, which is right for a standalone preview:
+   * disappearing silently would be worse than an honest string. A host that
+   * ALREADY shows the value beside the symbol (FieldDisplay) passes false, so
+   * an undrawable symbol contributes nothing instead of printing it twice.
+   */
+  textFallback?: boolean;
 }
 
 /** Mono value text (LC-07 CODE-KNOB-IMMUNE) — both the honest fallback for
@@ -74,15 +85,22 @@ export function BarcodePreview({
   moduleWidth = 1,
   showText = false,
   format,
+  textFallback = true,
 }: BarcodePreviewProps) {
   if (!value) return null;
   if (barcodePreviewSymbology(format) === "qr") {
     return (
-      <QrPreview value={value} height={height} moduleWidth={moduleWidth} showText={showText} />
+      <QrPreview
+        value={value}
+        height={height}
+        moduleWidth={moduleWidth}
+        showText={showText}
+        textFallback={textFallback}
+      />
     );
   }
   const runs = encodeCode128B(value);
-  if (!runs) return <MonoValue value={value} />;
+  if (!runs) return textFallback ? <MonoValue value={value} /> : null;
   const quietZone = moduleWidth * 10;
   return (
     <View
@@ -126,19 +144,33 @@ function QrPreview({
   height,
   moduleWidth,
   showText,
+  textFallback,
 }: {
   value: string;
   height: number;
   moduleWidth: number;
   showText: boolean;
+  textFallback: boolean;
 }) {
   const matrix = encodeQr(value);
-  if (!matrix) return <MonoValue value={value} />;
-  // Natural module size until the host's height bound clamps the square —
-  // then every module shrinks uniformly so the symbol stays square (LC-10).
+  if (!matrix) return textFallback ? <MonoValue value={value} /> : null;
+  // A module must land on a WHOLE pixel. A fractional module width rounds to
+  // different widths across the grid, so a decoder cannot resample the symbol —
+  // measured on the media-11 board at DPR 2: the 33px square (1.000 px/module)
+  // decoded and the 44px one (1.333 px/module) did not, in either scheme. So
+  // the module is the largest whole pixel that fits, capped by `moduleWidth`
+  // and by the host's `height` bound (LC-10 — the square never exceeds its
+  // host, and the bound is a ceiling, never a target).
   const totalModules = matrix.size + 2 * QR_QUIET_ZONE_MODULES;
-  const edge = Math.min(totalModules * moduleWidth, height);
-  const cell = edge / totalModules;
+  const cell = Math.floor(Math.min(moduleWidth, height / totalModules));
+  // Under one whole pixel there is no readable symbol to draw at all. Fall
+  // back to the value as text, the same honest contract the over-capacity and
+  // non-ASCII cases have: a symbol no reader can resample is decoration, and
+  // decoration that looks like data is the one thing this component refuses to
+  // paint. This is what a `compact` bound (24) or a table-row bound does to
+  // anything past a short SKU.
+  if (cell < 1) return textFallback ? <MonoValue value={value} /> : null;
+  const edge = cell * totalModules;
   const quietZone = cell * QR_QUIET_ZONE_MODULES;
   const rows = qrRowRuns(matrix);
   return (